1. Home
  2. Docs
  3. Integrations
  4. Learn about Desk365 integ...
  5. Enhancing Your Application with the Desk365 API

Enhancing Your Application with the Desk365 API

Desk365’s API allows seamless integration with applications such as Asana, Jira, etc., providing enhanced functionality and streamlined processes. This guide will help you get started with the Desk365 API, covering everything from obtaining your API Key to understanding the latest updates in Version 3.

By following this guide, you will be able to effectively utilize the Desk365 API to improve your workflow and productivity.

Getting started

To start using the Desk365 API, you first need to obtain an API Key. This key serves as the authorization token for all API requests. 

  1. Obtain your API Key: Contact your Desk365 administrator or visit your Desk365 account settings to get your API Key. 
accessing-desk365-api-key

2. Authorize: Click on the ‘Authorize’ button in the API interface and enter your API Key. 

3. Access the endpoints: Once authorized, you can access all the endpoints.  

Please note that when using the API in your code, you should add the API Key in the “Authorization” header of your HTTP request.

Desk365 API versioning: Access the latest API documentation

For detailed information on Desk365’s API functionalities and to access version 3, version 2 and version 1 documentations, please refer to the links below: 

Important note: 

Please note that support for API versions 1 and 2 will end soon, and only Version 3 will be maintained in the future. To ensure compatibility, upgrade your integrations to use Version 3 of Desk365 APIs. 

What’s new in Desk365 API version 3?

Desk365’s API version 3 is designed to offer more flexibility, better performance, and enhanced data access. Whether you’re an existing user or just getting started, this guide will walk you through the new features and improvements in Version 3. 

1. OpenAPI specification for standardized documentation

The Desk365 API documentation now follows the OpenAPI Specification, a globally recognized standard for defining APIs. 

What does this mean for you? 

  • Easier integration with tools like Postman, Swagger UI, or your development environment. 
  • Better clarity and consistency across the API documentation. 
  • Simplified understanding of request and response structures. 

With OpenAPI, working with Desk365’s API is now more straightforward, regardless of your technical expertise. 

2. Subdomain access for enhanced security

We’ve introduced subdomain-based access to make API usage more secure and personalized. 

Key changes: 

  • Instead of the old apps.desk365.io, API calls will now go through your own subdomain like yoursubdomain.desk365.io. 
  • Each subdomain has its own unique API Key, which ensures that only authorized users can access data for that specific subdomain. 
  • Your API key is valid only when accessing the documentation under your designated subdomain 

This change adds a layer of security and ensures that your API calls are better aligned with your account’s unique setup. 

3. Updated request URL format with /v3

API requests must now include /v3 in the URL to ensure you’re using the latest version. 

New URL format example: 

https://<<yoursubdomain>>.desk365.io/apis/v3/tickets  

Including /v3 ensures you access all the improvements and new features exclusive to Version 3. 

4. Retrieve details up to 10,000 tickets per call with enhanced pagination

Version 3 brings a significant improvement to how many tickets you can retrieve in one call. 

What’s new? 

  • You can now choose to retrieve 30, 50, or 100 tickets per call in the ‘List all tickets’ response using the ticket_count parameter. 
  • The maximum number of tickets you can access in one session has increased to 10,000 tickets per hour. 

This means faster data access and more efficient ticket management, especially for teams handling large volumes of support queries. 

5. Custom fields now use ‘cf_’ prefix

Custom fields in Version 3 have been standardized for better clarity. 

Key updates: 

  • When you retrieve tickets, custom fields now appear with a cf_ prefix (e.g., cf_department, cf_employee_id). 
  • When sending data, you’ll also need to prefix custom field names with cf_ in your requests like v3/tickets/update and v3/tickets/create. 

This change ensures consistency in how custom fields are identified and used, making integrations cleaner and easier to maintain. 

6. SLA names included in ticket details

With Version 3, ticket responses now include SLA (Service Level Agreement) names, providing more context about the service expectations for each ticket. 

Why is this important? 

  • You can see which SLA applies to each ticket directly in the API response. 
  • This information helps in tracking SLA compliance and improving response times. 

Including SLA names in ticket data allows for better reporting and performance monitoring, making it easier to meet your support goals. 

The new features in Version 3 are designed to make your API experience smoother, faster, and more secure. With OpenAPI documentation, subdomain access, better ticket retrieval options, and improved field handling, Version 3 sets the foundation for seamless integrations and enhanced productivity. 

Integrate Desk365 with other applications using the Desk365 API.

Explore our endpoints ranging from

Tickets

Contacts

Companies

Time entries

Surveys

Contracts

Understanding Desk365 API

Fields with null values and empty strings are converted to null values and included in API response enhancing data consistency and clarity in our API responses.

Inclusion of null values

In Desk365 API, fields with null values are included in the response, explicitly showing the fields with a “null” value.

Example

new-response-with-null-values-desk365

Adding filters and retrieving tickets

When retrieving tickets using the Desk365 API, the default result shows all tickets sorted by the date they were created, from newest to oldest. However, you can narrow down your search by using filters.

How to use filters?

