API Documentation

​💬
 Introduction
​Desk360 API is a Representational State Transfer (REST) ​​structure that provides operations such as:

◾
Reading
◾
Modifying
◾
Adding data
◾
Deleting data

from your help desk.
Desk360 APIs also support Cross-Origin Resource Sharing (CORS).
​✨
 HTTP Methods
The list of API commands used by Desk360
Command
Description
GET
Fetches object(s)
POST
Creates an object
PUT
Updates/Modifies an object
All API requests must reach the secure endpoint i.e. HTTPS only
​💨
 Rate Limit
This rate limit applies are based on IP address.
The limits will be company based rather than IP based in the future.
Plan
Rate Limit/Minute
Basic
10
Business
100
Enterprise
Up to your demand. For further requests, contact us.
Make sure to apply the rate limit-best practices and it stays within the rate limit.
Make sure to make API calls in a safe layer such as your backend, not front-end or your mobile application.
Remind that even invalid requests are included in the rate limit.
Check your current rate limit status by looking at the following HTTP headers returned in response to each API request:
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 180
X-RateLimit-Remaining: 178
Title
Description
X-RateLimit-Limit
Total number of API calls allowed per minute.
X-RateLimit-Remaining
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The reset time in Unix epoch time format.
Retry-After
The number of seconds you should wait in order to trigger your next API request.
This header is returned only when the rate limit is reached.
If your API request is received after the rate limit is reached, Desk360 will return an error in the response. The Retry-After value in the response header will tell you how long to wait before sending another API request.
HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 26
​🚀
 Getting Started
​🔒
 Authentication
Who can access my helpdesk? Can anyone see my data?
Before prioritizing a ticket or responding to a customer or using any of the APIs listed above, you must authenticate or log in as you sign in to your helpdesk web portal.
To authenticate the request, you can use your personal. You can access this API key directly from the panel, or you can obtain your API token with a request with your username and password.
All Desk360 API endpoints (except login) need this token in order to respond to your request.
Option 1: Obtain your token with a request.
If you enable password access from your Desk360 Panel / Settings / API you can directly use v1/login endpoint in order to create/obtain an API token. This API will return an API token if it is already created, if not it will auto-generate a token and returns it.
To make it secure, the maximum wrong login attempt is fixed to 5 per minute.
Correct attempts do not affect the limits.
get
https://api.desk360.com
/v1/login
Login
cURL
C#
Java
JavaScript
PHP
Python
curl --location --request POST 'https://api.desk360.com/v1/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "YOUR_PASSWORD"
}'
var client = new RestClient("https://api.desk360.com/v1/login");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n    \"email\": \"[email protected]\",\n    \"password\": \"YOUR_PASSWORD\"\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"email\": \"[email protected]\",\n    \"password\": \"YOUR_PASSWORD\"\n}");
Request request = new Request.Builder()
  .url("https://api.desk360.com/v1/login")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
var axios = require('axios');
var data = JSON.stringify({"email":"[email protected]","password":"YOUR_PASSWORD"});
​
var config = {
  method: 'post',
  url: 'https://api.desk360.com/v1/login',
  headers: { 
    'Content-Type': 'application/json'
  },
  data : data
};
​
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.desk360.com/v1/login');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "email": "[email protected]",
    "password": "YOUR_PASSWORD"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
import requests
​
url = "https://api.desk360.com/v1/login"
​
payload="{\n    \"email\": \"[email protected]\",\n    \"password\": \"YOUR_PASSWORD\"\n}"
headers = {
  'Content-Type': 'application/json'
}
​
response = requests.request("POST", url, headers=headers, data=payload)
​
print(response.text)
​
Option 2: Create a token from Panel
1.Login to your Desk360 Panel.
2.Go to Settings.
3.Click API.
4.Create a token for a user.
​📎
 Attachments
The following endpoints are supported with attachments:
​◾
Replying to a ticket
◾
Adding a note to a ticket
Please follow the guidelines listed below:
Only files on a local machine can be added using the API. You can not use links!
Content-Type should always be multi-part/form-data for attached requests.
​❌
 Errors
