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.
- Obtain your API Key: Contact your Desk365 administrator or visit your Desk365 account settings to get your 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 both version 1 and version 2 documentation, please refer to the links below:
- v1 Documentation: https://apps.desk365.io/apis/api-docs.html?version=v1
- v2 Documentation: https://apps.desk365.io/apis/api-docs.html
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):
- New Response (with null values included):
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:
- New Response with Null Values:
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
- Use “- -” to indicate an unassigned value for the filter.
- Omit fields from the filter if you prefer not to include them in the filtering process.
- 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 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.
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.
