DeskDirector API

Jason He Updated by Jason He

DeskDirector provides a set of generic 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 APIs

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 using 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 APIs 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 use our APIs - 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 APIs (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. You can get this from Advanced => Developer's Corner.

https://{subdomain}.deskdirector.com/admin/v2/advanced/deskdirector-api

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 APIs 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 APIs which modify entities thoroughly before putting them into production.

FAQs:

Q. I am using Postman to access your Desk Director API's and I'm getting "errorCode": "Unauthorized"

First make sure you have the `api_key` in your query parameters. You can get this from your Admin Portal => Advanced => Developer's Corner

If you still get an unauthorized error code it means the end point requires an Access Token. You can retrieve these by logging into your DD instance from your Browser => Dev Tools => Network Tab => Config => Token.

Note: Access tokens expire in 60 minutes and there is no way to generate a permanent access token.

Now that you have the token, create an Authorization header in your http request:

* Key Authorization

* Value DdAccessToken {access_token}

How did we do?

Subscribing to Chat Webhooks

Contact