1. Home
  2. Docs
  3. Integrations
  4. Learn about Desk365&#8217...
  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 2.

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. 

authorize-enable-api-key-desk365

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

desk365-accessing-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 both version 1 and version 2 documentation, please refer to the links below:

Versioning with 'v2' in the Request URL

Desk365’s new version of the API enhances functionality, improves data consistency, and introduces new features. When accessing the new API endpoints, it is essential to include v2 in the ‘Request URL’ to ensure compatibility with the latest updates. 

By using the v2 versioning in the URL, you ensure that your requests are directed to the latest version of the API, which includes the below improvements and any additional enhancements introduced in the future. 

What's the difference?

  • v1 API Request URL (no change from initial URL): https://apps.desk365.io/apis/endpoint
  • v2 API Request URL (addition of v2 in the URL): https://apps.desk365.io/apis/v2/endpoint

What's New in Version 2?

In Version 2, we have made significant updates to how our API handles empty fields and null values. Fields with null values will now be included in the API response, and fields that previously contained empty strings will be converted to null values. These changes enhance data consistency and clarity in our API responses. 

1. Inclusion of Null Values

We have recently updated our API to improve how it handles empty fields. Previously, fields with null values were removed from the API response, and only fields with actual values were displayed. With the upcoming change, fields with null values will be included in the response, explicitly showing the fields with a null value. 

Example of the Change

  • Previous Response (when assigned to value is empty): 
assigned-value-is-empty-desk365
  • New Response (with null values included): 
new-response-with-null-values-desk365

2. Handling of Empty Strings

Fields that previously contained empty strings will now be converted to null values. This ensures consistency in how we represent missing or empty data across our API. 

Example of the Change

Here is an example demonstrating the change: 

  • Previous Response with Empty Strings: 
response-with-empty-string-desk365
  • New Response with Null Values: 
new-response-with-null-values-desk365-string

By using null instead of an empty string, the API ensures that the absence of data is explicitly and consistently indicated. 

Impact on Your Integration

  • Inclusion of Null Values: You may need to update your code to handle the presence of null values in the response if your current implementation does not already account for this. 
  • Empty Strings to Null: Ensure that your application can properly handle fields that were previously empty strings now being represented as null. 

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.

Survey-endpoints-Desk365

Retrieving All Survey Details

The first endpoint we’ll look at is the /v2/surveys endpoint. This API call is used to retrieve a list of all surveys in the system, ordered by their creation time in ascending order. It’s a simple yet powerful way to gather a comprehensive list of surveys without needing any 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. 

get-survey-details-Desk365

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. 

get-survey-details-Desk365

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. 

List-all-survey-ratings-Desk365

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?