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.
- 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 version 3, version 2 and version 1 documentations, please refer to the links below:
- v3 Documentation: https://yourdomain.desk365.io/apis/api-docs.html
- v2 Documentation: https://apps.desk365.io/apis/api-docs.html?version=v2
- v1 Documentation: https://apps.desk365.io/apis/api-docs.html?version=v1
Versioning with 'v3' 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 v3 in the ‘Request URL’ to ensure compatibility with the latest updates.
By using the v3 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?
- v3 API Request URL (addition of v2 in the URL): https://<<yoursubdomain>>.desk365.io/apis/v3/endpoint
- v2 API Request URL: https://apps.desk365.io/apis/v2/endpoint
- v1 API Request URL: https://apps.desk365.io/apis/endpoint
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 yourcompany.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 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.
- 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 /update and /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.
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.
1. 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
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.
