DeskDirector API

DeskDirector provides a set of generic APIs and platform APIs for you to integrate with.

It allows you to trigger workflows based on Webhooks (such as ticket status changes), add ticket notes on behalf of a user or modify permissions through admin API.

In this article, we will go through what is available and the authorization system.

Exploring the API's

Every DeskDirector instance has a Swagger interface which you can use to explore our API's.

You can find it at https://[your-subdomain-here].deskdirector.com/swagger

At top of the Swagger interface you can select the different API versions. Keep in mind, even though Swagger shows the service models as pascal case, for API v2 and v3 it is actually camel case.

API Versions

  • API v1 This API has been deprecated. It is used by our legacy systems. We do not recommend to use them and we do not provide any support for them. All JSON properties have been serialized as Pascal case.
  • API v2 This is our current API. It uses Camel case inside the JSON response. It is a solid and well supported API and is used by all our existing systems.
  • API v3 This API has only been created recently for the purpose of our new admin console. The legacy admin console uses API v1 and v2 but these API's have been difficult to use, thus we created the v3 branch for new admin related API's.

API category

  • Public API - In general, this API is only used for retrieving information about your DeskDirector instance or querying certain entities inside DeskDirector.
  • Admin API - These API's are used for our admin console. We have recently allowed API key to used against admin related API. API Key's role is equivalent to admin role.
  • Portal API - These API's are used by the Portal.
  • TECH API - These API's are used by TECH.
We only provide support for the Public API.

All other API's are subject to change.
Admin, Portal and TECH API's are all under active development. Deprecation of API's can happen whenever we retire pages and functionality.
This is especially true for our Admin API's as these are undergoing significant changes right now.

How to user our API's - Authorization

Access Token

Portal and TECH can generate access tokens which each last 60 minutes.

Access Tokens are leveraged by our new Menu System. Whenever a user accesses an External Site type menu item, we will pass through an Access Token inside the URL as a query parameter. Any code running on your custom page will be able to read the Access Token and use it to make API calls on behalf of the user.

Access Tokens can be used against both Portal and TECH API's (depending on which application generated the Access Token)

To use a Access Token you will need to place it inside the Authorization header of all your HTTP requests.

Please replace {access_token} with the actual token.

Authorization: DdAccessToken {access_token}

API Key

An API Key can be generated inside your Admin Console at https://[your-subdomain-here]/admin/ddapi.

The API Key can be used to access Public API's and Admin API's.

To use an API Key you will need to place it inside the Authorization header of all your HTTP requests.

Please replace {api_key} with the actual key.

Authorization: DdApi {api_key}

Cookie

Cookie can be used against related platform. End user's cookie can use against portal API, member cookie can use against TECH API or admin API if they have the required privileges.

Using our API's to update entities

The DeskDirector API provides many API's to create and update entities.

In many cases, we use PUT requests to update entities. This will completely overwrite all existing properties on the entity, with only those specified in the request.

Currently only the TECH Update Ticket API supports the PATCH operation, which will update only the properties specified in the request.

Please test all API's which modify entities thoroughly before putting them into production.


How did we do?