Table of Contents

DeskDirector API

Niamh Ferns Updated by Niamh Ferns

DeskDirector API

DeskDirector provides a set of generic and platform APIs for you to integrate with. With this, you can 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 that allows you to explore our API. To see this, navigate to https://[your-subdomain-here].deskdirector.com/swagger.

At top of the Swagger interface you can select which API version you would like to reference.

Keep in mind, even though Swagger shows the service models in pascal case, API v2 and v3 use camel case.
Versions
  • API v4: This is the newest version of our API and is under active development
  • API v3: This version of our API was made available when we moved from the legacy Admin Console to the new Admin Portal
  • API v2: This is the API you will see used for most actions in DeskDirector. It is a solid and well-supported API and is used by all our existing systems. For most users, this is what we recommend you use in your automations.
    API v2 uses camelCase for JSON response keys.
  • API v1: This API has been deprecated and is only used by our legacy systems. We do not recommend using this version and we do not provide any support for it.
    API v1 uses PascalCase for JSON response keys.
Categories
  • 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 Portal. 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.

API Authorization

Access Token

Portal and TECH users can generate access tokens with a 60 minute expiry.

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 an Access Token you will need to place it inside the Authorization header of all your HTTP requests:

Authorization: DdAccessToken {your access token here}

API Key

An API Key can be generated inside your Admin Portal. You can get this from Advanced > Developer 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.

Authorization: DdApi {your api key here}

A cookie can be used for a related platform. I.E: an end user's cookie can use against portal API and a service agent's cookie can use against TECH API or Admin API, if they have the required privileges.

Using Our API 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.

As always, please test all API requests that modify entities thoroughly before putting them into production.

Frequently Asked Questions

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

First make sure you have the API token in your query parameters. You can get this from your Admin Portal under Advanced > Developer Corner.

If you still get an unauthorized error code it means the end point requires an Access Token. You can generate an access token from your Admin Portal or send the following HTTP request:

GET /api/v2/user/member/<your member ID here>/userkey?expiresIn=<desired expiry time in seconds> HTTP/1.1
Host: <your sub domain>.deskdirector.com

Authorization: DdApi <your API key here>
Note: Access tokens expire in 60 minutes by default 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?

Webhooks

Contact