I received an error. How can I solve it?
API requests that cause errors will return an appropriate HTTP status code to help determine the type of error. You can use the following table to understand what each code means:
HTTP Status Code
Status Code Definition
Description
400
Client or Validation Error
The request body/query string is not in the correct format.
For example, the Create a ticket API requires the email field to be submitted as part of the request, and if it is missing, this status code is returned.
401
Authentication Failure
This indicates that the Authorization field is either missing or incorrect.
Check Authentication for more information.
404
Requested Resource not Found
The request contains an invalid ID / Desk360 domain or invalid parameters in the URL.
For example, an API call to retrieve a ticket with an invalid ID will return an HTTP 404 status code to inform you that no such ticket exists.
405
Method not allowed
This API request has used the wrong HTTP method.
For example, a DELETE requested on /products endpoint will return an HTTP 405 as /products allows only GET requests.
406
Unsupported Accept Header
Only application/json and */* are supported. When uploading files multipart/form-data are supported.
415
Unsupported Content-type
Only application/json is supported.
429
Rate Limit Exceeded
The API rate limit allowed for your Desk360 domain has been exhausted. Check Rate Limit.
500
Unexpected Server Error
You can't do much more here. This indicates an error on the Desk360 side. Please email us your API script with response headers. We will contact you and fix this issue as soon as possible.
Sample error response
In addition to the HTTP status code, most errors also return a response with more information to help you troubleshoot the error. An example error response is shown below. The format of the error response is explained after the example.
    "error": {
        "code": "failed_validation",
        "message": "The status field is required."
        "doc_url": "https://docs.desk360.com/api"
    }
}
Error Response Fields
Field
Description
code
Custom error code that is machine-parseable.
message
Descriptive error message.
doc_url
A link to guide you if there is a solution on the documentation.
Error Codes
Code
Description
authentication_exception
Authentication failed. The token is missing or invalid. Do not forget to put "Bearer" in the beginning of your token. eg: "Bearer YOUR-API-TOKEN"
method_not_allowed_exception
If the method and endpoint is mismatched, you will get this error. Please check the endpoint method. eg:  Products only allows GET method.
not_found_exception
You may have made a typo in your request URL.
model_not_found_exception
Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
internal_server_error
The error is coming from our servers. If you have been receiving this error message for a while, contact us.
insecure_request_exception
HTTP is not allowed. Use HTTPS instead.
too_many_requests_exception
Check Rate Limit.
invalid_credentials
You typed your email/password wrong.
password_access_disabled
You can enable password access from your Desk360 Panel Settings. Check Authentication to learn how to enable password access.
too_many_attempts
If you entered your email/password wrong more than 5 times, you should wait for a minute.
not_authorized
You do not have permission to modify the resource.
not_found
Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
status_update_failed
Status update failed. You can only set Resolved (1) or Waiting (2), also, if the ticket is resolved you can not change the reason.
facebook_integration_error
instagram_integration_error
twitter_integration_error
Check your integration is still active from your Desk360 Panel. If it is active and you getting the error, the issue might be coming from Facebook/Twitter servers.
email_error
There is an error while sending the email. The email might be invalid.
non_custom_type
You can not update/delete non-custom types.
failed_validation
This is a validation error, please read the message and apply what it says.
​📄
 Pagination
API responses that return a list of objects are paginated, for example, View Ticket List. Add the parameter page to the query string to navigate through the pages. The page number starts from 1 and each page is fixed to show 20 objects.
https://api.desk360.com/api/v1/products/1/tickets?page=1
The "Link" header in the response will be showing the next page if it exists:
Headers
"Link" : <https://api.desk360.com/v1/products/1/tickets?page=2>; rel=next
If you are on the last page the link header will not be filled.
​✅
 Best Practices
Whenever it is possible, please queue API calls on your side. This allows you to buffer recent calls to avoid reaching the rate limit. Once you reach the rate limit, retry API calls after the retry period.
Whenever it is feasible, cache the data that does not change much on your side. For example, the mapping between agent name and ID is extremely unlikely to change, so it is a useful approach to cache this data to avoid the rate limit. 
Avoid making API calls directly from a mobile app, instead, send the request to your servers and make API calls from there. This ensures that if an API endpoint is changed, you can make and deploy the change on your server instead of updating your application and forcing your customers to the latest version.
​🎫
 Products & Tickets
Apart from its competitors, Desk360 enables its customers to manage multiple products under one account. Therefore, for the ticket transactions, you must first determine the product under which you will perform these transactions. For exampleproducts/1/tickets shows tickets for the product with the Product ID 1.
In order to find your Product ID, visit Products.
get
https://api.desk360.com
/v1/products
Products
Code Samples
cURL
C#
Java
JavaScript
PHP
Python
curl --location --request GET 'https://api.desk360.com/v1/products' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
var client = new RestClient("https://api.desk360.com/v1/products");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_API_TOKEN");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.desk360.com/v1/products")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_API_TOKEN")
  .build();
Response response = client.newCall(request).execute();
var axios = require('axios');
​
var config = {
  method: 'get',
  url: 'https://api.desk360.com/v1/products',
  headers: { 
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
};
​
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
​
<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.desk360.com/v1/products',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN'
  ),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;
​
import requests
​
url = "https://api.desk360.com/v1/products"
​
payload={}
headers = {
  'Authorization': 'Bearer YOUR_API_TOKEN'
}
​
response = requests.request("GET", url, headers=headers, data=payload)
​
print(response.text)
get
https://api.desk360.com
/v1/products/:productId/tickets
Get Ticket List
Code Samples
cURL
C#
Java
JavaScript
PHP
Python
curl --location --request GET 'https://api.desk360.com/v1/products/1/tickets?page=1' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
var client = new RestClient("https://api.desk360.com/v1/products/1/tickets");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_API_TOKEN");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.desk360.com/v1/products/1/tickets")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_API_TOKEN")
  .build();
Response response = client.newCall(request).execute();
var axios = require('axios');
​
var config = {
  method: 'get',
  url: 'https://api.desk360.com/v1/products/1/tickets',
  headers: { 
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
};
​
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
​
<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.desk360.com/v1/products/1/tickets',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN'
  ),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;
​
import requests
​
url = "https://api.desk360.com/v1/products/1/tickets"
​
payload={}
headers = {
  'Authorization': 'Bearer YOUR_API_TOKEN'
}
​
response = requests.request("GET", url, headers=headers, data=payload)
​
print(response.text)
Descriptive Tables
Priority
Platform
Status
Message Types
Priority
Value
Low
0
Medium
1
High
2
Urgent
3
Platform
Value
Desk360 SDK iOS contact us tickets
iOS
AppStore review tickets
AppStore
GooglePlay review tickets
GooglePlay
Web contact us tickets
Web
Desk360 SDK Android tickets
Android
Email tickets
Mail
Facebook tickets
Facebook
Twitter mention tickets
Mention
Internal created tickets
Internal
Twitter direct message tickets
DirectMessage
Twitter retweet comment tickets
RetweetComment
Twitter tweet tickets
Tweet
Facebook messenger tickets
Messenger
Status
Value
Unresolved
0
Resolved
1
Waiting
2
Reopen
3
Type
Value
Text Message
0
GIF
1
Image
2
Video
3
External Message
4
Twitter Message
5
Note
6
Auto Reply
7
Slack
8
get
https://api.desk360.com
/v1/products/:productId/tickets/:ticketId
Get Ticket Details
Code Samples
cURL
C#
Java
JavaScript
PHP
Python
curl --location --request GET 'https://api.desk360.com/v1/products/1/tickets/1' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
var client = new RestClient("https://api.desk360.com/v1/products/1/tickets/1");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_API_TOKEN");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.desk360.com/v1/products/1/tickets/1")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_API_TOKEN")
  .build();
Response response = client.newCall(request).execute();
var axios = require('axios');
​
var config = {
  method: 'get',
  url: 'https://api.desk360.com/v1/products/1/tickets/1',
  headers: { 
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
};
​
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
​
<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.desk360.com/v1/products/1/tickets/1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN'
  ),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;
​
import requests
​
url = "https://api.desk360.com/v1/products/1/tickets/1"
​
payload={}
headers = {
  'Authorization': 'Bearer YOUR_API_TOKEN'
}
​
response = requests.request("GET", url, headers=headers, data=payload)
​
print(response.text)
​
get
https://api.desk360.com
/v1/products/:productId/tickets/:ticketId/logs
Get Ticket Logs
Code Samples
cURL
C#
Java
JavaScript
PHP
Python
curl --location --request GET 'api.localhost:10380/v1/products/1/tickets/1/logs' \
--header 'Authorization: Bearer YOUR_API_TOKEN'
var client = new RestClient("https://api.desk360.com/v1/products/1/tickets/1/logs");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_API_TOKEN");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.desk360.com/v1/products/1/tickets/1/logs")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_API_TOKEN")
  .build();
Response response = client.newCall(request).execute();
var axios = require('axios');
​
var config = {
  method: 'get',
  url: 'https://api.desk360.com/v1/products/1/tickets/1/logs',
  headers: { 
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
};
​
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
​
<?php
​
$curl = curl_init();
​
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.desk360.com/v1/products/1/tickets/1/logs',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN'
  ),
));
​
$response = curl_exec($curl);
​
curl_close($curl);
echo $response;
​
import requests
​
url = "https://api.desk360.com/v1/products/1/tickets/1/logs"
​
payload={}
headers = {

Command	Description
GET	Fetches object(s)
POST	Creates an object
PUT	Updates/Modifies an object

Plan	Rate Limit/Minute
Basic	10
Business	100
Enterprise	Up to your demand. For further requests, contact us.

Title	Description
X-RateLimit-Limit	Total number of API calls allowed per minute.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The reset time in Unix epoch time format.
Retry-After	The number of seconds you should wait in order to trigger your next API request. This header is returned only when the rate limit is reached.

HTTP Status Code	Status Code Definition	Description
400	Client or Validation Error	The request body/query string is not in the correct format. For example, the Create a ticket API requires the email field to be submitted as part of the request, and if it is missing, this status code is returned.
401	Authentication Failure	This indicates that the Authorization field is either missing or incorrect. Check Authentication for more information.
404	Requested Resource not Found	The request contains an invalid ID / Desk360 domain or invalid parameters in the URL. For example, an API call to retrieve a ticket with an invalid ID will return an HTTP 404 status code to inform you that no such ticket exists.
405	Method not allowed	This API request has used the wrong HTTP method. For example, a DELETE requested on /products endpoint will return an HTTP 405 as /products allows only GET requests.
406	Unsupported Accept Header	Only application/json and */* are supported. When uploading files multipart/form-data are supported.
415	Unsupported Content-type	Only application/json is supported.
429	Rate Limit Exceeded	The API rate limit allowed for your Desk360 domain has been exhausted. Check Rate Limit.
500	Unexpected Server Error	You can't do much more here. This indicates an error on the Desk360 side. Please email us your API script with response headers. We will contact you and fix this issue as soon as possible.