You can filter tickets by several attributes, such as: 

  • Status (e.g., Open, Pending) 
  • Priority (e.g., 1, 10) 
  • Type (e.g., Printer ‘Out of Ink’ Complaint, Customer’s Request) 
  • Group (e.g., “Sales” Department, “Marketing” Department) 
  • Assigned To (e.g., agent email like user1@example.com“, “user2@example.com) 
  • Category (e.g., Hardware, Software) 
  • Subcategory (e.g., Printer, Laptop) 
  • Source (e.g., 1, 6) 
  • Contact (e.g., customer email like “customer1@example.com”, “customer2@example.com 

Each filter should be an array of string values. Ensure that double quotes, single quotes, and backslashes within the strings are properly escaped with a backslash i.e., \” for a double quote, \’ for a single quote or \\ for a backslash.  

Here’s an example of a sample filter with properly escaped attributes: 

{ 

  “status”: [“Open”, “Pending”], 

  “priority”: [“1”, “10”], 

  “type”: [“Printer ‘Out of Ink’ Complaint”, “Customer’s Request”], 

  “group”: [“\”Sales\” Department”, “\”Marketing\” Department”], 

  “assigned_to”: [“user1@example.com”, “user2@example.com”], 

  “category”: [“Hardware”, “Software”], 

  “subcategory”: [“Printer”, “Laptop”], 

  “source”: [“1”, “6”], 

  “contact”: [“customer1@example.com”, “customer2@example.com”] 

}

Note
  1. Use “- -” to indicate an unassigned value for the filter. 
  1. Omit fields from the filter if you prefer not to include them in the filtering process. 
  1. If you use external programs to access the Desk365 API, ensure that the request URL is encoded in UTF-8 format. 

These filters help you retrieve tickets based on specific criteria, making it easier to manage and respond to them efficiently. 

Filters overview

Attribute

Type

Description

status

Array of strings

Filters tickets by their status, e.g., ["Open", "Pending"].

priority

Array of strings

Filters tickets based on priority levels, e.g., ["1", "10"] where "1" is Low and "10" is Urgent.

type

Array of strings

Filters tickets based on their type, e.g., ["Printer 'Out of Ink' Complaint", "Customer's Request"]. Escaped single quotes are used properly.

group

Array of strings

Filters tickets assigned to certain groups, e.g., ["\"Sales\" Department", "\"Marketing\" Department"].

assigned_to

Array of strings

Filters tickets based on the agents assigned to them by email, e.g., ["user1@example.com", "user2@example.com"].

category

Array of strings

Filters tickets by category, e.g., ["Hardware", "Software"].

subcategory

Array of strings

Filters tickets by subcategory, e.g., ["Printer", "Laptop"].

source

Array of strings

Filters tickets by the source of the ticket, e.g., ["1", "6"] where "1" represents Email and "6" represents Support Portal.

contact

Array of strings

Filters tickets based on the contact’s email address, e.g., ["customer1@example.com", "customer2@example.com"].

Additional parameters

In addition to the basic filters, Desk365 API provides several advanced options to customize the response. 

Attribute

Type

Description

include_custom_fields

String

Includes custom ticket fields in the response.

include_description

String

Adds the ticket description to the response.

include_survey_details

String

Includes survey ratings in the response. Only the latest survey rating will be included.

nested_fields

String

If set to 1, custom fields and survey details will not appear in a nested structure.

offset

String

Helps paginate through the ticket list.

order_by

String

Specifies the field to order by

order_type

String

Specifies the sort order, either ascending or descending.

updated_since

String

Only tickets updated after the given timestamp will be returned.

Fixed numerical values

The response contains fixed numerical values for specific fields.  

Field

Numeric Value

Description

Priority

1 (Low), 5 (Medium), 10 (High), 20 (Urgent)

Priority levels for filtering tickets.

Source

1 (Email), 5 (Microsoft Teams), 6 (Support Portal), 7 (Phone/Other), 12 (Web Form), 13 (Web Widget)

Indicates the source from which the ticket was created.

Survey Type

1 (Customer Satisfaction), 2 (Five Star Rating), 3 (Net Promoter Score)

Different types of survey responses.

Survey Rating

-3 to 3

Values for Customer Satisfaction survey responses. Ratings are mapped to text using the sv_name field in the survey details endpoint.

Survey data retrieval

Desk365 offers powerful Survey APIs that are essential for enhancing any customer support or feedback system. These APIs streamline the collection, management, and analysis of customer feedback in an organized and automated manner. We’ll delve into three key Survey API endpoints provided by Desk365 and discuss their roles in effectively managing survey data.

Retrieving all survey details

The first endpoint we’ll explore is the /surveys endpoint. This API call retrieves a list of all surveys in the system, organized by their creation time in ascending order. It’s a straightforward yet effective method to gather a complete list of surveys without requiring specific parameters.

Key constants: 

  • survey_type: Represents the type of survey being queried. 

                            1 = Customer  Satisfaction 

                            2 = Five Star Rating 

                            3 = Net Promoter Score 

  • cs_rating_order: Defines the order in which ratings are presented. 

                            1 = Good to Bad 

                            2 = Bad to Good 

  • cs_neutral_type: Specifies the categorization method for ‘Neither satisfied nor dissatisfied’ in reports. 

                             1 = Positive 

                             2 = Neutral 

                             3 = Negative 

  • notify_type: Describes the trigger for survey notifications. 

                             7 = Ticket resolved 

                             8 = Ticket closed 

This endpoint is ideal for getting a quick overview of all surveys currently in the system. 

Fetching survey details by name

Sometimes, you may need detailed information about a specific survey. The /v2/surveys/details endpoint serves this purpose by allowing you to fetch detailed information for a given survey name. This is particularly useful when you need to drill down into the specifics of a survey, such as its structure, questions, and configurations. However, it is important to note that deleted surveys cannot be retrieved through this endpoint. 

Key parameters: 

  • survey_name (required): The name of the survey for which details are being requested. 

Key constants: 

The constants are similar to those in the /v2/surveys endpoint but also include: 

  • cs_neutral_type: Adds a layer to classify responses into Positive, Neutral, or Negative categories. 

                             1 = Positive 

                             2 = Neutral 

                             3 = Negative 

This endpoint is particularly useful for retrieving in-depth information about a specific survey, which can be crucial for analysis and reporting. 

Accessing survey ratings

The /v2/surveys/ratings endpoint allows you to retrieve all survey ratings, again ordered by their creation time in ascending order. This endpoint is a valuable tool for collecting feedback data, which can be used for performance metrics, customer satisfaction tracking, and improving service quality. 

Key constants: 

  • survey_type: 

                              1 = Customer Satisfaction 

                              2 = Five Star Rating 

                             3 = Net Promoter Score 

  • cs_neutral_type: 

                             1 = Positive 

                             2 = Neutral 

                             3 = Negative 

This endpoint provides a straightforward way to gather all rating data for analysis. 

Each endpoint serves a specific purpose, from retrieving all surveys to getting detailed information about a particular survey, and finally, accessing survey ratings.

Survey retrieval and key attributes

  • We have enhanced the functionality to retrieve survey details in the “get all tickets” endpoint. If include_survey_details is set to 1, survey details for each ticket can be retrieved within the same endpoint, making it easier for you to associate survey details with each ticket
  • When multiple surveys are created from the same domain, only the latest responded survey will be retrieved.
  • If no survey has been sent to the contact, survey_ratings object will be null. If a survey has been sent but not responded to, the details will still be populated, but the ratings will be null.
  • Attributes prefixed with cs are specific to customer satisfaction surveys.
  • Survey details are prefixed with sv, indicating various survey-related data points.

Sample response body

  “count”: 150, 

  “tickets”: [ 

    { 

      “ticket_number”: 10, 

      “contact_email”: “test@gmail.com”, 

      “subject”: “Printer not working”, 

      “description”: “<div>Please fix it</div>”, 

      “description_text”: “Please fix it”, 

      “status”: “open”, 

      “priority”: 5, 

      “type”: “Question”, 

      “source”: “1”, 

      “assigned_to”: “agent@gmail.com”, 

      “group”: “Sales”, 

      “category”: “Billing”, 

      “sub_category”: “Disputed Charge”, 

      “created_on”: “2023-01-01 00:00:00”, 

      “updated_on”: “2023-01-02 00:00:00”, 

      “resolved_on”: “2023-01-03 00:00:00”, 

      “closed_on”: “2023-01-04 00:00:00”, 

      “due_date”: “2023-01-03 00:00:00”, 

      “first_response_time”: “2023-01-02 00:00:00”, 

      “first_assigned_time”: “2023-01-02 00:00:00”, 

      “first_assigned_duration”: 1440, 

      “resolved_duration”: 2880, 

      “first_replied_duration”: 1440, 

      “closed_duration”: 4320, 

      “custom_fields”: { 

        “department”: “string”, 

        “dob”: “string”, 

        “employee_id”: 0 

      }, 

      “survey_rating”: { 

        “sv_name”: “Test survey”, 

        “sv_answered”: true, 

        “sv_type”: 1, 

        “sv_cs_scale”: 7, 

        “sv_cs_neutral_type”: 2, 

        “sv_question”: “How would you rate our customer service?”, 

        “sv_rating”: 3, 

        “sv_cs_question_2”: “How would you rate our expertise?”, 

        “sv_cs_rating_2”: 3, 

        “sv_cs_question_3”: “How would you rate your overall satisfaction with the help you’ve received?”, 

        “sv_cs_rating_3”: 3, 

        “sv_additional_comments_title”: “Add any additional comments you may have about the support received”, 

        “sv_additional_comments_response”: “Good customer service”, 

        “sv_sent_on”: “2023-10-01 00:01:00”, 

        “sv_rated_on”: “2023-10-02 00:01:30” 

      } 

    } 

  ] 

Rate limit details

The Desk365 API has a rate limit in place to ensure fair usage and system stability. The current rate limit allows for 100 API calls per hour per API key. 

By following this guide, you should be able to effectively utilize the Desk365 API to integrate with various applications, enhancing your workflow and productivity.  

Require additional assistance? Please reach out to us at help@desk365.io

How can we help?