Field	Description
code	Custom error code that is machine-parseable.
message	Descriptive error message.
doc_url	A link to guide you if there is a solution on the documentation.

Code	Description
authentication_exception	Authentication failed. The token is missing or invalid. Do not forget to put "Bearer" in the beginning of your token. eg: "Bearer YOUR-API-TOKEN"
method_not_allowed_exception	If the method and endpoint is mismatched, you will get this error. Please check the endpoint method. eg: Products only allows GET method.
not_found_exception	You may have made a typo in your request URL.
model_not_found_exception	Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
internal_server_error	The error is coming from our servers. If you have been receiving this error message for a while, contact us.
insecure_request_exception	HTTP is not allowed. Use HTTPS instead.
too_many_requests_exception	Check Rate Limit.
invalid_credentials	You typed your email/password wrong.
password_access_disabled	You can enable password access from your Desk360 Panel Settings. Check Authentication to learn how to enable password access.
too_many_attempts	If you entered your email/password wrong more than 5 times, you should wait for a minute.
not_authorized	You do not have permission to modify the resource.
not_found	Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
status_update_failed	Status update failed. You can only set Resolved (1) or Waiting (2), also, if the ticket is resolved you can not change the reason.
facebook_integration_error instagram_integration_error twitter_integration_error	Check your integration is still active from your Desk360 Panel. If it is active and you getting the error, the issue might be coming from Facebook/Twitter servers.
email_error	There is an error while sending the email. The email might be invalid.
non_custom_type	You can not update/delete non-custom types.
failed_validation	This is a validation error, please read the message and apply what it says.

Priority	Value
Low	0
Medium	1
High	2
Urgent	3

Platform	Value
Desk360 SDK iOS contact us tickets	iOS
AppStore review tickets	AppStore
GooglePlay review tickets	GooglePlay
Web contact us tickets	Web
Desk360 SDK Android tickets	Android
Email tickets	Mail
Facebook tickets	Facebook
Twitter mention tickets	Mention
Internal created tickets	Internal
Twitter direct message tickets	DirectMessage
Twitter retweet comment tickets	RetweetComment
Twitter tweet tickets	Tweet
Facebook messenger tickets	Messenger

Status	Value
Unresolved	0
Resolved	1
Waiting	2
Reopen	3

Type	Value
Text Message	0
GIF	1
Image	2
Video	3
External Message	4
Twitter Message	5
Note	6
Auto Reply	7
Slack	8

API Documentation

​💬 Introduction

​✨ HTTP Methods

​💨 Rate Limit

​🚀 Getting Started

​🔒 Authentication

​📎 Attachments

​❌ Errors

Error Codes

​📄 Pagination

​✅ Best Practices

​🎫 Products & Tickets

Descriptive Tables

💬
Introduction

✨
HTTP Methods

💨
Rate Limit

🚀
Getting Started

🔒
Authentication

📎
Attachments

❌
Errors

📄
Pagination

✅
Best Practices

🎫
Products & Tickets