Zoho Desk APIs facilitate integration with other Zoho applications and third-party tools by adhering to RESTful principles. These APIs enable you to programmatically fetch and edit data in the different modules in Zoho Desk, such as Tickets, Contacts, Accounts and so on. All the APIs follow HTTP rules and error codes. To keep yourself updated about the changes in our APIs, follow the Zoho Desk Developer APIs forum.
API Root Endpoint
desk.zoho.com/api/v1
All Zoho Desk APIs require these two mandatory fields in the header.
Authorization - Authentication request tokenorgId -ID of the organization to access. All API endpoints except /organizations mandatorily require the orgId.Example
$ curl -X GET https://desk.zoho.com/api/v1/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
Zoho Desk APIs enable data manipulation and retrieval through different HTTP methods.
| Method | Purpose |
|---|---|
| GET | Retrieve resources |
| POST | Create resources and perform resource actions |
| PUT | Update resources |
| PATCH | Partially update resources |
| DELETE | Delete resources |
Using the GET method, you can get a list of resources or details of a particular instance of a resource.
To get a list of tickets
$ curl -X GET https://desk.zoho.com/api/v1/tickets
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
To get the details of a ticket referred to by a specified ticket_id
$ curl -X GET https:// desk.zoho.com/api/v1/tickets/903000000000099
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
Zoho Desk uses HTTP status codes to indicate success or failure of API calls. Status codes in the 2xx range indicate success, 4xx range indicate error in the information provided, and 5xx range indicate server side errors. The following table lists some commonly used HTTP status codes.
| Status Code | Description |
|---|---|
| 200 | OK |
| 201 | Created |
| 204 | No content |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden (Unauthorised access) |
| 404 | URL not found |
| 405 | Method not allowed (Method called is not supported for the API invoked) |
| 413 | Payload Too Large |
| 415 | Unsupported Media Type |
| 422 | Unprocessable Entity |
| 429 | Too Many Requests |
| 500 | Internal error |
Besides HTTP status codes and their corresponding error messages, error responses for Zoho Desk APIs also include a machine-parsable errorCode param to simplify error handling.
The different errorCodes and their uses are described below.
This errorCode value appears if the authentication token in the API request is invalid
This errorCode value appears if the OAuthToken is invalid or expired.
This errorCode value appears if the OAuthToken does not contain the scope required to perform the operation.
This errorCode value appears if the user chooses a different organization while generating the OAuthToken instead of the organization in which they want to perform the operation.
This errorCode value appears if the user does not have all the permissions required to access the resource.
This errorCode value appears if the user is unable to perform an action due to the limitations of the Zoho Desk edition in use
The possible values for the feature key are
AGENTSLIGHT_AGENTSTEAMThe possible values for the editionType key are
FREEEXPRESSSTANDARDPROFESSIONALENTERPRISEThis errorCode value appears if the URL provided is invalid or does not exist.
This errorCode value appears if the method in the API request is known by the server but disabled for the API requested.
This errorCode value appears if the size of the resource exceeds the limit defined by the server.
This errorCode value appears if the server refuses the request as a result of receiving the input in an unsupported format.
This errorCode value appears if there are inaccuracies, such as duplicate entries or invalid IDs, in the data given by the user. The type of inaccuracy is identified by the errorType param.
The possible values for the errorType key are:
The field that contains the inaccurate value is returned in the fieldName param, which is represented in the JSON Pointer convention
This errorCode value appears if the input does not fulfil the conditions necessary for successfully executing the API.
This errorCode value appears if the API request tries to remove the last user remaining in a department that has live chat enabled
This errorCode value appears if the user creates a contract for an SLA with existing or overlapping time periods.
This errorCode value appears when the Extension API fails to process a request due to an exception received from an external service such as Sigma, DRE, or the Marketplace.
The errorDetails provide information about the source and cause of the failure:
This errorCode value appears if the API request tries to deactivate a user who has enabled integrations in the help desk portal
The integration param returns the integration the user enabled in the portal. The possible values are :
LIVECHATThis errorCode value appears if the user sends too many requests within a given amount of time ("rate limiting").
This errorCode value appears if the user fires too many requests in a simultaneous/concurrent manner ("rate limiting").
This errorCode value appears if the server encounters an unexpected condition that prevents it from fulfilling the request.
Request Example
$ curl -X GET https://desk.zoho.com/api/v1/tickets/700000007942
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60"
Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
UnAuthenticatedErrorResponse
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Oauth Error Response
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
ScopeMisMatch Error Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
OAuth Org Mismatch Error Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Forbidden Error Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
LicenseAccessLimited Error Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Url Not Found Error Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Method Not Allowed Error Response
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8
Resource Size Exceeded Error Response
HTTP/1.1 413 Payload Too Large
Content-Type: application/json;charset=UTF-8
Unsupported Media Type Error Response
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json;charset=UTF-8
Invalid Data Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Unprocessable Entity Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Unprocessable Entity Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Unprocessable Entity Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Unprocessable Entity Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Unprocessable Entity Error Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Threshold Exceeded Error Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8
Concurrent Rate Limit Exceeded Error Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8
Internal Server Error Response
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
In Zoho Desk, you can fetch multiple resources using listing APIs, such as list tickets , list agents and list departments and so on. The retrieval and arrangement of these resources on end-users' screen is called pagination. Pagination in listing APIs is made possible by two parameters: from and limit
| Attributes | Description |
|---|---|
| from | from indicates the offset from which the records is to be fetched the default value of from parameter is 1 |
| limit | limit indicates the number of records the API must fetch. The default value of limit will be 10. A single API request can fetch a maximum of 50 resources. However, some APIs support higher limits, which is mentioned in the API document, wherever applicable |
The paginated responses are retrieved in the form of JSON objects that contain a key called data and a JSON array of resources (objects) as the value.
Request Example with pagination
$ curl -X GET 'https://desk.zoho.com/api/v1/accounts?from=1&limit=1'
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
-H "featureFlags:multiLayout,ticketTeam"
Response Example:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"data" : [ {
"website" : "112121",
"accountName" : "Admin Account",
"phone" : "121212",
"webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
"createdTime" : "2015-02-16T16:57:44.000Z",
"zohoCRMAccount" : {
"id" : "32754000000537001"
},
"customerHappiness" : {
"badPercentage" : "30",
"okPercentage" : "30",
"goodPercentage" : "40"
},
"id" : "1892000000052077",
"email" : "admin@zylker.com"
} ]
}Zoho Desk enables you to retrieve different related resources through a single API request, which is made possible by the include query param. This query param takes a comma separated list of values corresponding to the API.
Backwards Compatibility on api changes is always maintained. Minor api changes like field, URL, query param deprecation will be notified via forum with a transistion period. Support will be revoked after the end of transition period. Only major api interface change will involve the version number in the URL to change.
An OpenAPI Specification (OAS) is an industry-standard way to describe RESTful APIs. It provides a clear, structured way to define authentication methods, endpoints, request parameters, and response formats. OpenAPI specification is written either in JSON or YAML, making them both machine-readable and easy for developers to interpret.
OpenAPI 3.1.0 provides a standardized and structured approach that helps developers understand, use, and integrate APIs more effectively. It is designed to provide:
The OpenAPI Specification (OAS) for Zoho Desk APIs is hosted on GitHub:
Zoho Desk's OAS files are designed to provide a generic representation of standard API endpoints, request/response structures, and supported HTTP methods. They do not include application-specific business logic.
For example, each module may require different input data for specific scenarios. However, the generic design may not fully capture your application-specific requirements. Developers are expected to identify such gaps, plan accordingly, and extend or adapt the specifications to fit their use cases during integration.
Every time you make an API call in Zoho Desk, it uses up API credits. These credits help control usage and ensure system performance stays stable.
The number of credits used depends on what kind of operation you're performing. Simple actions use fewer credits, while complex actions use more.
Every Zoho Desk edition comes with a set of base credits by default. Additional credits are also provided based on the number of users you have purchased, excluding light agents.
| Edition | Base Credits + Additional Credits per User |
|---|---|
| Free/ Trial period | 5,000 + 0 |
| Express | 25,000 + 100/User |
| Standard | 50,000 + 250/User |
| Professional | 75,000 + 500/User |
| Enterprise/Zoho One/CRM Plus | 100,000 + 1,000/User |
For example, if a portal is using the Professional edition and has 50 users.
Here is a calculator to find the available credit limits based on your edition and the number of users.
API credits are tracked on a 24-hour cycle, from 00:00 to 23:59:59, based on the timezone of your data center. These credits reset every 24 hours.
Once you have used up all your base and user credits, you can purchase additional credits
Note:Unused credits will expire after the 24-hour period ends.
You can view the daily base credits available to your organization by navigating to Setup > Developer Space > APIs.
You can easily track your credit usage by checking this section. It provides a detailed breakdown showing how many credits have already been consumed and how many are still available for use.
Note:API credit usage is presented for the current day. Please allow up to 15 minutes for the latest usage information to be updated.
In addition to API credits, Zoho Desk also uses a concurrency system to manage API usage. Concurrency limits define the maximum number of API calls that can be active at the same time from a portal
These limits differ based on your Zoho Desk edition.
| Edition | Concurrency Limits |
|---|---|
| Free/ Trial period | 5 |
| Express | 10 |
| Standard | 10 |
| Professional | 15 |
| Enterprise/Zoho One/ CRM Plus | 25 |
If you exceed the allowed concurrency limit, you will receive an error message, as shown
In such cases, you can terminate (kill) some ongoing API calls to continue.
Since concurrency is based on the number of simultaneous active calls, each active API call still consumes credits as usual.
You can make as many API calls as needed per minute, as long as the number of active calls at any given time stays within your editions concurrency limits.
Error response
{
"errorCode": "TOO_MANY_REQUESTS",
"message": "The maximum number of Concurrent API Calls that can be made has been exceeded."
}
Desk uses two types of credit consumption models depending on the nature of the API
The number of credits consumed remains fixed, regardless of how much data is processed.
API: Fetch a single record
Credit: 1 credit/ call
This credit consumption depends on how many records you are working with or how intensive the operation is.
When adding, updating, or deleting multiple records in a single API request, credits are consumed based on the number of records processed.
Simply, More records = More credits used
Each API has a defined configured credit value, and the total credit consumption is calculated using a formula
| Operation | Defined credit |
|---|---|
| Update multiple records | 1 credit for every 2 records |
| Delete multiple records (Move records to trash) | 6 credits per record |
| Restore records from the recycle bin | 6 credits per record |
| Execute generic action | 1 credit per record Note: If the record ID is not specified, 50 credits will be consumed by default. |
For example, updating 50 records will use 25 credits. Restoring 50 records from the recycle bin will consume 300 credits.
When you fetch multiple records, credits are consumed based on the range of records retrieved. The larger the range, the more credits are used. This applies to APIs that search for or fetch a large number of records. The credit usage increases with the number of records processed.
For example, if an API is invoked with parameters from=5 and limit=50, it will retrieve 50 records starting from index 5 (i.e., records 5 to 54). Since these records are near the beginning of the dataset, the operation is lighter and will consume around 3 credits.
However, fetching the same number of records from a much later point. For example, from index 10,005 to 10,054 is more resource-intensive and may consume up to 50 credits.
All APIs support a maximum of 50 records per request. The deeper the data range, the higher the credit consumption.
Note:Fetching a record by its ID or number (e.g., Ticket ID or Ticket Number) counts as a single record. Only one credit will be consumed.
In Zoho Desk, you can increase your API credits beyond the base credits provided with your edition. To do this, simply send an email to support@zohodesk.com, or contact your dedicated account manager and they will take care of the rest.
Note:Credit purchase limits vary by edition. The editions (excluding Free and Trial) allow up to 5,000,000 credits, including base and user credits.
Before You Request Additional Credits, Make Sure
The table below shows the pricing for each credit slab.
| Tier | Daily credit Range | Monthly Rate per 1000 credits |
|---|---|---|
| First 25,000 | 1 to 25,000 | $4.20 |
| Next 75,000 | 25,001 to 100,000 | $1.80 |
| Next 150,000 | 100,001 to 250,000 | $1.50 |
| Above 250,000 | 250,001+ | $0.75 |
Example: Calculating Monthly Cost for 300,000 Credits
If you need 300,000 credits in a day, the monthly cost would be:
Total Monthly Cost: $502.50
Use the calculator below to check the monthly payable amount for the add-on credits.
Disclaimer: All calculated rates are approximate and subject to changes in the exchange rate.
You can track how many API credits are used and how many are remaining by checking the response headers of your API call.
| Response Header Name | Description |
|---|---|
| X-Rate-Limit-Request-Weight-v3 | The number of credits used for that specific API call. |
| X-Rate-Limit-Remaining-v3 | The credits left for portal for the current day. |
| Retry-After | The time (in seconds) you need to wait before trying the next API request. This appears in the response header only after you reach the rate limit. |
Note:The Retry-After header appears only when your portal hits the maximum daily credit limit.
Success Response Header
HTTP/1.1 200 OK
-H "X-Rate-Limit-Request-Weight-v3: 3"
-H "X-Rate-Limit-Remaining-v3: 950"
Too many request Response Header
HTTP/1.1 429
-H "Retry-After: 34"
You can set up alert notifications to stay informed about your API credit usage. By specifying a threshold limit in percentage, the system will automatically trigger an alert when your API usage reaches that defined limit. This helps you proactively manage your consumption and avoid unexpected disruptions. Learn how to configure API usage alerts.
Zoho Desk's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization. This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. Each API request must include an OAuthToken to retrieve any resource from your Zoho Desk portal.
To view a sample reference code in Java to help you understand the OAuth authorization flow for Zoho Desk Rest APIs, click here.
Clients are not required to support password authentication or store user credentials.
Clients gain delegated access, i.e., access only to resources authenticated by the user.
Users can revoke the client's delegated access anytime.
OAuth2.0 access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.
The following are some terms you need to know before you start using the Zoho Desk APIs.
The Zoho Desk resources, such as Tickets, Contacts, Tasks, etc.
The Zoho Desk server that hosts protected resources.
Any end-user of your account, who can grant access to the protected resources.
An application that sends requests to the resource server to access the protected resources on behalf of the end-user.
The consumer key generated from the connected application.
The consumer secret generated from the connected application.
Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the Zoho Desk authorization server.
The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens..
A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to Zoho Desk APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.
A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.
Sample Success Response
First, register your app in Zoho's Developer Console, which you can access here.
Java Script: Applications that run exclusively on a browser and are independent of a web server.
Web Based: Applications that are clients running on a dedicated HTTP server.
Mobile: Applications that are installed on smart phones and tablets.
Non-browser Mobile Applications: Applications for devices without browser provisioning such as smart TVs and printers.
Self Client: If your application is a stand-alone application that performs only back-end jobs like data-sync (without any manual intervention).
For more details, refer to OAuth Overview.
Client Name: The name of your application you want to register with Zoho.
Homepage URL: The URL of your web page.
Authorized Redirect URIs: A valid URL of your application to which Zoho Accounts redirects you with a grant token(code) after successful authentication.
On successful registration, you will be provided with a client ID and a client secret. These are your OAuth credentials.
To use the Zoho Desk APIs, the user must authenticate the application to make API calls on their behalf with an access token.
The access token, in return, must be obtained from a grant token (authorization code). The Zoho Desk APIs use the authorization code grant type to provide access to protected resources.
There are two ways in which you can generate the grant token based on the client type.
Web-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. For this client-type, you must use redirection-based code generation. In this authorization flow, obtain an authorization grant by invoking the authorization URI, that contains the parameters listed in the table below. Refer to the example to understand how to construct this authorization URI.
| Parameter | Description |
|---|---|
| client_id | Client ID generated after registering the client. |
| response_type | "code" |
| redirect_uri | Redirect URI mentioned while registering the client. |
| scope | The various scopes associated with Zoho Desk.You can use the list of scopes as per your requirement |
| access_type | "offline"/"online". In cases where refresh tokens can't be stored, use online access_type. The default will be online |
| state | State is an opaque value used by the client to maintain state between the request and callback. |
After you invoke the authorization URI, a "user-consent" page opens.
The application gets authorized. The grant token sent as a parameter in the redirect_uri.
A back-end script from your end needs to store the following details from the above URL.
The application exchanges the authorization code for an access token.
The browser redirects to the redirect URI with the parameter error=access_denied, and your application is denied access to the user's data in Zoho Desk.
Note:The grant token is valid only for one minute.
Use this method to generate the grant token if your application does not have a domain and a redirect URL.
You can also use this option when your application is a standalone server-side application performing a back-end job.
Go to Zoho Developer Console.
Choose Self Client from the list of client types, and click Create Now.
Click OK in the pop up to enable a self client for your account.
Now, your client ID and client secret are displayed under the Client Secret tab.
Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details.
Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
Enter a description and click Generate.
The generated code for the specified scope is displayed. Copy the grant token.
Note:Generating the grant token is a one-time process, provided you generate the access and refresh tokens within the time the grant token is valid for.
Authorization Grant API Url
GET https://accounts.zoho.com/oauth/v2/auth
Query Params
?response_type=code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&state=-5466400890088961855
Invoke a URL in the following format to exchange the authorization code (obtained at the end of the previous step) with an OAuthToken.
| Parameter | Description |
|---|---|
| code | Authorization code obtained after generating the grant token. |
| client_id | Client ID obtained after registering the client. |
| client_secret | Client secret obtained after registering the client. |
| grant_type | "authorization_code" |
| redirect_uri | Redirect URI mentioned while registering the client. |
After invoking the URL, you will be presented with an access token, which you must include in all API calls.
Note:Each access token is valid for only an hour and used only for the operations defined in the scope.
Refresh token does not expire. Use it to refresh access tokens when they expire.
You can only generate a maximum of five refresh tokens in a minute.
Access Token API Url
POST https://accounts.zoho.com/oauth/v2/token
Query Params
?code=1000.fadbca4c2be2f08b0ce82a54f4313.ba5325853af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/oauthgrant
Response Example
Access tokens generally expire in one hour, which means a new access token has to be generated to keep the process going. You can eliminate the need to perform the entire procedure to generate access tokens, by using refresh tokens. Once the access token expires, the refresh token can be used to generate a new access token.
Refresh token can be obtained only when access_type is set to offline while creating the access token.
Refer to the example to understand how an access token can be obtained using the refresh token.
Note:A "User" in an organization can have a maximum of 20 refresh tokens. And each refresh token can have a maximum of 15 active access tokens (non expired).
When a user creates a 16th access token, the system deletes the first created access token. Similarly, when the user creates the 21st refresh token, the system deletes the first created refresh token.
We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your Desk account.
Access Token From Refresh token API Url
POST https://accounts.zoho.com/oauth/v2/token
Query Params
?refresh_token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&grant_type=refresh_token
Response Example
If you want to revoke your refresh token, Make a POST request with the following URL:
https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}
Refer to the example to understand how a refresh token can be revoked.
Revoking Token API Url
POST https://accounts.zoho.com/oauth/v2/token/revoke
Query Params
?token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
To invoke Zoho Desk's APIs, pass the access token in the Authorization parameter in the header, as shown in the example.
Request Example
$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237
-H "orgId:2389290"
-H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"
Response Example
HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
The various scopes accessible using Zoho Desk's APIs are as follows:
| ScopeName | Description |
|---|---|
| Desk.tickets.ALL | Grants read and write access to tickets and related data. |
| Desk.tickets.READ | Grants read access to tickets and related data. |
| Desk.tickets.WRITE | Grants write access to tickets. |
| Desk.tickets.UPDATE | Grants update access to tickets and related data. |
| Desk.tickets.CREATE | Grants access to create tickets |
| Desk.tickets.DELETE | Grants access to delete tickets |
| Desk.contacts.READ | Grants read access to contacts, accounts and related data |
| Desk.contacts.WRITE | Grants write access to contacts, accounts and related data |
| Desk.contacts.UPDATE | Grants update access to contacts, accounts and related data |
| Desk.contacts.CREATE | Grants access to create contacts and accounts |
| Desk.tasks.ALL | Grants read and write access to tasks and related data |
| Desk.tasks.WRITE | Grants write access to tasks and related data |
| Desk.tasks.READ | Grants read access to tasks and related data |
| Desk.tasks.CREATE | Grants access to create tasks |
| Desk.tasks.UPDATE | Grants update access to tasks and related data |
| Desk.tasks.DELETE | Grants access to delete tasks |
| Desk.basic.READ | Grants read access to basic data, such as organizations, agents and departments |
| Desk.basic.CREATE | Grants access to create basic data, such as organizations, agents and departments |
| Desk.settings.ALL | Grants read and write access to settings data |
| Desk.settings.WRITE | Grants write access to settings data |
| Desk.settings.READ | Grants read access to settings data |
| Desk.settings.CREATE | Grants access to create new settings data |
| Desk.settings.UPDATE | Grants access to update existing settings data |
| Desk.settings.DELETE | Grants access to delete settings data |
| Desk.search.READ | Grants access to search for data |
| Desk.events.ALL | Grants read and write access to the events subscription |
| Desk.events.READ | Grants read access to the events subscription |
| Desk.events.WRITE | Grants write access to the events subscription |
| Desk.events.CREATE | Grants access to create events subscription |
| Desk.events.UPDATE | Grants update access to the events subscription |
| Desk.events.DELETE | Grants delete access to the events subscription |
| Desk.articles.READ | Grants read access to articles |
| Desk.articles.CREATE | Grants access to create articles |
| Desk.articles.UPDATE | Grants update access to articles |
| Desk.articles.DELETE | Grants delete access to articles |
Any OAuth token generated is linked to a Zoho Desk organization. This step of associating the token and the organization, which happens in the backend while getting authorization consent from the end user, is called organization binding.
If the end-user has only one Zoho Desk organization (portal), the OAuth token is linked to it automatically. If they have multiple organizations, they must manually select the one with which the token must be linked, as illustrated in the following image.
After they click the Submit button, the OAuth token is generated with the organization information bound to it.
Zoho Desk APIs automatically extract organization information from OAuth tokens. Therefore, it is not necessary to add the extra orgId query parameter in an API call or pass it in the API's header. However, if you choose to do so, make sure that the value of orgId is same as that of the portal bound with the OAuth token. If the IDs do not match, the API call fails, and the OAUTH_ORG_MISMATCHerror message is returned.
Zoho Desk supports webhooks that asynchronously deliver information on events that occur in the help desk. These events include actions, such as creating or updating a ticket, contact, or account, and so on. For information on how to include Zoho Desk webhooks in your service, refer to this document.
Your help center is one of the key channels through which customers can seek support. This portal provides your customers with access to major help modules, such as your knowledge base, user community, live chat, and ticket submission form. A well-designed and well-maintained help center ensures good self-service capabilities for your customers and lesser burden on your support agents. To know more about this please refer this document
The Zoho Desk Java SDK helps you create client Java applications that can be integrated with your Zoho Desk portal. This SDK makes it easy to access and use Zoho Desk APIs where necessary. In other words, it serves as a wrapper for the REST APIs, making it easy to use Zoho Desk's functionalities in your custom applications. To know more about this SDK please refer this document
In Zoho Desk, each business is categorized as an organization. If you have multiple businesses, set each business up as an individual organization by creating a new signup and generating a unique organization ID. All APIs except the ones directly related to organizations must include the organization ID in the header in this format: orgId:{organization_id}
string
Actual name of the organization/business
string
Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.
string
Phone number of the organization
string
Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, PROFESSIONAL, STANDARD and EXPRESS.
long
Unique ID of the organization
boolean
Key that returns if the organization is the default organization of the user
boolean
Key that returns if the user is an admin in the organization
string
URL of the help desk portal
string
URL of the image file displaying the organization's logo
string
Alternative name for the help desk portal
string
Number of employees in the organization
string
Brief description of the organization
string
Mobile number of the organization
string
Website of the organization
string
Fax number of the organization
string
Primary contact person in the organization
string
Street in which the organization's office is located
string
City in which the organization's office is located
string
State in which the organization's office is located
string
Zip code of the organization's address
string
Country in which the organization's office is located
string
Currency locale in which the organization operates
string
Currency symbol used in the organization
Example
This API fetches the details of an organization from your help desk.
Credit: 1 credit/call
boolean
optional,Key that denotes if the customDomain field must be included in the API response
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists all organizations to which the current user belongs.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists all organizations which can be accessed using the current Oauth token.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API updates the details of an organization.
Credit: 1 credit/call
string
optional,Actual name of the organization/business
string
optional,Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.
string
optional,Phone number of the organization
string
optional,Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, PROFESSIONAL, STANDARD and EXPRESS.
string
optional,Alternative name for the help desk portal
string
optional,Number of employees in the organization
string
optional,Brief description of the organization
string
optional,Mobile number of the organization
string
optional,Website of the organization
string
optional,Fax number of the organization
string
optional,Primary contact person in the organization
string
optional,Street in which the organization's office is located
string
optional,City in which the organization's office is located
string
optional,State in which the organization's office is located
string
optional,Zip code of the organization's address
string
optional,Country in which the organization's office is located
string
optional,Currency locale in which the organization operates
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches the logo set for an organization/portal in your help desk.
string
optional,Key that helps avoid browser cache. Only alphanumeric values are allowed.
string
optional,Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.
OAuth Scope
Request Example
Response Example
This API fetches the favicon set for an organization/portal in your help desk.
string
optional,Key that helps avoid browser cache. Only alphanumeric values are allowed.
string
optional,Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.
OAuth Scope
Request Example
Response Example
This API updates the logo set for an organization/portal in your help desk.
Note: To upload organization logo generate OAuthToken for the scope: Desk.settings.UPDATE,profile.orglogo.UPDATE or Desk.basic.UPDATE,profile.orglogo.UPDATE
Credit: 1 credit/call
Content-Type:multipart/form-data
Image file of the logo.The maximum file size allowed is 2 MB ; and extensions allowed are: .jpg,.png,.jpeg.
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API updates the favicon set for an organization/portal in your help desk.
Credit: 1 credit/call
Content-Type:multipart/form-data
Image file of the favicon.The maximum file size allowed is 2 MB ;and extensions allowed are .jpg,.png,.gif,.jpeg,.ico
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes the logo set for an organization/portal in your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API updates the favicon set for an organization/portal in your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API updates the default organization for the current user in Zoho Desk.
Credit: 1 credit/call
long
requiredUnique ID of the organization to be marked as default org
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
Business hours are the working hours of your help desk. In Zoho Desk, you can configure multiple business hour sets, based on factors, such as the shift times of your agents, and time zones of the regions you cater to. Defining business hours is important because the due time for responding to and resolving tickets are calculated based on these hours. They play a critical role in time tracking and SLAs
String
Name of the business hours set
String
Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE
String
Type of the business hours set. Values allowed are 24X7 (available anytime throughout the week), SPECIFIC (available during specific hours on the days selected),and CUSTOM (available during different hours on different days
deprecated
long
ID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours
list
ID(s) of the holiday lists to associate with business hours. Note: A maximum of 2 holiday lists can be associated with business hours
string
ID of the time zone to associate with the business hours set
list
Business hours for the week
Example
This API creates a business hours set in your help desk portal
Credit: 1 credit/call
String
requiredName of the business hours set
String
requiredActivation status of the business hours set. Values allowed are ACTIVE and INACTIVE
String
requiredType of the business hours set. Values allowed are 24X7 (available anytime throughout the week), SPECIFIC (available during specific hours on the days selected),and CUSTOM (available during different hours on different days
deprecatedlong
optionalID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours
list
optionalID(s) of the holiday lists to associate with business hours. Note: A maximum of 2 holiday lists can be associated with business hours
string
optional,ID of the time zone to associate with the business hours set
list
optionalBusiness hours for the week
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API fetches the details of a business hours set configured in your help desk portal
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
TThis API updates the details of a business hours set configured in your help desk portal
Credit: 1 credit/call
String
optionalName of the business hours set
String
optionalActivation status of the business hours set. Values allowed are ACTIVE and INACTIVE
String
optionalType of the business hours set. Values allowed are 24X7 (available anytime throughout the week), SPECIFIC (available during specific hours on the days selected),and CUSTOM (available during different hours on different days
deprecatedlong
optionalID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours
list
optionalID(s) of the holiday lists to associate with business hours. Note: A maximum of 2 holiday lists can be associated with business hours
string
optional,ID of the time zone to associate with the business hours set
list
optionalBusiness hours for the week
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a business hours set from your help desk portal
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API lists a particular number of business hour sets, based on the limit specified
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the business hour sets must be listed
integer
optional,Number of business hour sets to list
String
optionalActivation status of the business hour sets. Values allowed are ACTIVE and INACTIVE
list
optionalThe IDs of the BusinessHours to list separated by commas. You can pass upto 50 IDs.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists a particular number of automation rules that include a business hours set,based on the limit specified
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the rules must be listed
integer
optional,Number of rules to list
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Holiday list refers to the list of public holidays applicable to your help desk. In Zoho Desk, you can configure multiple holiday lists, based on the regions you cater to. Holiday lists are factored in calculating the due time for responding to and resolving tickets. They play a critical role in time tracking and SLAs. You can associate a holiday list with multiple business hour sets, but each business hour set can include only one holiday list.
String
Name of the holiday list
list
Holidays to define in the list
String
Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE
list
IDs of the business hour sets associated with the holiday list
String
Type of holiday. Possible values: RECURRING: Fixed holidays that repeat every year on the same date (e.g., Christmas, New Year's Day), YEAR_SPECIFIC:Holidays that vary depending on the year (e.g., Easter, Thanksgiving)
Integer
The year the holiday falls in. Note: Required only when the holidayListType is set to YEAR_SPECIFIC
Example
This API creates a holiday list in your help desk portal
Credit: 1 credit/call
String
requiredName of the holiday list
list
requiredHolidays to define in the list
String
requiredActivation status of the holiday list. Values allowed are ACTIVE and INACTIVE
list
optionalIDs of the business hour sets associated with the holiday list
String
optionalType of holiday. Possible values: RECURRING: Fixed holidays that repeat every year on the same date (e.g., Christmas, New Year's Day), YEAR_SPECIFIC:Holidays that vary depending on the year (e.g., Easter, Thanksgiving)
Integer
optional,The year the holiday falls in. Note: Required only when the holidayListType is set to YEAR_SPECIFIC
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API fetches the details of a holiday list configured in your help desk portal
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API updates the details of a holiday list configured in your help desk portal
Credit: 1 credit/call
String
optionalName of the holiday list
list
optionalHolidays to define in the list
String
optionalActivation status of the holiday list. Values allowed are ACTIVE and INACTIVE
list
optionalIDs of the business hour sets associated with the holiday list
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a holiday list from your help desk portal
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API lists a particular number of holiday lists, based on the limit specified
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the holiday lists must be listed
integer
optional,Number of holiday lists to list
String
optionalActivation status of the holiday list. Values allowed are ACTIVE and INACTIVE
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Departments refer to the organizational divisions configured in your help desk, based on the business function performed by each division; for example, marketing, sales, finance, admin, and so on.
long
ID of the department
string
Name of the department
string
Display name of the department in the help center
string
A short description of the department
boolean
Key that denotes if the department is visible in the help center or not
boolean
Key that denotes if the department is enabled or not
boolean
Key that denotes if the assign to team functionality is enabled or not
boolean
Key that denotes if the department has a logo or not
long
ID of user who created the department
timestamp
Time of creating the department
list
IDs of agents associated with the department
boolean
Key that denotes if the department is the default department in the help desk portal
string
Chat status of the departments: AVAILABLE, DISABLED, NOT_CREATED
Example
This API fetches the details of a department from your help desk
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists a particular number of departments, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
boolean
optionalKey that filters departments based on their enabled status
integer
optional,Index number, starting from which the departments must be fetched
string
optional,String to search for departments by name, help center name, or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for departments whose name, help center name, or description start with the string, 2) *string* - Searches for departments whose name, help center name, or description contain the string, 3) string - Searches for departments whose name, help center name, or description is an exact match for the string
integer
optional,Number of departments to fetch; default value is 10 and maximum value supported is 200
string
optional,Key that filters departments based on their chat status. Values allowed are AVAILABLE, DISABLED, NOT_CREATED, and ${UNAVAILABLE}. ${UNAVAILABLE} refers to departments which are not available for chat.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the agents in a department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the agents must be listed
integer
optional,Number of agents to fetch; default value is 10 and maximum value is 200
string
optional,Key that filters agents, based on their activation status: ACTIVE or DISABLED
boolean
optionalKey that denotes if the agents must be light or non light.
boolean
optionalKey that denotes if the agents must be confirmed or unconfirmed.
string
optional,String to search for agents by first name, last name, or email ID. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for agents whose first name, last name, or email ID start with the string, 2) *string* - Searches for agents whose first name, last name, or email ID contain the string, 3) string - Searches for agents whose first name, last name, or email ID is an exact match for the string
string
optional,Name of the field that must be used for searching and listing agents. Values allowed are: firstName, lastName, name, and emailId.
string
optional,To sort the available list of agents in either ascending or descending order. Values allowed are: asc or desc
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API returns the number of departments configured in your help desk portal.
Credit: 50 credits/call
boolean
optionalKey that filters departments based on their enabled status
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the details of the departments whose IDs are passed in the API request.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredComma-separated array of department IDs. Maximum number of IDs allowed is 50.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API checks if multiple departments have the same name.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
required,Name of the department for which you want to check duplicate entries
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API adds a department to your help desk portal.
Credit: 1 credit/record
string
required,Name of the department
string
optional,Display name of the department in the help center
string
optional,A short description of the department
boolean
optionalKey that denotes if the department is visible in the help center or not
boolean
optionalKey that denotes if the assign to team functionality is enabled or not
list
requiredIDs of agents associated with the department
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
This API updates the details of an existing department.
Credit: 1 credit/call
string
optional,Name of the department
string
optional,Display name of the department in the help center
string
optional,A short description of the department
boolean
optionalKey that denotes if the department is visible in the help center or not
boolean
optionalKey that denotes if the assign to team functionality is enabled or not
list
optionalIDs of agents associated with the department
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API disables a department in your help desk portal.
Credit: 1 credit/call
Long
optionalAgents move to new department ID
Long
optionalEmail move to new department ID
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API enables a department in your help desk portal.
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API associates agents to a department.
Credit: 1 credit/call
list
requiredIds of Agents
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API dissociates agents from a department.
Credit: 1 credit/call
list
requiredIds of Agents
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches the logo set for a department.
Credit: 1 credit/call
string
optional,Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API updates the logo set for a department.
Credit: 1 credit/call
Content-Type:multipart/form-data
Image file of the logo. Maximum file size allowed is 2MB; maximum number of files allowed is one; and extensions allowed are: jpg, png, gif, and jpeg.
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API removes the logo set for a department.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
By default, the web address of your help center is a Zoho Desk sub-domain in the "desk.zoho.com/portal/<mycompany>" format. However, you can personalize this address, so that your customers can submit their tickets from a sub-domain, such as 'support.mycompany.com'. This feature is called domain/host mapping.
string
Address of the domain
boolean
Key that denotes if the domain is verified
boolean
Key that denotes if the domain is applied to the portal
string
Zoho Desk domain security code to add in the domain service provider's CNAME
timestamp
Time of verifying the domain
timestamp
Time of applying the domain to the portal
long
ID of user who verified the domain
long
ID of user who applied the domain to the portal
string
SSL status of the domain
string
SSL request status of the domain if SSL certificate is requested for the domain
long
ID of user who requested for the SSL certificate for the domain
timestamp
Time of requesting the SSL certificate for the domain
Example
This API adds a domain to your help desk.
Credit: 1 credit/call
string
required,Address of the domain
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API verifies a domain in your help desk.
Credit: 1 credit/call
string
required,Domain to be verified.
string
required,Domain verification method. CNAME or HTML.
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API maps a domain to the default portal in your help desk.
Credit: 1 credit/call
string
required,Address of the domain
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API resets the current domain of the default portal in your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API lists the domains configured in your help desk.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
boolean
optionalKey that filters domains based on their verification status
boolean
optionalKey that filters domains based on their application status in the help desk
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
Products are the goods/services your organization sells.
long
ID of the product
long
ID of user to whom the product is assigned
string
Name of the product
string
Reference code of the product
string
Category to which the product belongs
string
Organization that manufactures the product
double
Price of the product
deprecated
list
User-defined fields related to the product
list
User-defined fields related to the product
long
User who added the product to the help desk portal
long
User who modified the details of the product
timestamp
Time of adding the product to the help desk portal
timestamp
Time of modifying product details
string
Description of the product
Example
This API fetches a single product from your helpdesk.
Credit: 1 credit/call
string
optional,Key that fetches secondary information related to the product. Values allowed are: departments and owner. You can pass multiple values by separating them with commas.
OAuth Scope
Desk.products.READ
,
Desk.settings.READ
Request Example
Response Example
This API lists a specific number of products from your help desk portal, based on the limit defined. (Note: The departmentIds key will soon be deprecated and not included in API responses.)
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalID of the view to apply while fetching the products
integer
optionalIndex number, starting from which the products must be fetched
integer
optional,No. of products to fetch
long
optionalID of the department from which the products must be fetched. If you want to list the products configured in all accessible departments, pass the value 0.
long
optionalID of user to whom the product is assigned
string
optional,Sort by a specific attribute : productName, productCode, unitPrice, createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.
string
optional,Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: layoutId. Maximum of 30 fields is supported as comma separated values.
list
optionalSecondary information related to the contact.Value supported is owner.
OAuth Scope
Desk.products.READ
,
Desk.settings.READ
Request Example
Response Example
This API adds a product to your helpdesk.
Credit: 1 credit/call
long
optionalID of user to whom the product is assigned
string
required,Name of the product
string
optional,Reference code of the product
string
optional,Category to which the product belongs
string
optional,Organization that manufactures the product
double
optionalPrice of the product
deprecatedlist
optionalUser-defined fields related to the product
list
optionalUser-defined fields related to the product
string
optional,Description of the product
OAuth Scope
Desk.products.CREATE
,
Desk.settings.CREATE
Request Example
Response Example
This API lists tickets received from a specific products.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalID of the department from which the tickets must be fetched
Integer
optionalIndex number, starting from which the tickets must be fetched
Integer
optional,Number of tickets to fetch
string
optional,Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.
string
optional,Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma
boolean
optional,Filters Spam tickets
string
optional,Additional information related to the tickets. Values allowed are: products, departments, team, isRead and assignee. You can pass multiple values by separating them with a comma in the API request.
OAuth Scope
Desk.tickets.READ
,
Desk.settings.READ
,
Desk.search.READ
Request Example
Response Example
This API updates details of a product in your help desk portal.
Credit: 1 credit/call
long
optionalID of user to whom the product is assigned
string
optional,Name of the product
string
optional,Reference code of the product
string
optional,Category to which the product belongs
string
optional,Organization that manufactures the product
double
optionalPrice of the product
deprecatedlist
optionalUser-defined fields related to the product
list
optionalUser-defined fields related to the product
string
optional,Description of the product
OAuth Scope
Desk.products.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API moves products to the Recycle Bin of your help desk portal.
Credit: 6 credits/record
list
requiredIDs of the products you want to delete
OAuth Scope
Desk.products.DELETE
,
Desk.settings.DELETE
Request Example
Response Example
This API searches for duplicate records of a product.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the products must be fetched
integer
optional,No. of products to fetch
string
required,Name of the product, used as the keyword for the search
OAuth Scope
Desk.products.READ
,
Desk.settings.READ
Request Example
Response Example
This API associates contacts with a product. Only a maximum of 10 contacts can be associated with a product through a single API request.
Credit: 1 credit/call
list
requiredIDs of the resources to associate
boolean
requiredtrue for associating the resource and false for dissociating the resource
OAuth Scope
Desk.products.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API associates accounts with a product. Only a maximum of 10 accounts can be associated with a product through a single API request.
Credit: 1 credit/call
list
requiredIDs of the resources to associate
boolean
requiredtrue for associating the resource and false for dissociating the resource
OAuth Scope
Desk.products.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists the accounts associated with a product
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optionalIndex number starting from which the accounts must be fetched
integer
optional,Number of accounts to fetch
string
optional,Key that sorts the accounts by a specific attribute: accountName or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API lists the contacts associated with a product.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optionalIndex number, starting from which the contacts must be listed
integer
optional,Number of contacts to fetch
string
optional,Parameter that sorts contacts by one of these attributes: firstName, lastName, phone, email, account, createdTime, modifiedTime
list
optionalKey that fetches secondary information related to the contact.Value allowed is accounts
boolean
optional,Filters Spam contacts
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
Product attachments are the files you attach to a product to aid quick resolution.
long
ID of the attachment Note : This ID can be used only by the user who uploaded the attachment. If another user tries to use the attachment ID in other APIs such as sendEmailReply, draftEmailReply, etc an error will be thrown.
long
ID of user who attached the file
timestamp
Time of attaching the file
string
Name of the attachment
boolean
Key that returns if the attachment is public or not
long
Size of the attachment
Example
This API lists all attachments in a product.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.
integer
optionalfrom Index
integer
optional,the number of attachments to be displayed
string
optional,Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.
OAuth Scope
Desk.products.READ
,
Desk.settings.READ
Request Example
Response Example
This API attaches a file to a product.
Credit: 1 credit/call
Content-Type:multipart/form-data
attachment to be added
OAuth Scope
Desk.products.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API deletes an attachment from a product.
Credit: 1 credit/call
OAuth Scope
Desk.products.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
These public APIs help access details of the countries,languages and time zones supported in Zoho Desk.
Example
This API lists the countries that can be set in the locale field in Zoho Desk. Keep in mind that the countries object will be deprecated soon. Therefore, make sure to use the data object instead, wherever needed.
OAuth Scope
Request Example
Response Example
This API lists the languages that are available for listing in Zoho Desk.
OAuth Scope
Request Example
Response Example
This API lists the time zones that are available for listing in Zoho Desk.
OAuth Scope
Request Example
Response Example
Module is a structured compartment used to store, organize, and manage specific types of data allowing businesses to efficiently handle different entities such as tickets, contacts, products, price details etc.
string
SingularLabel of the module
string
PluralLabel of the module
string
Description of the module
list
IDs of departments associated with the Module
list
IDs of profileIds associated with the Module
string
Unique readonly name of the module
string
Specifies the name of the primary field of the module. When creating a module, a unique primary field is assigned to that module.
boolean
Specifies whether the module is a custom module
boolean
Specifies whether the module is department-specific
boolean
Specifies whether the module has a recycle bin feature to store records and attachments deleted from the desk account. If the value is 'true', the deleted records will be moved to the recycle bin, which you can restore if needed. If not, the records will be permanently deleted.
Long
The unique id of the module
long
Id of the User who created the module
timestamp
Specifies the time of creation of the Module
long
Id of the User who modified the module
timestamp
Specifies the time at which changes were made to the module
Example
The API creates a Custom Module. Custom Module allows users to organize, store, and manage specific types of data tailored to meet unique business requirements.
Credit: 1 credit/call
string
required,Singular Label of the module
string
required,Plural Label of the module
string
optional,Description of the module
list
optionalIDs of departments associated with the module
list
optionalIDs of profileIds associated with the module
boolean
optionalSpecifies whether the module is department-specific. If the key is not provided, it will create an organization-level module.
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
The API edits a Custom Module.
Credit: 1 credit/call
string
required,Singular Label of the module
string
required,Plural Label of the module
string
optional,Description of the module
list
requiredIDs of departments associated with the module
list
requiredIDs of profileIds associated with the module
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API fetches a single Module
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
The API fetches all the modules.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ
Request Example
Response Example
The API fetches a list of modules that are accessible to the current user profile.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.basic.READ
Request Example
Response Example
The API fetches all the modules available in Zoho Desk.
This API is deprecated, use api/v1/organizationModules api for fetching modules.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.basic.READ
Request Example
Response Example
Account refers to customer organizations that use your products or services. An account can have multiple contacts.
boolean
Key that returns if the value in the field is encrypted or not. The field types are Text, Number, Percent, Decimal, Email, Phone, URL which supports encryption
string
Name of the field on the UI
deprecated
string
Name of the custom field
string
Unique readonly name of the custom field that can be used to update value of record in api
string
i18nlabel for the field label
string
Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, Boolean and LargeText
integer
Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields
integer
Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields
integer
Precision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields
string
Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp. Applicable only for Currency fields
string
Default value set for a field. Applicable for Checkbox fields
boolean
Is this field available in help center
string
the tool tip of the field
string
the tool tip of the field
boolean
While enabled tracks the last activity of the particular field
Example
This API fetches fields in a module
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
requiredthe module name with in which search to be done. Value may be tickets, contacts , accounts ,tasks , calls , events, timeEntry,products, contracts, agents
string
optional,Key that fetches only the fields whose apiNames are given. Multiple values can be passed, with commas for separation.
long
optionalKey that fetches only the fields for the given departmentId.
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API creates a field
Credit: 1 credit/call
String
requiredName of the module whose fields must be fetched. Values allowed are tickets, contacts, accounts, tasks, timeEntry, products , calls , events, and contracts.
boolean
optionalKey that returns if the value in the field is encrypted or not. The field types are Text, Number, Percent, Decimal, Email, Phone, URL which supports encryption
string
required,Name of the field on the UI
deprecatedstring
optional,Name of the custom field
string
required,Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, Boolean and LargeText
integer
optionalMaximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields
integer
optionalNumber of decimal places the value in a field can take. Applicable for Decimal and Currency fields
integer
optionalPrecision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields
string
optional,Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp. Applicable only for Currency fields
string
optional,Default value set for a field. Applicable for Checkbox fields
string
optional,the tool tip of the field
string
optional,the tool tip of the field
boolean
optionalWhile enabled tracks the last activity of the particular field
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API edits a field
Credit: 1 credit/record
boolean
optionalKey that returns if the value in the field is encrypted or not. The field types are Text, Number, Percent, Decimal, Email, Phone, URL which supports encryption
string
optional,Name of the field on the UI
deprecatedstring
optional,Name of the custom field
string
optional,Data type of the field. Values allowed are Text, Number, Percent, Decimal, Currency, Date, Date Time, Email, Phone, PickList, Website, Textarea, Checkbox, Multiselect, Boolean and LargeText
integer
optionalMaximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields
integer
optionalNumber of decimal places the value in a field can take. Applicable for Decimal and Currency fields
integer
optionalPrecision of the value in the field. Precision refers to the total number of digits in a decimal number. For example, the precision of 30.12 is 4. Applicable for Currency fields
string
optional,Option to round off complex decimal numbers to the nearest whole number or shorter decimal number. Values allowed are roundOff, roundDown, and roundUp. Applicable only for Currency fields
string
optional,Default value set for a field. Applicable for Checkbox fields
string
optional,the tool tip of the field
string
optional,the tool tip of the field
boolean
optionalWhile enabled tracks the last activity of the particular field
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API get a field
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API get a field permissions for all the profiles
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API update field permissions
Credit: 1 credit/call
list
optionalnull
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API delete a custom field
Credit: 500 credits/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API returns the custom field count allowed and available in a module.
Credit: 50 credits/call
String
requiredName of the module whose allowed and available custom fields must be fetched. Values allowed are tickets, contacts, accounts, tasks, calls, events, timeEntry, products, and contracts.
long
optionalID of the department in which the layout is configured.
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API fetches criteria references of a custom field
Credit: 1 credit/record
String
requiredFeature name from which criteria references has to be fetched - DirectAssignment, RoundRobin, WorkFlow, SLA, Supervise, BluePrint, CustomView, Report, GameTrophy, GameBadge, LayoutRules, ValidationRules
integer
required,Index number, starting from which the rules must be listed
integer
required,Number of references to fetch
OAuth Scope
Desk.settings.READ
Request Example
Response Example
A record represents a complete set of information associated with a particular entity or object stored within a module. Once a module is created, records can be created for that module. For example, within a doctor module, a list of doctors can be created, with each doctor being a distinct record within that module.
string
The primary field of the Module for the record
object
The custom fields associated with the Module for the record
Long
The unique ID of the record
boolean
Specifies whether the record is trashed. The value will be 'false' for records that are in recyclebin.
timestamp
Specifies the time at which changes were made to the record
timestamp
Specifies the time of creation of the record
Example
This API creates a record for a module.
Call the Organization field API: Call the Organization field API to get the required field information in the custom module.
Collect the field API names: Extract the API names you want to include in your record from the response of the Organization field API. These API names will be used to specify the field values when creating the record.
Pass the field information to the Record API: Make a request to the Record API, providing the field API names and their corresponding values to create the record.
A sample record creation request is provided on the right side for reference.
Credit: 1 credit/call
string
requiredThe primary field of the Module for the record
jsonObject
optionalLayout of the record
jsonObject
optionalDepartment of the record
Note: This key is mandatory if the module is a department-specific module
jsonObject
optionalThe owner of the record
jsonObject
optionalCustom fields associated with the record
OAuth Scope
Desk.custommodule.CREATE
Request Example
Response Example
This API Edits a record for a module.
Call the Organization field API: Call the Organization field API to get the required field information in the custom module.
Collect the field API names: Extract the API names you want to include in your record from the response of the Organization field API. These API names will be used to specify the field values when updating the record.
Pass the field information to the Record API: Make a request to the Record API, providing the field API names and their corresponding values to update the record.
A sample record update request is provided on the right side for reference.
Credit: 1 credit/call
string
requiredThe primary field of the Module for the record
jsonObject
optionalLayout of the record
jsonObject
optionalThe owner of the record
jsonObject
optionalCustom fields associated with the record
OAuth Scope
Desk.custommodule.UPDATE
Request Example
Response Example
This API fetches a single record.
Credit: 1 credit/call
OAuth Scope
Desk.custommodule.READ
Request Example
Response Example
This API lists a particular number of records, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalThe ID of the view from which records need to be fetched.
integer
optional,The starting index number from where the records should be fetched.
integer
optional,The number of records that need to be fetched.
string
optional,Sort by a specific attribute. The allowed values are createdTime or modifiedTime. Note: The default sorting order is ascending. A - prefix denotes descending order of sorting.
string
optional,Key that returns the values of mentioned fields (both pre-defined and custom). Note: All field types except multi-text are supported. Standard, non-editable fields are supported too. Maximum of 30 fields is supported as comma separated values.
OAuth Scope
Desk.custommodule.READ
Request Example
Response Example
This API fetches the number of records.
Credit: 50 credits/call
long
requiredID of the view from which the record count needs to be fetched.
OAuth Scope
Desk.custommodule.READ
Request Example
Response Example
This API moves records to the Recycle Bin.
Credit: 6 credits/record
list
requiredIDs of the records to move to the Recycle Bin
OAuth Scope
Desk.custommodule.UPDATE
Request Example
Response Example
The API simultaneously updates multiple records.
Credit: 1 credit/2 records
list
requiredArray containing the IDs of the records to update. Note: The maximum number of IDs allowed is 50.
string
required,Name of the field to update
string
optional,Value in the field
OAuth Scope
Desk.custommodule.UPDATE
Request Example
Response Example
Dependency mapping is a function that is applicable only to PickList fields. Through this function, you can define a parent-child relationship between two fields. For example, let's say there are two fields - Country and State - in your Tickets module. The State field will display values, depending on the value you select in the Country field. If you choose India in the Country field, only the states of India will be displayed in the State field and the states of other countries will be hidden. If you choose a different country, only the states of that country will be displayed.
long
ID of the layout in which the dependency is mapped
long
ID of the parent field
long
ID of the child field
list
JSON object that shows the mapping configured
Example
This API lists the dependency mappings configured in a layout.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalID of the layout in which the dependency is mapped
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API fetches the parent and child fields using which you can configure dependency mappings in a layout.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredlayout Id
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API creates a dependency mapping between two fields.
Credit: 1 credit/call
long
requiredID of the layout in which the dependency is mapped
long
requiredID of the parent field
long
requiredID of the child field
list
requiredJSON object that shows the mapping configured
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates details of an existing dependency mapping.
Credit: 1 credit/call
list
optionala Json object which consist of elements which are inturn a json array
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a dependency mapping from a layout.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
Layouts define the arrangement and necessity of fields in forms used to capture details of help desk resources: Tickets, Tasks, Contacts, and so on. Each department can have unique layouts with both default and custom fields. You can also determine the visibility settings for each field in a layout.
long
ID of the layout
long
ID of user who created the layout
long
ID of user who modified the layout
long
ID of department in which the layout is configured
timestamp
Time of creating the layout
timestamp
Time of modifying the layout
boolean
Key that returns if the layout is the default layout in the module
string
Name of the layout
string
Description of the layout
string
Display Name of the layout in HelpCenter
list
sections in the layout
Example
This API lists all the layouts configured for a module.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
required Name of the module whose layouts must be fetched. The allowed values are tickets, contacts, accounts, calls, events, tasks, timeEntry, products, and contracts
long
optionalID of the department in which the layouts are configured
String
required,Status of the layout. The allowed values are active,inactive, and all
integer
required,The starting index number from where the layouts should be fetched
integer
required,The number of layouts to be fetched
string
optional,Name of the layout
long
optionalID of the layout
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API fetches a layout configured for a module
Credit: 1 credit/call
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API creates new Layout by cloning existing layout.
Credit: 1 credit/call
string
required,Name of the layout
string
optional,Description of the layout
string
required,Display Name of the layout in HelpCenter
boolean
requiredKey that returns if the layout is the default layout in the module
long
optionalId which helps to clone a layout in another department
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API creates the layout
Credit: 1 credit/call
boolean
requiredKey that returns if the layout is the default layout in the module
list
requiredsections in the layout
string
required,mdoule name
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates details of an existing layout.
Credit: 1 credit/call
boolean
optionalKey that returns if the layout is the default layout in the module
list
optionalsections in the layout
string
optional,mdoule name
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a layout
Credit: 500 credits/call
long
requiredThe layout id to which the entities in the deleted layout to be transferred to
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This Api deactivates existing layout
Credit: 1 credit/call
long
requiredThe layout id to which the entities in the deleted layout to be transferred to
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This api activates the deactivated Layout.
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This api returns the profiles associated with a layout
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This api Associates the given profiles to the layout
Credit: 1 credit/call
list
optionalThe profile id to which the layout needs to be associated to
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This Api provides the standrd layout format for the given module with organisations fields that can be used for create layout
Credit: 1 credit/call
String
requiredName of the module whose layouts must be fetched. Values allowed are tickets, contacts, accounts , calls , events, tasks, timeEntry, products, and contracts.
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API fetches details of a layout, based on the profile of the current user.
Credit: 1 credit/call
long
optionalID of the layout
OAuth Scope
Desk.basic.READ
Request Example
Response Example
This API replaces the old value with the new value for the PickList field type in all existing records only.
Note: When a value that does not exist in the PickList values is provided as new value, then this API will create the new value without deleting the old one.
Credit: 500 credits/call
long
requiredfield Id
string
required,oldValue
string
required,newValue
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API updates details of a field in the layout.
Credit: 1 credit/call
string
optional,Formula Expression
boolean
optionalKey that returns if a field is mandatory in a layout or not
string
optional,Default value set for a field. Applicable for Checkbox fields and PickList fields
list
optionalValues allowed in a field. Applicable for PickList fields
string
optional,Key that sorts values in a PickList field either alphabetically or by a user-defined order
boolean
optionalKey that returns if the picklist is nested or not
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API is to remove fields from a layout.
Credit: 1 credit/call
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API is to clone a field to other layouts.
Credit: 1 credit/call
list
optionalList of layout ids to which the field should be cloned.
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This api behaves as below
(i)When Query param fileType=CSV is passed the picklist values gets downloaded in csv file with *fieldlabel* as its name
(ii) When header param is not passed empty 200 response
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Export Format in which format should be shown.This value can be CSV
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Layout rules enable you to configure a page layout to respond to a user's input as a record is created or edited. Depending on how you set it up, the rule can set mandatory fields, show or hide fields, and show or hide sections.
string
Name of the rule
string
A short description of the rule
string
Name of the primary field to be used for creating the rule
string
Display Label of the primary field to be used for creating the rule
string
Activation status of the rule: ACTIVE or DEACTIVE
boolean
To execute the rule in help centre or not: true or false
list
Conditions in the layout rule
Example
This API fetches a single rule from your help desk layout.
Credit: 1 credit/call
string
optional,Additional information related to the rules. Values allowed are: creator and modifier.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists all the rules configured for a department/layout.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalGet the rules of the department
long
optionalGet the rules of the layout
String
optionalName of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events
Boolean
optionalGet the rules for active layouts
Boolean
optionalGet the rules that are active in the layout
Boolean
optionalGet the rules that can be executed in help centre
integer
optional,Index number, starting from which the rules must be fetched
integer
required,Number of rules to be fetched. Default is 50
String
optionalGet the rules that have this search term
string
optional,Additional information related to the rules. Values allowed are: creator and modifier.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API creates a rule for a field in a layout.
Credit: 1 credit/call
string
optional,Additional information related to the rules. Values allowed are: creator and modifier.
string
required,Name of the rule
string
optional,A short description of the rule
string
required,Name of the primary field to be used for creating the rule
string
optional,Display Label of the primary field to be used for creating the rule
string
optional,Activation status of the rule: ACTIVE or DEACTIVE
boolean
optionalTo execute the rule in help centre or not: true or false
list
requiredConditions in the layout rule
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates the details of an existing layout rule in a particular layout.
Credit: 1 credit/call
string
optional,Additional information related to the rules. Values allowed are: creator and modifier.
string
optional,Name of the rule
string
optional,A short description of the rule
string
optional,Name of the primary field to be used for creating the rule
string
optional,Display Label of the primary field to be used for creating the rule
string
optional,Activation status of the rule: ACTIVE or DEACTIVE
boolean
optionalTo execute the rule in help centre or not: true or false
list
optionalConditions in the layout rule
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a layout rule created for a field from a layout.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API lists the fields that can be used in criteria of a specified module in layout rules. Available pre-defined values may contain ${EMPTY}, ${NOTEMPTY}, ${OPEN}, ${CLOSED}, ${CURRENTTIME}. Available types are Text, Date, DateTime, Text, Boolean and Arithmetic.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
requiredCategory for getting the field criteria for primary or secondary fields
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Validation rules verify that the data an agent enters in a record meets the standards you specify before the agent can save the record.
string
Name of the primary field to be used for creating the validation rule
string
Display Label of the primary field to be used for creating the rule
string
Activation status of the validation rule: ACTIVE or DEACTIVE
boolean
To execute the rule in help centre or not: true or false
list
Conditions in the validation rule
Example
This API fetches a validation rule configured for your layout.
Credit: 1 credit/call
string
optional,Additional information related to rules. Values allowed are: creator, modifier
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API fetches all the validation rules configured for your department/layout.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalGet the rules of the department
long
optionalGet the rules of the layout
String
optionalName of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events
Boolean
optionalGet the rules for active layouts
Boolean
optionalGet the rules that are active in the layout
integer
optional,Index number, starting from which the rules must be fetched
integer
required,Number of rules to be fetched. Default is 50
String
optionalGet the rules that have this search term
Boolean
optionalGet the rules that can be executed in help centre
string
optional,Additional information related to the rules. Values allowed are: creator and modifier.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API creates a validation rule for a field in a layout.
Credit: 1 credit/call
string
optional,Additional information related to rules. Values allowed are: creator, modifier
string
required,Name of the primary field to be used for creating the validation rule
string
optional,Display Label of the primary field to be used for creating the rule
string
optional,Activation status of the validation rule: ACTIVE or DEACTIVE
boolean
optionalTo execute the rule in help centre or not: true or false
list
requiredConditions in the validation rule
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates the details of an existing validation rule in a particular layout.
Credit: 1 credit/call
string
optional,Additional information related to rules. Values allowed are: creator, modifier
string
optional,Name of the primary field to be used for creating the validation rule
string
optional,Display Label of the primary field to be used for creating the rule
string
optional,Activation status of the validation rule: ACTIVE or DEACTIVE
boolean
optionalTo execute the rule in help centre or not: true or false
list
optionalConditions in the validation rule
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a validation rule created for a field from a layout.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API lists the fields that can be used in criteria of a specified module in validation rules. Available pre-defined values may contain ${EMPTY}, ${NOTEMPTY}, ${OPEN}, ${CLOSED}, ${CURRENTTIME}. Available types are Text, Date, DateTime, Text, Boolean and Arithmetic.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
requiredCategory for getting the field criteria for primary or secondary fields
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Data sharing rules refer to user permissions related to viewing and/or editing resources in the different modules in Zoho Desk.
string
Data sharing rules related to SLA contracts
string
Data sharing rules related to tickets
string
Data sharing rules related to contacts
string
Data sharing rules related to accounts
string
Data sharing rules related to products
string
Data sharing rules related to tasks
string
Data sharing rules related to calls
string
Data sharing rules related to events
string
Data sharing rules related to custom module
Example
This API fetches the different data sharing rules configured in your help desk portal.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API updates the data sharing rules configured in your help desk portal.
Credit: 1 credit/call
string
optional,Data sharing rules related to SLA contracts
string
optional,Data sharing rules related to tickets
string
optional,Data sharing rules related to contacts
string
optional,Data sharing rules related to accounts
string
optional,Data sharing rules related to products
string
optional,Data sharing rules related to tasks
string
optional,Data sharing rules related to calls
string
optional,Data sharing rules related to events
string
optional,Data sharing rules related to custom module
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Agents are the customer service executives in your organization. They are the primary users of the helpdesk software, using which they interact with contacts and resolve tickets.
string
Email ID of the agent
string
Activation status of the agent: ACTIVE or DISABLED
string
Last name of the agent
string
First name of the agent
string
Full name of the agent
string
Phone number of the agent
string
Mobile number of the agent
string
Extension number of the agent
list
Departments with which the agent is associated
list
Chat departments with which the agent is associated
long
ID of the agent
long
Zoho user ID of the agent
long
Role ID of the agent
long
Profile ID of the agent
string
URL of the image file displaying the agent's photo
boolean
Key that returns if the agent is a confirmed user in the portal or not
string
The Role Permission type of Agent
string
Agent's about info
list
The channels handled for the Agent
string
Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.
string
The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.
string
Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.
Example
This API fetches details of an agent in your help desk.
Credit: 1 credit/call
string
optional,Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, associatedChatDepartments and verifiedEmails. You can include all four values by separating them with commas in the API request.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists a particular number of agents, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the agents must be fetched
integer
optional,Number of agents to fetch. The default value is 10 and the maximum value supported is 200.
string
optional,Key that filters agents based on their activation status: ACTIVE, DISABLED, DELETED or IMPORTED
long
optionalComma-separated array of department IDs. Maximum number of IDs allowed is 50.
long
optionalComma-separated array of profile IDs. Maximum number of IDs allowed is 50.
long
optionalComma-separated array of role IDs. Maximum number of IDs allowed is 50.
string
optional,Types of roles and permissions of the agents to list. The allowed values are AgentPublic, AgentPersonal,AgentTeamPersonal, Admin, Light, Custom, and ${NON_LIGHT}. ${NON_LIGHT} refers to agents who are not associated with the light agent profile.
boolean
optionalKey that denotes if the agents must be confirmed or unconfirmed.
boolean
optionalKey that denotes if the agents must be light or non light.
string
optional,Secondary information related to agents, The allowed values are profile, role. You can include all two values by separating them with commas in the API request.
string
optional,String to search for agents by first name, last name, or email ID. The string must contain at least one character. The supported search methods: 1) string* - Searches for agents whose first name, last name, or email ID start with the string, 2) *string* - Searches for agents whose first name, last name, or email ID contain the string, 3) string - Searches for agents whose first name, last name, or email ID is an exact match for the string
string
optional,Name of the field that must be used for searching and listing agents. The allowed values are: firstName, lastName, name, and emailId
string
optional,String to search for agents by custom field. The string must contain at least one character
string
optional,API name of the custom field that must be used for searching and listing agents
string
optional,To sort the available list of agents in either ascending or descending order. The allowed values are: asc or desc
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the agents count by status, confirmed and include light
Credit: 50 credits/call
string
optional,Parameter that filters agents based on their activation status: ACTIVE or DISABLED
boolean
optionalFilters Confirmed & Unconfirmed agents
boolean
optionalCount light agent.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of agents via the agent IDs passed in the API request.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredComma-separated array of agent IDs. Maximum number of IDs allowed is 50.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of the currently logged in agent.
Credit: 1 credit/call
string
optional,Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, and associatedChatDepartments. You can pass multiple values by separating them with commas in the query param
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API activates agents in your help desk.
Credit: 1 credit/2 records
list
requiredIds of Agents
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deactivates an agent in your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API sends reinvitation mails to unconfirmed agents.
Credit: 1 credit/2 records
list
requiredIds of Agents
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API adds an agent to your help desk.
Keep in mind the following points while adding an agent:
Credit: 1 credit/call
string
required,Email ID of the agent
string
required,Last name of the agent
string
optional,First name of the agent
string
optional,Phone number of the agent
string
optional,Mobile number of the agent
string
optional,Extension number of the agent
list
requiredDepartments with which the agent is associated
list
optionalChat departments with which the agent is associated
string
required,The Role Permission type of Agent
string
optional,Agent's about info
list
optionalThe channels handled for the Agent
string
optional,Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.
string
optional,The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.
string
optional,Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
This API updates details of an agent.
Credit: 1 credit/call
string
optional,Email ID of the agent
string
optional,Last name of the agent
string
optional,First name of the agent
string
optional,Phone number of the agent
string
optional,Mobile number of the agent
string
optional,Extension number of the agent
list
optionalDepartments with which the agent is associated
list
optionalChat departments with which the agent is associated
string
optional,The Role Permission type of Agent
string
optional,Agent's about info
list
optionalThe channels handled for the Agent
string
optional,Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.
string
optional,The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.
string
optional,Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes unconfirmed agents from your help desk.
Credit: 6 credits/record
list
requiredIds of Agents
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes a confirmed agent from your help desk.
Credit: 1 credit/call
string
optional,Nickname of the agent, which will appear on their entity history page
boolean
optionalKey that determines if the deleted agent must be anonymized in the help desk
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API removes the identification details of a deleted agent.
Credit: 1 credit/call
string
optional,Nickname of the agent, which will appear on their entity history page
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API sets the profile photo for the currently logged in agent.
Note: To upload your photo generate OAuthToken for the scope: Desk.settings.UPDATE,profile.userphoto.UPDATE or Desk.basic.UPDATE,profile.userphoto.UPDATE
Credit: 1 credit/call
Content-Type:multipart/form-data
Image file containing the agent's photo. Maximum file size allowed is 500KB; maximum file limit is one; and extensions allowed are: .jpg, .png, .gif, and .jpeg.
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API gets the profile photo for the given agent id.
Note: To get agent photo generate OAuthToken for the scope: Desk.settings.READ,profile.userphoto.READ or Desk.basic.READ,profile.userphoto.READ
Credit: 1 credit/call
string
optional,Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API deletes the profile photo of the currently logged in agent.
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches the preferences of the currently logged in agent.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API updates the preferences of the currently logged in agent.
Credit: 1 credit/call
List
optionalPattern that defines how the names should be displayed
long
optionalA valid active departmentId to which the agent is associated | 'allDepartment'
string
optional,Pattern that defines which duration format is used for duration fields in Reports
string
optional,Select the App appearance: light or dark or auto or pureDark
string
optional,Select the Left panel appearance: light or dark
string
optional,Enable or Disable the pure dark Mode: ENABLED or DISABLED
string
optional,Select the App theme: red or green or blue or yellow or orange or pink or skyBlue or teal
string
optional,Select the App layout that is optimal for your screen resolution: smartFocus or focusedWidth or fullWidth
string
optional,Select the App layout width: 59 to 89
string
optional,Select the App font family: Zoho Puvi or Lato or Roboto or Vazirmatn or OpenDyslexic or Poppins
string
optional,Select the App font size: 8 to 24
string
optional,Select the Editor font family: Lato or Roboto or Zoho Puvi or Arial or Carlito or Helvetica or Verdana or Wide or Courier New or Comic Sans MS or Garamond or Georgia or Narrow or Serif or Tahoma or Times New Roman or MotoyaLMaru or Trebuchet or Mulish or Vazirmatn or OpenDyslexic or Poppins
string
optional,Select the Editor Font Size: 8 or 10 or 12 or 14 or 18 or 24 36
string
optional,Enable or Disable the Public comment: ENABLED or DISABLED
string
optional,Highlight the Critical link: ENABLED or DISABLED
string
optional,Highlight the link by Underline: ENABLED or DISABLED
string
optional,Highlight the Clickable area: ENABLED or DISABLED
string
optional,Enable or Disable the Animations: regularmotion or reducedmotion or autoReducedmotion
string
optional,Enable or Disable the Custom scroll: ENABLED or DISABLED
string
optional,Select the App Zoom level: 8 to 24
string
optional,Set the App Font size based on the zoom level: ENABLED or DISABLED
string
optional,Enable or Disable the Accessibility ShortCut in wms: ENABLED or DISABLED
string
optional,Enable or Disable the App Increased Contrast: ENABLED or DISABLED
string
optional,Select the App Contrast level: low or medium or high
string
optional,Automatically Adapt the Contrast ratio for backgrounds: ENABLED or DISABLED
string
optional,Enable or Disable the App Rading Mask: ENABLED or DISABLED
string
optional,Select the Reading mask level: small or medium or full or custom
string
optional,Select the Reading mask height: 10 to 90
string
optional,Select the Reading mask width: 10 to 100
string
optional,Select the Reding mask opacity: 0.15 to 0.9
string
optional,Select the Ticket Reply Action Buttons: reply or replyAll or forward or reply_replyAll or reply_forward or replyAll_forward or replyAll_reply or forward_reply or forward_replyAll or forward_replyAll_reply or forward_reply_replyAll or replyAll_forward_reply or replyAll_reply_forward or reply_forward_replyAll or reply_replyAll_forward
string
optional,Select the Ticket Reply Action Button dropdown list order: forward_replyAll_reply or forward_reply_replyAll or replyAll_forward_reply or replyAll_reply_forward or reply_forward_replyAll or reply_replyAll_forward
string
optional,Enable or Disable the Empty Queue column: ENABLED or DISABLED
string
optional,The way in which the community topics should be displayed. The allowed values are CLASSIC or COMPACT
string
optional,Sort the list of community topics based on order. The allowed values are ascending or descending
string
optional,Sort the list of community topics based on time. The allowed values are createdTime or modifiedTime
string
optional,The number of community topics to be listed on a single page
string
optional,Set the width for detail view ibarTab: 357 or 1 to 100 as the decimal value
string
optional,Enable or Disable the focusRing: ENABLED or DISABLED
string
optional,Select the focusRing enabled places: all or main
string
optional,Select the notification view: stack or list
string
optional,Enable or Disable the Success notification autoClose: ENABLED or DISABLED
string
optional,Select the Success notification auto close time: 01 or 03 or 05 or 10 or 15 or 20
string
optional,Enable or Disable the Error notification autoClose: ENABLED or DISABLED
string
optional,Select the Error notification auto close time: 01 or 03 or 05 or 10 or 15 or 20
string
optional,Enable or Disable the App Custom cursor: ENABLED or DISABLED
string
optional,Select the App Custom cursor size: 8 or 16 or 24 or 32
string
optional,Select the App Custom cursor color: black or white
string
optional,Enable or Disable the adhdFriendly persona: ENABLED or DISABLED
string
optional,Enable or Disable the astigmatism persona: ENABLED or DISABLED
string
optional,Enable or Disable the blindness persona: ENABLED or DISABLED
string
optional,Enable or Disable the colorBlindness persona: ENABLED or DISABLED
string
optional,Enable or Disable the dyslexia persona: ENABLED or DISABLED
string
optional,Enable or Disable the epilepsy persona: ENABLED or DISABLED
string
optional,Enable or Disable the elderly persona: ENABLED or DISABLED
string
optional,Enable or Disable the motorDisabilities persona: ENABLED or DISABLED
string
optional,Enable or Disable the seizureSafe persona: ENABLED or DISABLED
string
optional,Enable or Disable the visuallyImpaired persona: ENABLED or DISABLED
string
optional,Select the Tickets module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Contacts module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Accounts module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Contracts module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Calls module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Tasks module Detailview Ibar Panel view: collapse or expand
string
optional,Select the Events module Detailview Ibar Panel view: collapse or expand
string
optional,Enable or Disable Ticket Reply Send and Update status: ENABLED or DISABLED
string
optional,Select Tag color variant: bold or subtle or minimal
string
optional,Enable or Disable the Tag text default color: ENABLED or DISABLED
string
optional,Select the Tickets Table View content style: wrap or clip
string
optional,Select the Contacts Table View content style: wrap or clip
string
optional,Select the Accounts Table View content style: wrap or clip
string
optional,Select the Contracts Table View content style: wrap or clip
string
optional,Select the Calls Table View content style: wrap or clip
string
optional,Select the Tasks Table View content style: wrap or clip
string
optional,Select the Events Table View content style: wrap or clip
string
optional,Enable or Disable the strikeThrough disabled button: ENABLED or DISABLED
string
optional,Enable or Disable the switch label: ENABLED or DISABLED
string
optional,Feeds Notification Preference value
string
optional,Select the line style for conversation in nested view: curved or straight
string
optional,Enable or Disable the icons display in conversation nested view: ENABLED or DISABLED
string
optional,Select the conversation subtab view type: recentTop or recentBottom or nestedView
string
optional,Select the threads and comments subtabs view type: recentTop or recentBottom
string
optional,Select the employee portals displayContext: inApp or newTab
string
optional,Select the employee portals displayMode: compactView or splitView or fullScreenView
string
optional,Enable or Disable the highlight search keyword: ENABLED or DISABLED
string
optional,Enable or Disable the highlight search keyword more prominent: ENABLED or DISABLED
string
optional,Select the Mandatory Field Indication: asterisk or requiredText
string
optional,Select the Mandatory Field Label Color: default (default - Uses the application’s standard label color defined by the active theme appearance.) or red
string
optional,Select the Color Filter: none or grayscale
string
optional,Select the places excluded from Grayscale Filter: none or richText_richTextEditor
string
optional,Select the module visibility type: topBand or unifiedLHS
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches details of an agent via the email ID passed in the API request.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API schedules reassignment of tickets, tasks, and automations belonging to a deleted/deactivated agent to another agent within the same department.
Credit: 500 credits/call
list
requiredDetails of agents to whom the resources associated with the agent will be reassigned
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches the entity preferences of the currently logged in agent.
Credit: 1 credit/call
string
required,Entity Type of the preference.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API updates the entity preferences of the currently logged in agent.
Credit: 1 credit/call
list
optionalUser entity preferences
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
Agent time entry refers to the time taken by an agent to resolve a ticket or perform a task.
long
ID of the time entry
long
ID of the ticket
string
Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.
long
ID of the user associated with the time entry
timestamp
Time when work related to the time entry was started.
integer
Number of hours in the time entry.
integer
Number of minutes in the time entry.
integer
Number of seconds in the time entry.
double
Per hour cost of an agent.
double
Additional cost incurred
double
Total cost incurred
double
Fixed cost
string
Description of the time entry
deprecated
list
User-defined fields related to the time entry.
JSONObject
User-defined fields related to the time entry.
timestamp
Time of creating the ticket time entry
timestamp
Time of modifying the ticket time entry
string
User who created the time entry.
string
User who modified the time entry.
String
Mode configured in time tracking. Supported values are Manual and Auto
boolean
Billing Preference
String
Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE
long
ID of the invoice related to the time entry
Example
This API fetches a time entry related to an agent.
Credit: 1 credit/call
string
optional,Secondary information related to the time entry. Value supported is owner.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists the time entries associated with an agent.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Module from which the time entries must be fetched. Values allowed are tickets and tasks.
long
optionalID of the department
integer
optionalIndex number, starting from which the time entries must be fetched
integer
optional,Number of time entries to fetch
String
optionalKey that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.
string
optional,Secondary information related to the time entry. Value supported is owner.
String
optionalKey that filters time entries, based on their billing status: nonBillable , billable or billed
timestamp
optionalKey that filters time entries created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.
timestamp
optionalKey that filters time entries whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API fetches the sum of time entries associated with an agent.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Module Preference. It can be either tickets tasks
long
optionalID of the department
String
optionalKey that filters time entries, based on their billing status: nonBillable , billable or billed
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Agent availability refers to your support agents' presence for responding to customers.
This API updates the agent availability setting configured in your help desk portal.
Credit: 1 credit/call
boolean
optionalKey that specifies if idle agents should be marked as offline after a particular duration.
int
optional,Duration after which idle agents should be marked as offline. The value can range from 1 to 540.
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API fetches the agent availability setting configured in your help desk portal.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the current availability of agents in a particular department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.
String
optionalKey that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.
integer
required,Number of agents to list. The default and the maximum value allowed is 50.
integer
required,Index number, starting from which the agents must be fetched. The default value is 0 and the maximum value allowed is 5999.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the agents who are currently online in a particular department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.
String
optionalKey that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.
integer
required,Number of agents to list. The default value is 20 and the maximum value allowed is 6000.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the agents who are currently offline in a particular department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.
String
optionalKey that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.
integer
required,Number of agents to list. The default value is 20 and the maximum value allowed is 6000.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
Signature refers to the self-identifying/self-referencing details that agents include at the end of their responses to customers.
Note:
Agents do not require any special permissions to update their own signatures.
Agents require the "Update Agent" permission to update the signatures of other agents.
boolean
Determines whether the agent's signature is included in ticket replies.
Note: If set to true, the agent's signature will be appended to all ticket replies; if set to false, it will be excluded.
deprecated
long
ID of the agent. This key is deprecated, Please use id key instead of this
long
ID of the agent
string
Default signature of the agent
list
Department-specific, customized signatures of the agent
Example
This API fetches the different signatures configured by an agent.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API updates the existing signatures of an agent.
Credit: 1 credit/2 records
boolean
optionalDetermines whether the agent's signature is included in ticket replies.
Note: If set to true, the agent's signature will be appended to all ticket replies; if set to false, it will be excluded.
string
optional,Default signature of the agent
list
optionalDepartment-specific, customized signatures of the agent
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API updates the customized signatures of an agent.
Credit: 1 credit/call
long
requiredID of the department in which the signature exists
string
required,Signature of the agent in that department
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
SkillType is a Category for grouping skills
Example
This API Creates a Skill Type
Credit: 1 credit/call
String
requiredName of the skilltype
long
requireddepartmentId of the Skill Type
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API Gets the details of a Skill Type
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API Updates a Skill Type
Credit: 1 credit/call
String
optionalName of the skilltype
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API Deletes a Skill Type
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API Lists all Skill Types in a department
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalDepartment Id
integer
optionalIndex number, starting from which the skills must be listed
integer
optional,Number of skilltypes to list, allowed minimum value 1, maximum value 100,default is 100
String
optionalFilter skill types by associated skills status, allowed values ACTIVE and INACTIVE
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Skills, They are area of expertises which can be mapped with Tickets and Agents
String
Name of the skill
String
description of the skill
String
Values allowed are ACTIVE and INACTIVE
long
ID of the Skill Type
list
The criteria details for the skill
list
IDs of the agents mapped with the skill
Example
This API Creates a skill
Credit: 1 credit/call
String
requiredName of the skill
String
optionaldescription of the skill
String
requiredValues allowed are ACTIVE and INACTIVE
long
requiredID of the Skill Type
list
requiredThe criteria details for the skill
list
optionalIDs of the agents mapped with the skill
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API Gets the details of a skill
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API Updates a skill
Credit: 1 credit/call
String
optionalName of the skill
String
optionaldescription of the skill
String
optionalValues allowed are ACTIVE and INACTIVE
long
optionalID of the Skill Type
list
optionalThe criteria details for the skill
list
optionalIDs of the agents mapped with the skill
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a skill from your help desk portal
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API lists all skills in a department
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredDepartment Id
integer
optionalIndex number, starting from which the skills must be listed
integer
optional,Number of skill to list, allowed minimum value 1, maximum value 100,default is 100
String
optionalActive inactive filter for Skills. Values allowed are ACTIVE and INACTIVE
String
optionalSearch string, Used to filter skills by name starting with this string
long
optionalSkill Type Id, to Filter Skills by SkillType
long
optionalThe IDs of the skills to list separated by commas. You can pass upto 50 IDs.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists a particular number of automation rules that include a skill,based on the limit specified
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the related rules must be listed
integer
optional,Number of rules to list, allowed minimum value 1, maximum value 100,default is 100
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists reorders Skills in a Department
Credit: 1 credit/2 records
JSONArray
requiredList of skill ids to reorder
long
requireddepartment of the skills to be reordered
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Returns skills mapped with an agent by department
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredlist of Department Ids separated by commas,Maximum 10 department ids allowed
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API modifies skills mapped for an agent in a department
Credit: 1 credit/call
long
requiredID of the Department
list
optionalIds of skills to be mapped
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API returns list of fields supported in criteria for Skills by module
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredDepartment Id
String
requiredModule, Allowed values are tickets,contacts and accounts
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Department Level Configurations for Skill Stamping
long
ID of the Department
string
Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER
string
This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE
Example
This API gets Configuration of Skill in a Department
Credit: 1 credit/call
long
requiredDepartment Id
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API updates Configuration of Skill in a Department
Credit: 1 credit/call
long
optionalID of the Department
string
optional,Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER
string
optional,This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
A team is a group of agents/users in a department. Just like how you can assign tickets or tasks to agents, you can also assign tickets and tasks to teams.
String
Name of the team
String
A short description of the team
Long
ID of the department to which the team belongs
list
List of sub-teams within the team
list
List of roles to add to the team
list
List of roles with subordinates to add to the team
list
List of agents to add to the team
list
List of agents derived with the properties set for the team
Example
This API creates a team in your help desk portal.
Credit: 1 credit/call
String
requiredName of the team
String
optionalA short description of the team
Long
requiredID of the department to which the team belongs
list
optionalList of sub-teams within the team
list
optionalList of roles to add to the team
list
optionalList of roles with subordinates to add to the team
list
optionalList of agents to add to the team
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
This API updates details of an existing team.
Credit: 1 credit/call
String
optionalName of the team
String
optionalA short description of the team
list
optionalList of sub-teams within the team
list
optionalList of roles to add to the team
list
optionalList of roles with subordinates to add to the team
list
optionalList of agents to add to the team
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes an existing team from your help desk portal. To reassign the open and on hold tickets and tasks of the deleted team to a different team, pass the ticketNewTeam, taskNewTeam, ticketNewAgent, and taskNewAgent team parameters in the API request. If you do not want to assign the tickets to another team, pass the values of ticketNewTeam and ticketNewAgent as null. However, in the case of tasks, either taskNewTeam or taskNewAgent must have a valid value. Both parameters cannot be passed as null.
Credit: 1 credit/call
long
requiredAssign open and on hold tickets of the team being deleted to this team.
long
requiredAssign open and on hold tickets of the team being deleted to this agent.
long
requiredAssign open tasks of the team being deleted to this team.
long
requiredAssign open tasks of the team being deleted to this agent.
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API fetches the details of a team.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of all teams created in all departments to which the current user belongs.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of all the members of a particular team.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Secondary information related to the team. Values allowed are profile, role. You can include all two values by separating them with commas in the API request.
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the other teams that can be added as sub-teams to the current team.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of all the teams to which an agent belongs.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of all the teams associated with a particular role.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches details of all the teams in a particular department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
Role refers to the user role that can be defined in Zoho Desk. Roles help define organization-wide hierarchy. Users at a higher hierarchy can always access all the records of at a lower hierarchy. For example, a Support Manager can access all the Agents' records, whereas Agents can access only their records.
string
Name of the role
string
A short description of the role
boolean
Key that denotes if the role is visible in the UI
boolean
Key that denotes if the role is the default role
boolean
Key that denotes if the role shares data with its peer roles
long
ID of the role
long
ID of the role to which the current role reports
list
IDs of roles that directly report to the current role
Example
This API lists a particular number of roles, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the roles must be listed
integer
optional,Number of roles to display. The default value is 15 and the maximum value allowed is 500.
boolean
optionalKey that filters roles according to their visibility in the UI
boolean
optionalKey that denotes whether the roles must be default roles or custom roles
string
optional,String to search for roles by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for roles whose name or description start with the string, 2) *string* - Searches for roles whose name or description contain the string, 3) string - Searches for roles whose name or description is an exact match for the string
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists agents mapped to a particular role.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API creates a role in your help desk.
Credit: 1 credit/call
string
required,Name of the role
string
optional,A short description of the role
boolean
requiredKey that denotes if the role shares data with its peer roles
long
optionalID of the role to which the current role reports
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
This API updates details of an existing role.
Credit: 1 credit/call
string
optional,Name of the role
string
optional,A short description of the role
boolean
optionalKey that denotes if the role shares data with its peer roles
long
optionalID of the role to which the current role reports
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes a role from your help desk.
Credit: 1 credit/call
long
requiredTransfer the child-roles to the given role
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API fetches the details of a particular role.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the number of roles configured in your help desk.
Credit: 50 credits/call
boolean
optionalKey that filters roles according to their visibility in the UI
boolean
optionalKey that denotes whether the roles must be default roles or custom roles
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the details of the personal role configured in your help desk. Agents with personal role can view only the tickets assigned to them and unassigned tickets.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists details of the roles whose IDs are passed in the API request.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
Profiles control the user permissions to access help desk modules, records, fields in a record, and other utilities, such as import, export, send email, etc. Users associated with a profile can access only the functions that are assigned to that profile.
string
Name of the profile
string
Description of the profile
boolean
If the profile is visible in UI
string
Type of the profile. Possible values are Administrator, Standard, Light, Portal, and Custom
boolean
If the profile is system generated
long
Id of the profile
Example
This API lists a particular number of user profiles, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
boolean
optionalKey that filters profiles according to their visibility in the UI
boolean
optionalKey that denotes whether the profiles must be default profiles or custom profiles
string
optional,String to search for profile by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for profiles whose name or description start with the string, 2) *string* - Searches for profiles whose name or description contain the string, 3) string - Searches for profiles whose name or description is an exact match for the string
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the number of profiles configured in your help desk.
Credit: 50 credits/call
boolean
optionalKey that filters profiles according to their visibility in the UI
boolean
optionalKey that denotes whether the profiles must be default profiles or custom profiles
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the details of a particular profile.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API replicates an existing profile.
Credit: 1 credit/call
string
required,Name of the profile to be created
String
optionalDescription of the profile to be created
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
This API updates the details of an existing profile.
Credit: 1 credit/call
string
optional,Name of the profile
string
optional,Description of the profile
OAuth Scope
Desk.settings.UPDATE , Desk.basic.UPDATE
Request Example
Response Example
This API deletes a profile from your help desk.
Credit: 1 credit/call
long
requiredThe profile id to which the agents in the delete profile to be transferred to
OAuth Scope
Desk.settings.DELETE , Desk.basic.DELETE
Request Example
Response Example
This API fetches the configuration details and permissions defined for the profile of the currently logged in user.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the permissions associated with the profile of the currently logged in user.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists agents mapped to a particular profile.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
boolean
optionalActivation status of the agents to list
boolean
optionalConfirmation status of the agents to list
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the different permissions configured for the light agent profile.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
Tickets are organizing units using which service agents handle customer enquiries, requests, complaints, and other such interactions in Zoho Desk.
long
ID of the ticket
string
Subject of the ticket
referred object
ID of the contact who raised the ticket. If a value is not available for this key, make sure to include the contact JSON object. If neither attribute is available, an error message regarding the unavailability of the contactId message is returned.
Contact
Details of the contact who raised the ticket. This object is used for automatically creating a contact when a ticket is received. If the email ID of the contact already exists in your portal, the corresponding contactId is used for creating the ticket. Else, a contact is first created and the contactId of the new contact is mapped to the ticket. The user’s profile and field permissions are considered in the contact creation process. Either the lastName or the email attribute must be present in the object.
referred object
ID of the product to which the ticket is mapped
list
File attachments in the ticket. For more information, refer to the Uploads section
string
Email ID in the ticket
string
Phone number in the ticket
string
Description in the ticket
string
Status of the ticket. Includes the custom statuses configured in your help desk portal.
string
Type of ticket resolution status.The values supported are OPEN and ON HOLD and CLOSED.
long
ID of agent to whom the ticket is assigned
string
Category of the ticket
string
Subcategory of the ticket
string
Resolution notes recorded in the ticket
timestamp
Due date for resolving the ticket
string
Priority of the ticket
string
Language preference to set for the ticket
string
Channel through which the ticket originated.
string
Code of the ticket's source channel
string
Type of ticket. Values supported are Problem, Request, Question, and Others.
deprecated
JSONObject
Custom fields in the ticket
JSONObject
Custom fields in the ticket
string
URL to access the resource
timestamp
Time of creating the ticket
timestamp
Time of modifying the ticket
integer
Number of time entries recorded in the ticket
integer
Number of approvals associated with the ticket
integer
Number of comments in the ticket
integer
Number of attachments in the ticket
integer
Number of tasks associated with the ticket
integer
Number of threads associated in the ticket
boolean
Key that returns if the ticket is deleted or not
boolean
Field that denotes whether the ticket is in trash
Product
Product associated with the ticket. You obtain this information using the include:product query parameter to fetch this information.
timestamp
Time of closing the ticket
String
Index/Serial number of the ticket
timestamp
Time of receiving customer response
boolean
Key that denotes if the current user has read the ticket or not
list
List of departments to which the ticket is shared and the access privileges corresponding to each department
object
Agent assigned to resolve the ticket. Use the include:assignee query param to fetch this information.
long
ID of the team assigned to resolve the ticket
boolean
Key that returns if the current user follows the ticket or not
object
Secondary information related to the channel of the ticket. Currently, this key is supported only for the Forums channel. Therefore, the API response will not return this information for tickets received through other channels.
list
Secondary contacts, such as CC'ed users, associated with the ticket
list
Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.
Example
This API fetches a single ticket from your helpdesk.
Credit: 1 credit/call
string
optional,Key that fetches secondary information related to the ticket. Values allowed are: contacts, products, assignee, departments, contract, isRead, team, and skills . Multiple values can be passed, with commas for separation.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists a particular number of tickets, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the tickets must be fetched
integer
optional,Number of tickets to fetch
long
optionalDepartments from which the tickets need to be queried. Note : For Predefined Views and All Department Views: You must specify the departmentId for which the tickets need to be fetched. Otherwise, it will fetch all tickets accessible across departments. For Single Department Custom View: You must specify the departmentId of the department for which the Custom View was created. The tickets will be fetched from that department.
string
optional,Key that filters tickets by Teams. Values allowed are Unassigned or a valid teamId. Multiple teamIds can be passed as comma-separated values.
string
optional,assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.
string
optional,Filter by channel through which the tickets originated. You can include multiple values by separating them with a comma
string
optional,Filter by resolution status of the ticket. You can include multiple values by separating them with a comma
string
optional,Sort by a specific attribute: responseDueDate or customerResponseTime or createdTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.
integer
optionalFetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.
string
optional,Additional information related to the tickets. Values allowed are: contacts, products, departments, team, isRead and assignee. You can pass multiple values by separating them with commas in the API request.
string
optional,Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: statusType, webUrl, layoutId. Maximum of 30 fields is supported as comma separated values.
string
optional,Key that filters tickets by priority. Multiple priority levels can be passed as comma-separated values.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API gets the archived tickets list in given department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the tickets must be fetched
integer
optional,Number of tickets to fetch
long
requiredID of the department from which the tickets must be fetched
int
optionalView Type - Supported Values 1 for Compact view , 2 for Classic view ,4 for Table View. If view type is not specified, Classic View will be the default view
string
optional,Key that returns additional information related to a ticket. Values allowed are: contacts, products,departments,team,isRead and assignee. All six values can be passed by separating them with a comma in the API request.
OAuth Scope
Desk.search.READ , Desk.tickets.READ
Request Example
Response Example
This API lists a particular number of tickets that are associated to you from your help desk, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the tickets must be listed
integer
optional,Number of tickets to fetch
long
optionalID of the department from which the tickets must be fetched
string
optional,assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.
string
optional,Filter by resolution status of the ticket. You can include multiple values by separating them with a comma
string
optional,Filter by followers of the ticket. Values allowed : a valid agentId.
string
optional,Filter by commenters of the ticket. Values allowed : a valid agentId. As of now, either follower or commenter is supported. If both params are given, commenter will be ignored.
long
optionalFetches only the tickets shared from departmentId to sharedDepartmentId. If departmentId is not provided, fetches all the tickets shared to sharedDepartmentId. sharedDepartmentId is given precedence only when isShared is false/not given.
boolean
optionalFilter all shared tickets actually belonging to departmentId if isShared is true. If departmentId is not provided and if isShared is true, shared tickets from all permitted departments will be listed. If departmentId is provided and isShared is true, tickets belonging to departmentId, but shared to any other department will be fetched. If departmentId and sharedDepartmentId is provided and isShared is true, then tickets belonging to departmentId, but shared to sharedDepartmentId will be fetched(Here permission checks are done on departmentId). If departmentId and sharedDepartmentId is provided and isShared is false/not given, then tickets shared to sharedDepartmentId, but belonging to departmentId will be fetched(Here permission checks are done on sharedDepartmentId).
integer
optionalFetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.
string
optional,Key that returns additional information related to a ticket. Values allowed are: contacts, products, and assignee. All three values can be passed by separating them with a comma in the API request.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API creates a ticket in your helpdesk.
Credit: 1 credit/call
string
required,Subject of the ticket
long
required,ID of the department to which the ticket belongs
referred object
optionalID of the contact who raised the ticket. If a value is not available for this key, make sure to include the contact JSON object. If neither attribute is available, an error message regarding the unavailability of the contactId message is returned.
Contact
optionalDetails of the contact who raised the ticket. This object is used for automatically creating a contact when a ticket is received. If the email ID of the contact already exists in your portal, the corresponding contactId is used for creating the ticket. Else, a contact is first created and the contactId of the new contact is mapped to the ticket. The user’s profile and field permissions are considered in the contact creation process. Either the lastName or the email attribute must be present in the object.
referred object
optionalID of the product to which the ticket is mapped
list
optionalFile attachments in the ticket. For more information, refer to the Uploads section
string
optional,Email ID in the ticket
string
optional,Phone number in the ticket
string
optional,Description in the ticket
string
optional,Status of the ticket. Includes the custom statuses configured in your help desk portal.
long
optionalID of agent to whom the ticket is assigned
string
optional,Category of the ticket
string
optional,Subcategory of the ticket
string
optional,Resolution notes recorded in the ticket
timestamp
optionalDue date for resolving the ticket
string
optional,Priority of the ticket
string
optional,Language preference to set for the ticket
string
optional,Channel through which the ticket originated.
string
optional,Type of ticket. Values supported are Problem, Request, Question, and Others.
deprecatedJSONObject
optionalCustom fields in the ticket
JSONObject
optionalCustom fields in the ticket
string
optional,URL to access the resource
list
optionalList of departments to which the ticket is shared and the access privileges corresponding to each department
long
optionalID of the team assigned to resolve the ticket
list
optionalSecondary contacts, such as CC'ed users, associated with the ticket
list
optionalComma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API updates an existing ticket.
Credit: 1 credit/call
boolean
optionalKey that enables or disables sending notifications to the corresponding contact when a ticket is closed
string
optional,Subject of the ticket
long
optional,ID of the department to which the ticket belongs
referred object
optionalID of the contact who raised the ticket. If a value is not available for this key, make sure to include the contact JSON object. If neither attribute is available, an error message regarding the unavailability of the contactId message is returned.
Contact
optionalDetails of the contact who raised the ticket. This object is used for automatically creating a contact when a ticket is received. If the email ID of the contact already exists in your portal, the corresponding contactId is used for creating the ticket. Else, a contact is first created and the contactId of the new contact is mapped to the ticket. The user’s profile and field permissions are considered in the contact creation process. Either the lastName or the email attribute must be present in the object.
referred object
optionalID of the product to which the ticket is mapped
list
optionalFile attachments in the ticket. For more information, refer to the Uploads section
string
optional,Email ID in the ticket
string
optional,Phone number in the ticket
string
optional,Description in the ticket
string
optional,Status of the ticket. Includes the custom statuses configured in your help desk portal.
long
optionalID of agent to whom the ticket is assigned
string
optional,Category of the ticket
string
optional,Subcategory of the ticket
string
optional,Resolution notes recorded in the ticket
timestamp
optionalDue date for resolving the ticket
string
optional,Priority of the ticket
string
optional,Language preference to set for the ticket
string
optional,Channel through which the ticket originated.
string
optional,Type of ticket. Values supported are Problem, Request, Question, and Others.
deprecatedJSONObject
optionalCustom fields in the ticket
JSONObject
optionalCustom fields in the ticket
string
optional,URL to access the resource
list
optionalList of departments to which the ticket is shared and the access privileges corresponding to each department
long
optionalID of the team assigned to resolve the ticket
list
optionalSecondary contacts, such as CC'ed users, associated with the ticket
list
optionalComma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API moves tickets to the Recycle Bin
Credit: 6 credits/record
list
requiredIDs of the tickets to move to the Recycle Bin
OAuth Scope
Desk.tickets.DELETE
Request Example
Response Example
This API deletes the given spam tickets
Credit: 6 credits/record
list
requiredIDs of the spam tickets. The maximum allowed number of IDs is 50.
OAuth Scope
Desk.tickets.DELETE
Request Example
Response Example
This API merges two different tickets.
Credit: 30 credits/call
list
requiredIDs of the tickets to merge
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API helps move a ticket from one department to another.
Note: The departmentId query parameter will be deprecated soon. Therefore, going forward, the departmentId attribute must be passed in the body of the API request.
Credit: 1 credit/call
long
optionalID of the department to which you want to move the ticket
long
optionalID of the department in which the ticket exists
long
optionalID of the community sub-category to which the forum ticket (forum topic converted into a ticket) must be moved
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API splits an incoming ticket thread into a new ticket.
Credit: 2 credits/call
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API updates multiple tickets at once.
Credit: 1 credit/2 records
list
requiredArray containing the IDs of the entities to update. The maximum number of IDs allowed is 50.
string
required,Name of the field to update
string
optional,Value in the field
boolean
optionalKey that denotes if the field is a user-defined field or not
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API closes multiple tickets at once.
Credit: 1 credit/2 records
list
requiredIDs of tickets to close. Note : A maximum of 50 tickets can be closed in a single API request.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API marks a ticket as read by the user.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API marks a ticket as unread by the user.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API marks tickets as spam.
Credit: 1 credit/2 records
boolean
requiredKey that marks or unmarks a single ticket or multiple tickets as spam
list
requiredID(s) of the ticket(s) that must be marked or unmarked as spam
boolean
optionalKey that marks or unmarks the associated contact as spam
boolean
optionalKey that marks or unmarks the other tickets from the contact(s) as spam
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API returns the number of tickets in a particular view.
Credit: 50 credits/call
long
requiredID of the view whose ticket count must be fetched
String
requiredID of the department from which the ticket count must be fetched
long
optionalID of the agent assigned to resolve the tickets
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API returns the number of tickets assigned to multiple agents.
Credit: 50 credits/call
String
optionalID of the department from which the ticket count must be fetched. To fetch ticket count of agents from all departments, pass the value allDepartments.
long
optionalIDs of the agents whose ticket count must be fetched
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches details of all actions — called events — performed on a ticket and in the sub-tabs on the ticket detail page. To view a detailed documentation for this API, visit this page.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the events must be fetched
int
optional,Number of events to list
string
optional, Key that filters events, based on their type. Values allowed are: CommentHistory, TimeEntryHistory, TaskHistory, CallHistory, EventHistory, AttachmentHistory, ApprovalHistory, SuperviseHistory, WorkflowHistory, MacroHistory, AssignmentRuleHistory, NotificationRuleHistory, SLAHistory, BlueprintHistory and SkillRelatedHistory
long
optionalKey that filters details of actions performed by a particular agent. Value allowed is the agent's ID in Zoho Desk.
string
optional,Key that filters the history of a particular field. The value for this key must be the apiName of the field.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches details related to the resolution of a ticket.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the resolution history of a ticket
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optionalIndex number starting from which records must be fetched
int
optional,Number of records to fetch
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API updates the resolution field of a ticket.
Credit: 1 credit/call
string
optional,Content to add in the field
boolean
optionalKey that specifies if the contact associated must be notified about the resolution
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API deletes a resolution added to a ticket.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.DELETE
Request Example
Response Example
This API fetches details related to the response and resolution times of a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API deletes all spam tickets.
Credit: 500 credits/call
OAuth Scope
Desk.tickets.DELETE
Request Example
Response Example
This API assigns tickets to agents according to their designated skills and routing preferences.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API removes existing skills and reapplies the required ones based on the ticket's current circumstances.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API suggests help articles that could be relevant to resolving a ticket.
Credit: 3 credits/call, 1 credit (with unique ID)
int
optional,Index number, starting from which the articles must be fetched
int
optional,Number of articles to list
long
optionalID of the department to which the help article belongs. If you want to include help articles from all departments, pass 0 as the value of this key
OAuth Scope
Desk.articles.READ
Request Example
Response Example
Threads are conversations that occur between agents and customers. A thread can originate from multiple channels, such as FACEBOOK, TWITTER, EMAIL, TWITTER_DM, WEB, ONLINE_CHAT, OFFLINE_CHAT, FORUMS, TWILIO, ZTI, CUSTOMERPORTAL, FEEDBACK, FEEDBACK_WIDGET.
long
ID of the thread
string
Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .
string
Status of the thread.Values supported are SUCCESS,PENDING,FAILED,DRAFT
string
Content of the thread
string
Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).
boolean
Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.
boolean
Specifies whether the thread is Private or Public. Forwarded threads are always private.
long
ID of the thread to which current thread is a reply, applicable only for EMAIL channel
list
List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.
timestamp
Time of creating the thread
string
Key that returns whether the thread is incoming or outgoing
string
Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.
string
To email ID in the thread, applicable only for EMAIL channel
string
Email ID to be CC-ed. Applicable only for EMAIL channel
string
Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel
string
Phone number through which the thread originated, applicable only for the ZTI and TWILIO
string
Summary of the thread
boolean
States whether the thread has attachments
boolean
Key that denotes if the thread is the description of the ticket
object
Secondary information related to the channel of the thread. Currently, this key is supported only for the Forums channel. Therefore, the API response will not return this information for threads generated through other channels
list
Actions available from the present state which will be included based on present status.It is a collection of all actions and each action has a rel,href and method.The respective links and methods to be invoked will be available under the 'href' and 'method' key for each action.
string
Time taken by the agent to respond to the customer
boolean
Specifies whether replies can be added be added to this thread.
string
Status of the ticket. Includes the custom statuses configured in your help desk portal.
Example
This API fetches a single thread from your help desk portal.
Credit: 1 credit/call
string
optional,Content of the thread in plain text format. Value allowed is plainText.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API get the orginal mail content including mail headers
Credit: 1 credit/call
boolean
optionalset this param as true if attachment is to be rendered
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the most recent thread of a ticket.
Note:
The API response for 'Get Latest Thread' will be dynamic, based on the channel from which the latest thread is received. For example, if the latest thread is received via the Email channel, the API will return the keys cc, to, and bcc, along with other details. These keys will not be included in the response for threads received via other channels.
Credit: 1 credit/call
boolean
optional,Key that denotes if the thread must be a public thread
boolean
optional,Key that denotes if the thread must be an incoming threads only
string
optional,Content of the thread in plain text format. Value allowed is plainText.
string
optional,Receipt status of the thread. Values allowed are success and failed
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API saves drafts of agent's responses to customers and sends them to a manager/senior agent for review.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API lists all threads in your helpdesk.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the threads must be fetched
integer
required,Number of threads to fetch
string
optional,Key that sorts the threads by sendDateTime.
If the value of sortBy key is:
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists a particular number of threads and comments recorded on a ticket, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Starting index from which the conversations should be fetched.
integer
required,Number of conversations to fetch
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API sends a reply to any of the configured non-system channels. The channel must be able to handle the reply otherwise the reply will fail. Available channels to be used in this API can be fetched using Get Channels API.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API sends an email reply. The from address in the email must be a from address configured in your help desk portal.
Credit: 1 credit/5 recipients
boolean
optional,Specify whether the thread is Private
boolean
optional,Specify whether the reply has to sent immediately
string
optional,Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .
string
required,Content of the thread
string
optional,Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).
boolean
optionalKey that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.
boolean
optionalSpecifies whether the thread is Private or Public. Forwarded threads are always private.
long
optionalID of the thread to which current thread is a reply, applicable only for EMAIL channel
list
optionalList of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.
string
optional,Key that returns whether the thread is incoming or outgoing
string
optional,Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.
string
optional,To email ID in the thread, applicable only for EMAIL channel
string
optional,Email ID to be CC-ed. Applicable only for EMAIL channel
string
optional,Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel
boolean
optionalStates whether the thread has attachments
string
optional,Status of the ticket. Includes the custom statuses configured in your help desk portal.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API adds a reply to a Facebook post
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API sends a reply to a tweet.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API sends a reply to a comment on a forum post. While using this API, make sure to add the _ZohoDiscussions.basic.ALL_ scope in the request.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API drafts an email reply. The from address in the email must be a from address configured in your help desk portal.
Credit: 1 credit/call
string
optional,Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .
string
required,Content of the thread
string
optional,Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).
boolean
optionalKey that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.
boolean
optionalSpecifies whether the thread is Private or Public. Forwarded threads are always private.
long
optionalID of the thread to which current thread is a reply, applicable only for EMAIL channel
list
optionalList of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.
string
optional,Key that returns whether the thread is incoming or outgoing
string
optional,Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.
string
optional,To email ID in the thread, applicable only for EMAIL channel
string
optional,Email ID to be CC-ed. Applicable only for EMAIL channel
string
optional,Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel
boolean
optionalStates whether the thread has attachments
string
optional,Status of the ticket. Includes the custom statuses configured in your help desk portal.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API drafts a reply to a Facebook post.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API drafts a reply to a forum post.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API updates a draft thread created via the EMAIL, FACEBOOK, or FORUM channel.
Credit: 1 credit/call
string
optional,Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .
string
optional,Content of the thread
string
optional,Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).
boolean
optionalKey that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.
boolean
optionalSpecifies whether the thread is Private or Public. Forwarded threads are always private.
long
optionalID of the thread to which current thread is a reply, applicable only for EMAIL channel
list
optionalList of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.
string
optional,Key that returns whether the thread is incoming or outgoing
string
optional,Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.
string
optional,To email ID in the thread, applicable only for EMAIL channel
string
optional,Email ID to be CC-ed. Applicable only for EMAIL channel
string
optional,Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel
boolean
optionalStates whether the thread has attachments
string
optional,Status of the ticket. Includes the custom statuses configured in your help desk portal.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API deletes an attachment from a draft thread.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Ticket comments are discussions related to a ticket, primarily between agents in your help desk portal. Private comments are visible only to agents, while public comments are displayed on the customer portal.
long
ID of the comment
string
The comment content.
To mention an agent:
zsu[@user:{zuid}]zsu
To mention a team:
zsu[@team:{teamId}_{teamName}]zsu
Note: This format can also be used to retrieve agent information.
boolean
Specifies the comment is public or private.
Note: This key's value can only be set when adding a comment.
long
ID of the user who added the comment.
timestamp
Time at which the comment was added.
timestamp
Time at which the comment was last modified.
list
List of file attachments included in the comment.
Note: For more details on attachments, refer to the Uploads section.
string
Specifies the type of the content whether html or plainText. The default value is html.
Example
This API allows you to add a comment to a ticket. To mention an agent or team, use the below format:
Credit: 1 credit/call
string
optional,The comment content.
To mention an agent:
zsu[@user:{zuid}]zsu
To mention a team:
zsu[@team:{teamId}_{teamName}]zsu
Note: This format can also be used to retrieve agent information.
boolean
optionalSpecifies the comment is public or private.
Note: This key's value can only be set when adding a comment.
list
optionalList of file attachments included in the comment.
Note: For more details on attachments, refer to the Uploads section.
string
optional,Specifies the type of the content whether html or plainText. The default value is html.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API allows you to update a comment to a ticket. To mention an agent or team, use the below format:
Credit: 1 credit/call
string
optional,The comment content.
To mention an agent:
zsu[@user:{zuid}]zsu
To mention a team:
zsu[@team:{teamId}_{teamName}]zsu
Note: This format can also be used to retrieve agent information.
boolean
optionalSpecifies the comment is public or private.
Note: This key's value can only be set when adding a comment.
list
optionalList of file attachments included in the comment.
Note: For more details on attachments, refer to the Uploads section.
string
optional,Specifies the type of the content whether html or plainText. The default value is html.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API deletes a comment.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API fetches a ticket comment from your help desk portal.
Credit: 1 credit/call
String
optionalSecondary information related to the comments The allowed values are mentions and plainText. In the API request, you can pass mention, plainText, or both by using commas to separate them.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists a particular number of comments recorded on a ticket, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number starting from which the comments must be fetched
integer
required,Number of comments to fetch
string
optional,Sort by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.
String
optionalSecondary information related to the comments The allowed values are mentions and plainText. In the API request, you can pass mention, plainText, or both by using commas to separate them.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the history of comments recorded on a ticket, including instances of adding and editing the comments.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the comment activities must be fetched
String
optionalSecondary information related to the comments The allowed values are mentions and plainText. In the API request, you can pass mention, plainText, or both by using commas to separate them.
integer
required,Number of comment activities to fetch
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
Ticket time entry refers to the time taken by an agent to resolve a ticket.
long
ID of the time entry
long
ID of the ticket
string
Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.
long
ID of the user associated with the time entry
timestamp
Time when work related to the time entry was started.
integer
Number of hours in the time entry.
integer
Number of minutes in the time entry.
integer
Number of seconds in the time entry.
double
Per hour cost of an agent.
double
Additional cost incurred
double
Total cost incurred
double
Fixed cost
string
Description of the time entry
deprecated
list
User-defined fields related to the time entry.
JSONObject
User-defined fields related to the time entry.
timestamp
Time of creating the ticket time entry
timestamp
Time of modifying the ticket time entry
string
User who created the time entry.
string
User who modified the time entry.
String
Mode configured in time tracking. Supported values are Manual and Auto
boolean
Billing Preference
String
Billing type configured in the time tracking. Possible values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE
long
ID of the invoice related to the time entry
Example
This API fetches a time entry recorded for a ticket.
Credit: 1 credit/call
string
optional,Secondary information related to the time entry. Value supported is owner.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists the time entries associated with a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Module from which the time entries must be fetched. Values allowed are tickets and tasks.
integer
optionalIndex number, starting from which the time entries must be fetched
integer
optional,Number of time entries to fetch
String
optionalKey that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.
string
optional,Secondary information related to the time entry. Value supported is owner.
String
optionalKey that filters time entries, based on their billing status: nonBillable , billable or billed
timestamp
optionalKey that filters time entries created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.
timestamp
optionalKey that filters time entries whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API adds a time entry in your help desk
Credit: 1 credit/call
string
optional,Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.
long
optionalID of the user associated with the time entry
timestamp
requiredTime when work related to the time entry was started.
integer
optional,Number of hours in the time entry.
integer
optionalNumber of minutes in the time entry.
integer
optionalNumber of seconds in the time entry.
double
optionalPer hour cost of an agent.
double
optionalAdditional cost incurred
double
optionalFixed cost
string
optional,Description of the time entry
deprecatedlist
optionalUser-defined fields related to the time entry.
JSONObject
optionalUser-defined fields related to the time entry.
String
optionalMode configured in time tracking. Supported values are Manual and Auto
boolean
optionalBilling Preference
long
optionalID of the invoice related to the time entry
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API updates an existing ticket time entry
Credit: 1 credit/call
string
optional,Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.
long
optionalID of the user associated with the time entry
timestamp
optionalTime when work related to the time entry was started.
integer
optional,Number of hours in the time entry.
integer
optionalNumber of minutes in the time entry.
integer
optionalNumber of seconds in the time entry.
double
optionalPer hour cost of an agent.
double
optionalAdditional cost incurred
double
optionalFixed cost
string
optional,Description of the time entry
deprecatedlist
optionalUser-defined fields related to the time entry.
JSONObject
optionalUser-defined fields related to the time entry.
String
optionalMode configured in time tracking. Supported values are Manual and Auto
boolean
optionalBilling Preference
long
optionalID of the invoice related to the time entry
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API deletes a time entry recorded for a ticket
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API fetches the sum of time entries associated with a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Module from which the time entries must be fetched. Values allowed are tickets and tasks.
String
optionalKey that filters time entries, based on their billing status: nonBillable , billable or billed
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches time entries for a ticket created after recently modified time of the given billing type from your help desk
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
requiredAllowed values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT SPECIFIC_COST_PER_PROFILE
integer
optionalIndex number, starting from which the time entries must be fetched
integer
optional,Number of time entries to fetch
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
Ticket timer is a feature that records the time an agent spends on resolving a ticket.
integer
No. of hours spent
integer
No. of minutes spent
integer
No. of seconds spent
integer
State of the timer. States can be RUNNING, PAUSED, INIT
Example
This API fetches the time elapsed in the ticket timer, along with the current state
Credit: 1 credit/call
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API performs timer-related actions, such as START, STOP, PAUSE and RESUME
Credit: 1 credit/call
String
required Action of the timer.Supported actions are START, STOP, PAUSE and RESUME
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Ticket attachments are files you attach to a ticket to aid quick resolution.
long
ID of the attachment Note : This ID can be used only by the user who uploaded the attachment. If another user tries to use the attachment ID in other APIs such as sendEmailReply, draftEmailReply, etc an error will be thrown.
long
ID of user who attached the file
timestamp
Time of attaching the file
string
Name of the attachment
boolean
Key that returns if the attachment is public or not
long
Size of the attachment
Example
This API lists the files attached to a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.
integer
optionalIndex number, starting from which the attachments must be fetched
integer
optional,Number of attachments to fetch
Boolean
optionalKey that returns if the attachment is public or no
string
optional,Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API attaches a file to a ticket.
Credit: 1 credit/call
Boolean
optionalField that determines whether the attachment is public or private
Content-Type:multipart/form-data
File to attach to the ticket
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API updates an existing attachment.
Credit: 1 credit/call
boolean
optionalWhether to Show
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API deletes an attachment from a ticket.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Often, customer support agents do not have the authority to make decisions related to ticket resolution. When the intervention of a support manager or any other higher authority is required in the decision-making process, the agent can submit the ticket for approval.
list
IDs of users to whom the approval must be submitted
string
Subject of the approval
string
Status of the approval
String
Description of the approval
timestamp
Time when the approval was requested
timestamp
Time when the approval was processed
long
ID of the approval
Example
This API lists the approvals submitted in your help desk.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number starting from which the approvals must be fetched
integer
optional,Number of approvals to fetch
string
optional,Key that filters the approvals by status
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the details of an approval.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API creates an approval in your help desk.
Credit: 1 credit/call
list
requiredIDs of users to whom the approval must be submitted
string
required,Subject of the approval
string
optional,Status of the approval
String
optionalDescription of the approval
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API updates the details of an existing ticket approval.
Credit: 1 credit/call
list
optionalIDs of users to whom the approval must be submitted
string
optional,Subject of the approval
string
optional,Status of the approval
String
optionalDescription of the approval
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Ticket followers are users who follow a ticket to track the progress made in resolving it.
long
ID of the user
string
Name of the user
string
Name of the user
string
Email ID of the user
string
URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.
string
Key that returns the module being followed. Values allowed are tickets, contacts, or accounts
Example
This API adds one or more users to the followers list of a ticket.
Credit: 1 credit/call
list
requiredthe list of ids to be added as follower
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API removes one or more users from the followers list of a ticket.
Credit: 1 credit/call
list
requiredthe list of ids to be added as follower
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API fetches the list of users following a ticket.
Note:
Sometimes, followers of a contact/account indirectly end up as ticket followers if the ticket is associated with the contact/account they follow. In that case, the following key returns the value of the original module the user follows--*contact* or account.
Even in a case where the user first followed the ticket and then followed the contact/account associated with it, the following key returns the value contact or account. This is because the contact/account is the parent resource of the ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
Ticket tags refer to the keywords added to tickets to ensure quick grouping, filtering, and reference.
This API searches for tags added in your help desk portal.
Credit: 3 credits/call, 1 credit (with unique ID)
int
optionalIndex number, starting from which the tags must be fetched
int
optional,Number of tags to fetch
long
requiredID of the department from which the tags must be fetched.
String
optionalSearch keyword related to the tag.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists the ticket tags added in your help desk portal.�
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the tags must be fetched
string
optional,Key that sorts tags by a specific attribute: createdTime or count. The default sorting order is descending.
int
optionalIndex number, starting from which the tags must be fetched
int
optional,Number of tags to fetch
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists tickets containing the tag specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optionalIndex number, starting from which tickets must be fetched.
int
optional,Number of tickets to list
string
optional,User assigned to resolve the ticket. Values allowed are Unassigned or a valid assigneeId. You can pass multiple assigneeIds as comma-separated values.
string
optional,Channel through which the tickets were received. You can pass multiple values by separating them with commas.
string
optional,Resolution status of the tickets. You can pass multiple values by separating them with commas.
integer
optionalNumber of days since the tickets were received. Values allowed are 15, 30 , 90.
string
optional,Priority of the tickets. You can pass multiple values by separating them with commas.
string
optional,Key that sorts the tickets by a specific attribute: dueDate, recentThread, createdTime, or ticketNumber. The default sorting order is ascending. A - prefix denotes a descending order of sorting.
string
optional,Additional information related to the tickets. Values allowed are: contacts, products, departments, team, isRead and assignee. You can pass multiple values by separating them with commas.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API adds a single tag or multiple tags to a ticket.
Credit: 1 credit/call
list
requiredNames of the tags
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API removes a single tag or multiple tags from a ticket.
Credit: 1 credit/call
list
requiredNames of the tags
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API lists tags associated with a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists the five most recent tags associated with tickets.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the tags must be fetched
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API adds a tag to the list of recently viewed tags. tag_id is a mandatory parameter in the API request.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.CREATE
Request Example
Response Example
This API replaces a tag to the specified tag. tag_id is a mandatory parameter in the API request.
Credit: 500 credits/call
long
optionalTag ID of the Replacing Tag
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Ticket templates are provisions that automatically populate predefined values in ticket fields, thereby helping users save time and effort while adding new tickets.
long
ID of the ticket template
string
Name of the ticket template
boolean
Key that specifies if the template must be displayed in the help center or not
long
ID of the ticket layout from which the template is derived
list
Values to auto-populate in the different fields in the template
Example
This API helps create a ticket template in your help desk portal.
Credit: 1 credit/call
string
required,Name of the ticket template
boolean
optionalKey that specifies if the template must be displayed in the help center or not
list
requiredValues to auto-populate in the different fields in the template
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API fetches the details of a particular ticket template.
Credit: 1 credit/call
string
optional,Additional information related to the template. Values allowed are: contacts, products, departments, team, and assignee. You can pass multiple values by separating them using commas in the API request.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API lists a particular number of ticket templates, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optional,Index number, starting from which the templates must be fetched
long
optionalID of the department from which templates must be fetched
long
optionalID of the layout from which templated must be fetched for the given department ID
integer
required,Number of templates to list. The default value is 10 and the maximum value supported is 100
boolean
optionalVisibility of the templates in the help center
deprecatedString
optionalName of the template
String
optionalString to search for ticket templates by ticket template name
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API helps update the details of a particular ticket template.
Credit: 1 credit/call
string
optional,Name of the ticket template
boolean
optionalKey that specifies if the template must be displayed in the help center or not
list
optionalValues to auto-populate in the different fields in the template
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a ticket template from your help desk portal.
Credit: 6 credits/record
list
requiredArray of Entity id to be deleted
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
A ticket in a support system often includes multiple conversations. As a result, crucial information might not be easily accessible.This feature allows users to pin threads or comments, ensuring they are prominently displayed whenever the ticket is viewed.
string
The type of entity to pin. The allowed values are COMMENTS and THREADS
boolean
The visibility of the pin.
long
ID of the entity to pin.
list
IDs of the pins to delete.
Example
This API creates a new pin on the ticket.
Credit: 1 credit/call
string
required,The type of entity to pin. The allowed values are COMMENTS and THREADS
boolean
optionalThe visibility of the pin.
long
requiredID of the entity to pin.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
This API fetches the list of pins of a particular ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,The type of pins to fetch as a comma separated list. The allowed values are comments and threads
string
optional,Secondary information related to the pinned conversations. Values allowed are pinnedBy, and mentions.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API deletes one or more pins from a ticket.
Credit: 1 credit/call
list
requiredIDs of the pins to delete.
OAuth Scope
Desk.tickets.UPDATE
Request Example
Response Example
Ticket count refers to the number of tickets raised across all the departments in your help desk.
Note:
1. Query parameters, especially those of string type, pertaining to count APIs must be URL-encoded.
2. New resources added to your help desk might take some time to be indexed for search. Therefore, if API responses do not reflect the updated ticket count, wait for a few minutes and try again.
Example of CustomField Data Without URL Encoding:
customField1=cf_ModelName:F3z3
customField2=cf_phone:9022334455
customField3=cf_permanentAddress: Wall Street
Example of CustomField Data with URL Encoding:
customField1=cf_ModelName%3AF3z3
customField2=cf_phone%3A9022334455
customField3=cf_permanentAddress%3AWall%20Street
This API returns the ticket count of your help desk.
Credit: 50 credits/call
long
optionalID of the department from which ticket count must be fetched. If you do not pass this parameter in the API request, ticket count across all departments will be returned.
long
optionalID of the agent assigned to resolve the ticket
long
optionalID of the contact who raised the ticket
String
optionalCategory of the ticket
String
optionalUser-defined field in the ticket
String
optionalUser-defined field in the ticket
String
optionalUser-defined field in the ticket
timestamp
optionalKey that filters tickets created in a particular period of time.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;
For example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z
timestamp
optionalKey that filters tickets modified in a particular period of time.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;
For example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z
OAuth Scope
Desk.search.READ , Desk.tickets.READ
Request Example
Response Example
This API returns the ticket count of your help desk, filtered by a specific field.
Credit: 50 credits/call
long
optionalID of the department from which ticket count must be fetched. If you do not pass this parameter in the API request, ticket count across all departments will be returned.
long
optionalID of the agent assigned to resolve the ticket
long
optionalID of the contact who raised the ticket
long
optionalID of the account to which the ticket is mapped
String
optionalCategory of the ticket
String
optionalUser-defined field in the ticket
String
optionalUser-defined field in the ticket
String
optionalUser-defined field in the ticket
timestamp
optionalKey that filters tickets created in a particular period of time.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;
For example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z
timestamp
optionalKey that filters tickets modified in a particular period of time.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;
For example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z
String
requiredField by which the ticket count must be filtered. Values allowed are. status, priority, channel, statusType, spam, escalated, overDue
OAuth Scope
Desk.search.READ , Desk.tickets.READ
Request Example
Response Example
Time tracking refers to the process of recording the time agents take to resolve tickets. This information can be recorded manually or automatically, based on your organization's requirement and preference. APIs related to this endpoint help you configure the settings for automated time tracking.
boolean
Time tracking refers to the process of recording the time agents take to resolve tickets. This information can be recorded manually or automatically, based on your organization's requirement and preference. APIs related to this endpoint help you configure the settings for automated time tracking.
long
ID of the department in which time tracking must be enabled or disabled.
boolean
Key that returns if the time tracked is billable or not.
String
Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE
Double
Cost fixed for either billing category - by ticket or by agent.
list
List of agents in the department
list
List of user profiles defined in the department
String
Action that the active timers in the department must perform. Values supported are ADD and DISCARD
list
Activity preference(s)
list
Ticket preference(s)
Example
This API adds a TimeTracking configuration to your helpdesk.
Credit: 1 credit/call
boolean
requiredTime tracking refers to the process of recording the time agents take to resolve tickets. This information can be recorded manually or automatically, based on your organization's requirement and preference. APIs related to this endpoint help you configure the settings for automated time tracking.
long
requiredID of the department in which time tracking must be enabled or disabled.
boolean
optionalKey that returns if the time tracked is billable or not.
String
optionalType of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE
Double
optionalCost fixed for either billing category - by ticket or by agent.
list
optionalList of agents in the department
list
optionalList of user profiles defined in the department
String
optionalAction that the active timers in the department must perform. Values supported are ADD and DISCARD
list
optionalActivity preference(s)
list
optionalTicket preference(s)
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates an existing TimeTracking configuration.
Credit: 1 credit/call
boolean
optionalTime tracking refers to the process of recording the time agents take to resolve tickets. This information can be recorded manually or automatically, based on your organization's requirement and preference. APIs related to this endpoint help you configure the settings for automated time tracking.
long
optionalID of the department in which time tracking must be enabled or disabled.
boolean
optionalKey that returns if the time tracked is billable or not.
String
optionalType of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE
Double
optionalCost fixed for either billing category - by ticket or by agent.
list
optionalList of agents in the department
list
optionalList of user profiles defined in the department
String
optionalAction that the active timers in the department must perform. Values supported are ADD and DISCARD
list
optionalActivity preference(s)
list
optionalTicket preference(s)
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API fetches the details of the TimeTrack Settings configured in your helpdesk.
Credit: 1 credit/call
long
requiredID of the department
OAuth Scope
Desk.settings.READ
Request Example
Response Example
This API fetches the history of changes made to the billing preferences in time tracking settings. The different events supported are BILLING_PREFERENCE_ENABLED, BILLING_PREFERENCE_DISABLED, BILLING_TYPE_SELECTED, BILLING_TYPE_CHANGED, FIXED_COST_ENTERED, FIXED_COST_EDITED, AGENT_ADDED, AGENT_COST_EDITED, AGENT_DELETED, PROFILE_ADDED, PROFILE_COST_EDITED, and PROFILE_DELETED.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the history must be fetched.
int
optionalIndex number, starting from which the events must be fetched.
int
optional,Number of events to be fetched.
string
optional,Secondary information related to the time entry. Value supported is owner.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Active timer will fetch currently active [either running (or) paused] timer(s) details
Example
This API fetches currently running timer details for an agent
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
Integer
optional,limit
Integer
optionalfrom
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists a particular number of currently active timers in a department, based on the limit specified.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department from which the timers must be fetched
string
optional,Zoho Desk modules from which the timers must be fetched. Values allowed are: Tickets, Tasks, Events, and Calls. You can pass multiple values by separating them using commas. If you do not pass a value, all modules are considered.
long
optionalPoint of time before or after which the timers were started. This parameter works in conjunction with the sortBy parameter. If the value of sortBy is startTime, the timers are listed in ascending order. If the value of sortBy is -startTime, they are listed in descending order. (Note: With startTime in play, the time value associated with the last timer in an API response is considered as the value from which the next set of timers must be fetched in the subsequent response.)
Integer
optional,Number of timers to list
string
optional,Key that sorts the timers from oldest to latest (ascending order) or latest to oldest (descending order). Values allowed are: startTime (ascending order) and -startTime (descending order, which is the default sorting order).
long
optionalKey that filters timers by Owner. Values allowed are any valid Owner ID or multiple Owner IDs separated by commas.
OAuth Scope
Desk.tickets.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ
Request Example
Response Example
This API fetches the details of timers currently active in a ticket.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the timers must be fetched
integer
optional,Number of timers to fetch
string
optional,Secondary information related to the timers. Value supported is owner.
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the details of timers currently active in a task.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
integer
optionalIndex number, starting from which the timers must be fetched
integer
optional,Number of timers to fetch
string
optional,Secondary information related to the timers. Value supported is owner.
OAuth Scope
Desk.activities.READ
, Desk.activities.tasks.READ
,
Desk.tasks.READ
Request Example
Response Example
This functionality is used to collect customer feedback for outgoing ticket replies. It is essential to ensure that the feedback feature is enabled for the department associated with the ticket to get feedback on the ticket’s outgoing response.
Get customer feedback list for a given department. You can also use any one of the sub modules: agentId, contactId, accountId, or ticketId at a time.
Credit: 50 credits/call
String
requiredMandatory param to fetch the customer-happiness list for a given ID of the department. You can also provide department as allDepartment to fetch customer happiness from all departments
Long
optionalFilter that returns the customer-happiness list for a particular agent
Long
optionalFilter that returns the customer-happiness list for a particular contact
Long
optionalFilter that returns the customer-happiness list for a particular account
Long
optionalFilter that returns the customer-happiness list for a particular ticket
Long
optionalStart time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds
Long
optionalStart time till which the customer-happiness list should show. End time should be in GMT time zone and in milliseconds
int
optionalThe starting index from which the list should be displayed based on the time of receiving customer feedback
int
optional,Number of ratings to be displayed in the list
string
optional,Segregate the list based on the type of rating. Allowed values are good, ok, or bad
string
optional,Period from which the customer happiness rating must be fetched. Values allowed are: TODAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_7_DAYS, YESTERDAY, LAST_1_HOUR, CUSTOM_IN_DATE, LAST_100_RATINGS, LAST24HOURS and LAST_30_DAYS
timestamp
optionalstart date time
timestamp
optionalend date time
string
optional,Sorted by ratedtime
string
optional,Allowed values are : contacts, tickets, agents. You can include both by separating them with a comma in the query param.
OAuth Scope
Desk.search.READ , Desk.tickets.READ
Request Example
Response Example
This API gives you the count of the ratings given by the customers for each category of a given department. You can also use any one of the sub modules: agentId, contactId, accountId, or ticketId at a time.
Credit: 50 credits/call
String
requiredMandatory param to fetch the customer-happiness list for a given ID of a department. You can also provide department as allDepartment to fetch customer-happiness list from all the departments
Long
optionalFilter that returns the customer-ratings count for a particular agent
Long
optionalFilter that returns the customer-ratings count for a particular contact
Long
optionalFilter that returns the customer-ratings count for a particular account
Long
optionalFilter that returns the customer-ratings count for a particular ticket
Long
optionalStart time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds
Long
optionalStart time till which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds
string
optional,Period from which the customer happiness rating must be fetched. Values allowed are: TODAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_7_DAYS, YESTERDAY, LAST_1_HOUR, CUSTOM_IN_DATE, LAST_100_RATINGS, LAST24HOURS and LAST_30_DAYS
timestamp
optionalstart date time
timestamp
optionalend date time
Integer
optionalThe from index
Integer
optional,Number of rating to be displayed
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API retrieves the content of specific customer feedback.
Credit: 1 credit/call
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API provides an html placeholder to insert the customer feedback link into the reply mail. The link, when clicked by the email recipient, leads them to a feedback form where they can provide their feedback.
Credit: 1 credit/call
Long
requiredID of the department for which the placeholder should be collected.
string
optional,Localization languageCode of Customer Happiness page to be displayed
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
Dashboards provide a visual representation of custom reports, allowing you to track key metrics at a glance. There are standard dashboards available by default, and users can also create their own dashboards by adding relevant components as needed.
This API fetches the number of tickets created in a particular duration.
Credit: 50 credits/call
string
required,Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the number of tickets that are in the on hold status.
Credit: 50 credits/call
string
required,Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the number of tickets that are resolved.
Credit: 50 credits/call
string
required,Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the number of tickets that have remained unresolved over a particular period.
Credit: 50 credits/call
string
required,Key that groups the ticket count according to a particular attribute.This value can be date channel agent
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists the durations taken to resolve tickets.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
required,Key that groups stats according to a specific attribute: date, channel, agent, or hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API lists the durations taken to respond to tickets.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
required,Key that groups stats according to a specific attribute: date, channel, agent, or hour
boolean
requiredKey that specifies if the response is the first response to the customer question
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the total number of responses sent/made by your agents.
Credit: 50 credits/call
string
required,Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
This API fetches the number of tickets that were reopened in your help desk portal.
Credit: 50 credits/call
string
required,Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour
long
optionalID(s) of the department(s) from which the stats must be fetched
long
optionalID(s) of the agent(s) whose stats must be fetched
long
optionalID(s) of the team(s) from which the stats must be fetched
String
requiredPredefined time range from which the stats must be fetched
string
optional,Starting date for defining custom time range
string
optional,Ending date for defining custom time range
string
optional,Channel through which the tickets were received
OAuth Scope
Desk.tickets.READ
Request Example
Response Example
Channels in Zoho Desk represents the source of the tickets & threads. A channel represents the characteristic of a reply source such as reply configuration.
string
Type of the channel. Possible values are SYSTEM, INTEGRATION, INSTANT_MESSAGE
string
Name of the channel
string
Unique Identifier Code of the channel
string
Name of the application that handles the channel
string
Photo URL of the channel
string
Default department ID of the channel in which the tickets will be created unless customized
string
Specifies whether the channel accepts replies for tickets or threads
JSONObject
Reply configuration of the channel if the channel accepts replies for tickets or threads
string
Type of integration, only if the type is INSTANT_MESSAGE
Example
This API fetches currently installed channels including System, Channel integration and Instant Messaging channels
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.basic.READ
Request Example
Response Example
MailReplyAddress refers to the email ID from which replies are sent to customers.
Example
This API fetches the details of a MailReplyAddress.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the mailReplyAddresses configured in your help desk portal.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the Department from which the addresses need to be queried.
boolean
optionalKey that returns if the mailReplyAddress is active or not
integer
optionalIndex number, starting from which the mail addresses must be fetched
integer
optional,Number of mail addresses to fetch
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API adds a MailReplyAddress to your help desk.
Credit: 1 credit/call
long
requiredID of the department in which the MailReplyAddress must be configured
string
required,Email ID to add
string
required,Display name for the MailReplyAddress
deprecatedboolean
optionalKey that enables or disables SMTP authentication for the MailReplyAddress
JSONObject
optionalDetails related to the SMTP authentication for the MailReplyAddress
string
optional,MailService Provider name
boolean
optionalKey specifying if this MailReplyAddress is the default reply-to address for the department
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates details of an existing MailReplyAddress.
Credit: 1 credit/call
long
optionalID of the department(s) in which the MailReplyAddress is configured
string
optional,Display Name
boolean
optionalKey that returns if the MailReplyAddress is active or not
deprecatedboolean
optionalIs SMTP Enabled
string
optional,MailService Provider name
JSONObject
optionalDetails related to the SMTP authentication for the MailReplyAddress
boolean
optionalKey specifying if this MailReplyAddress is the default reply-to address for the department
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a MailReplyAddress from your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
This API sends a verification link to the MailReplyAddress configured in your help desk portal.
Credit: 1 credit/call
OAuth Scope
Desk.settings.CREATE , Desk.basic.CREATE
Request Example
Response Example
SupportEmailAddress refers to the email ID to which customer correspondences are forwarded.
Example
This API fetches the details of a SupportEmailAddress.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the SupportEmailAddresses configured in your help desk.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredID of the department(s) from which the SupportEmailAddresses must be fetched.
integer
optionalIndex number, starting from which the mail addresses must be fetched
integer
optional,Number of mail addresses to fetch
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API adds a SupportEmailAddress to your help desk.
Credit: 1 credit/call
long
requiredID of the department in which the SupportEmailAddress must be configured
string
required,Display name for the SupportEmailAddress
string
required,Email ID to add
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
This API updates details of an existing SupportEmailAddress.
Credit: 1 credit/call
long
optionalID of the department in which the SupportEmailAddress is configured
string
optional,Display name for the SupportEmailAddress
boolean
optionalKey that returns if the SupportEmailAddress fetches emails or not
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API deletes a SupportEmailAddress from your help desk.
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
When you sign up for Zoho Desk, you are provided with one default support email address: support@mycompany.zohodesk.com. The "mycompany" part of the email address represents the portal name that you initially signed up with.Emails received at this address become tickets. This address is also used as the "From" address in replies to users.
Example
This API updates the subdomain (the "mycompany" part) of the support email address.
1. Only the primary contact of the organization can update the subdomain of the support email address.
2. The new support email address will be support@zylker.com.3. The updated support email address will be used for fetching emails, henceforth. So make sure that you update the new address in the forwarding configurations of your mailbox.
4. The new support email address is applicable only for the default department.5. All existing email aliases along with the old support email address will be permanently deleted from your account.
6. Emails forwarded to the old support address will not be fetched in.
Credit: 1 credit/call
string
optional,Name of the new email subdomain
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API fetches the subdomain of the support email address.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
MailConfiguration refers to the secondary configurations related to the email addresses in your help desk portal.
Example
This API lists the MailConfigurations set for a specific department.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API lists the MailConfigurations set for the entire help desk portal.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API updates the MailConfigurations set for a specific department.
Credit: 1 credit/call
boolean
optionalKey that enables or disables auto CC of email replies to your
boolean
optionalKey that enables or disables creation of contacts from 'Reply To' email addresses
boolean
optionalKey that enables or disables display of the agent's name in replies to customers
boolean
optionalKey that enables or disables creation of tickets on behalf of the sender while forwarding emails
boolean
optionalKey that enables or disables private thread handling
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
This API updates the MailConfigurations set for the entire help desk portal.
Credit: 1 credit/call
boolean
optionalKey that enables or disables auto CC of email replies to your
boolean
optionalKey that enables or disables creation of contacts from 'Reply To' email addresses
boolean
optionalKey that enables or disables display of the agent's name in replies to customers
boolean
optionalKey that enables or disables creation of tickets on behalf of the sender while forwarding emails
boolean
optionalKey that enables or disables private thread handling
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Templates provide the data needed to construct the modules
Example
Add a new Template
Credit: 1 credit/call
string
required,The name of the Template
string
required,The Subject of the template
string
required,The recordType of the template can be contacts, accounts, tickets, products, tasks
long
requiredThe department of the template
long
requiredThe folder of the template
string
required,The from email of the template
string
optional,The reply to mail id
string
optional,the body of the template
string
required,content type of the template
list
optionalList of file attachments in the template
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
View a particular Template
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Update an existing Template
Credit: 1 credit/call
string
optional,The name of the Template
string
optional,The Subject of the template
string
optional,The recordType of the template can be contacts, accounts, tickets, products, tasks
long
optionalThe department of the template
long
optionalThe folder of the template
string
optional,The from email of the template
string
optional,The reply to mail id
string
optional,the body of the template
string
optional,content type of the template
list
optionalList of file attachments in the template
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Delete a Template
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
List all Templates
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredthe corresponding department to be fetched
string
optional,The name of the module
integer
required,from index, DEFAULT 1
integer
required,number of templates to be retrieved Range 1-1000, DEFAULT 1000
string
optional,String to search for templates by name. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for templates whose name start with the string, 2) *string* - Searches for templates whose name contain the string, 3) string - Searches for templates whose name is an exact match for the string
long
optionalthe corresponding folder to be fetched
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Render an exisiting Template into reply
Credit: 1 credit/call
long
requiredThe id of the entity can be contact,ticket or account
String
optionalSource from which template content has to be rendered. Values can be TICKET_REPLY , NOTIFICATIONS , AUTOMATION_ALERTS , SLA
OAuth Scope
Desk.settings.READ
Request Example
Response Example
List the placeholders supported in emailTemplates
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
String
requiredTo get placeholders for this module.Allowed values are tickets,tasks,contacts,accounts,products,solutions,calls,events
Long
requiredTo get placeholders for this departmentId
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Cloning an exisiting Template's attachments
Credit: 25 credits/call
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
A pack of Email templates
Example
Adding a Template Folder
Credit: 1 credit/call
string
required,name of the template folder
string
optional,the description of the folder
long
requiredthe id of the department
OAuth Scope
Desk.settings.CREATE
Request Example
Response Example
Listing a particular Template Folder
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ
Request Example
Response Example
Updating a Template Folder
Credit: 1 credit/call
string
optional,name of the template folder
string
optional,the description of the folder
long
optionalthe id of the department
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Delete a Template Folder
Credit: 1 credit/call
OAuth Scope
Desk.settings.DELETE
Request Example
Response Example
List all Template Folders in alphabetical order
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
requiredthe corresponding department to be fetched
integer
required,from index, DEFAULT 1
integer
required,number of folders to be retrieved Range 1-50, DEFAULT 50
string
optional,Meta information related to the template Folder. Values allowed are: smsTemplatesCount, emailTemplatesCount. You can pass multiple values by separating them with commas in the API request.
OAuth Scope
Desk.settings.READ
Request Example
Response Example
A channel refers to the platform or medium through which a message is sent or received. In IM a channel is created using configuration parameters, refer to the settings that can be adjusted to customize the behaviour of the channel.
long
Channel ID of the channel
string
Account name of the channel
string
Integration Service of the channel. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER
long
Bot ID of the channel
string
Name of the channel
boolean
Is channel Active ?
boolean
Is storage enabled for the channel ?
boolean
Is sandbox channel ?
timestamp
Channel creation time
long
Agent Id who created the channel
boolean
Is authorization pending ?
boolean
Is channel subscribed ?
string
Authentication Url
boolean
Is the agent owner of the channel ?
long
Total conversation count of the channel
string
Universal link of the channel
boolean
Is channel deleted ?
string
Photo Url of the channel
long
Department Id for which channel is associated
string
App name and channel name is same for a IM channel
string
Code Name of the channel. This is uniquely generated while creating a channel by using the channel name.
JSONArray
ConfigParams contains a list of configuration properties of the channel with which a channel is created. Config param is specific for a integration.
Example
This API lists all channels
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Integration Service ID to filter. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER
long
optionalDepartment Id for which channels to be fetched
string
optional,Additional information related to the channels.If passed in the param, then these values will be appended in the channel response. Allowed values are preference,creator,meta,configParams
boolean
optionalSet this to fetch sandbox channels only.
boolean
optionalSet this to fetch only the active channels
boolean
optionalSet this to fetch along with the deleted channels
string
optional,Set this to fetch channels with the given Config Param Name. Refer config param attribute of channel to get Config Name
string
optional,Set this to fetch channels with the given Config Param Value. Refer config param attribute of channel to get Config Value
string
optional,Set this to fetch channels with the not given Config Param Name. Refer config param attribute of channel to get Config Name
string
optional,Set this to fetch channels with the not given Config Param Value. Refer config param attribute of channel to get Config Value
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
This API fetches details of an channel.
Credit: 1 credit/call
string
optional,Additional information related to the channel. Allowed values are preference, creator
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
This API initiates a session with a template message
Credit: 1 credit/call
string
required,ID to which Message Has to be sent
string
required,Specifies receiverID type. Allowed value PHONENUMBER
long
requiredTemplateMessageId to send that template
string
required,Content of the message
string
optional,Content of the header message
string
optional,Content of the URL message
string
required,Language of Translation. Enter this input in ISO language code. For example en, fr, de, bn, ta etc
JSONArray
optionalMessage meta to be added to chat message
OAuth Scope
Desk.InstantMessages.CREATE
Request Example
Response Example
This API is designed to trigger Facebook Messenger messages to end users outside the standard messaging window, provided you have the Facebook comment ID and Facebook user ID from a post where the user interacted. In facebookMessengerPayload JSONObject, facebookUserId and facebookCommentId are mandatory params, if not passed in the payload, it will throw API error. Also, a single message can be sent with a given comment id. Attachment is also supported to be sent but make sure that if attachment is added, do not add message in facebookMessengerPayload JSON since it is restricted to send both attachment and message altogether in Facebook
Credit: 1 credit/call
null
Session payload for Facebook Messenger
Content-Type:multipart/form-data
File attachment to send
string
required,Integration Service of the channel. Only available integration service is FACEBOOKMESSENGER
JSONObject
optionalFacebook messenger payload for which the session needed to be created and message to be sent
JSONArray
optionalMessage meta to be added to chat message
OAuth Scope
Desk.InstantMessages.CREATE
Request Example
Response Example
An IM template Message predefined comman message to send while initiating a session
long
Template Message ID
string
Message title
string
Display Message
boolean
Specify whether the message is private to the creator
string
Content of the message
string
Message tags
timestamp
Last modified time
long
Department ID
string
Waba ID
string
Message Type. Allowed value is TEMPLATE
string
Message status
boolean
Is active ?
JSONObject
Actor
JSONArray
List of translations
Example
This API lists all sessions
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the canned messages must be fetched
int
optional,Number of canned messages to fetch
timestamp
optionalAfter which date entities to be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.
string
optional,Tag to filter by
boolean
optionalCanned Message Active Status
long
requiredDepartment ID for which the canned messages to be fetched
string
optional,Waba ID for which the canned messages to be fetched
long
optionalChannel ID for which the canned messages to be fetched
long
optionalContact ID for which the canned messages to be applied
string
optional,Filter with Status of Message Applicable only if messageType is Template. Allowed values are PENDING, FAILED, APPROVED, REJECTED
string
required,Filter by MessageType. Allowed values are TEMPLATE
string
optional,Language to filter canned message. Enter this input in ISO language code. For example en, fr, de, bn, ta etc
long
optionalSession ID for which the canned messages to be applied
long
optionalTicket id for which the canned message has to be applied
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
This API fetches details of a template message.
Credit: 1 credit/call
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
Get a canned message or a template message with applied contact information in the placeholders
Credit: 1 credit/call
long
optionalContact id for which the canned message has to be applied
long
optionalSession id for which the canned message has to be applied
string
optional,Language for which the canned message has to be applied. Enter this input in ISO language code. For example en, fr, de, bn, ta etc
long
optionalTicket id for which the canned message has to be applied
OAuth Scope
Desk.basic.CREATE , Desk.InstantMessages.CREATE
Request Example
Response Example
A session denotes the communication between an agent and an end-user, during which messages are exchanged. Several sessions can exist within a channel. Multiple messages can be included within a single session. Additionally, each end-user will have an exclusive session linked to a channel.
long
Sesion ID of the session
long
Channel ID for which the session is created
string
Status filter for the conversations. Allowed values are OPEN, ON_PROGRESS ,ON_HOLD ,BLOCKED
timestamp
Session creation time
long
Agent Id assicoated with the session
long
Bot ID associated with the session
JSONObject
Session actor
string
Subject of the session
int
Total message count in the session
timestamp
Last active time of agent
timestamp
End user last active time of agent
timestamp
Last active time of agent
int
Total unread message count in the session
string
Integration Service of the channel. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER
string
Session reply status. Allowed values are ACCEPTED, CHANNEL_INACTIVE, CHANNEL_REVOKED, SESSION_ENDED, SESSION_BLOCKED, SESSION_EXPIRED, UNASSIGNED, NOT_AN_ASSIGNEE, CREDIT_EXHAUSTED, ACCESSTOKEN_EXPIRED, PERMISSION_REVOKED, UNEXPECTED_ERROR, PAGE_REMOVED, SANDBOX_LIMIT_REACHED, CHANNEL_DELETED, ENDUSER_OFFLINE
long
End user desk contact Id
JSONObject
Session meta
JSONObject
Session assignee
string
Channel code
Example
This API lists all sessions
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the conversations must be fetched
int
optional,Number of conversations to fetch
long
optionalFilter conversations of a channel
long
optionalFilter conversations assigned to bots
long
optionalFilter conversations assigned to an agent
long
optionalFilter conversations of a contact
long
optionalFilter conversations of a profile
timestamp
optionalAfter which modified date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.
timestamp
optionalBefore which date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.
timestamp
optionalAfter which date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.
string
optional,Status filter for the conversations. Allowed values are OPEN, ON_PROGRESS ,ON_HOLD ,BLOCKED
string
optional,Assignment status filter for the conversations. Allowed values are MINE, UNASSIGNED ,NONE ,BOT
long
optionalFilter conversations of all channels in given department
boolean
optionalExclude session of channels which are in syncing status
OAuth Scope
Desk.InstantMessages.READ
Request Example
Response Example
This API fetches details of an session.
Credit: 1 credit/call
OAuth Scope
Desk.InstantMessages.READ
Request Example
Response Example
This API updates an IM session. Providing either agent Id or bot Id will assgin the session to that particular Id.
Credit: 1 credit/call
long
optionalCurrent assignee of this session
string
optional,Current status of the session to be set. Possible values are OPEN, ENDED, ON_PROGRESS, ON_HOLD, BLOCKED
long
optionalCurrent Desk bot assignee of this session.
OAuth Scope
Desk.InstantMessages.UPDATE
Request Example
Response Example
Metics APIs will provide various IM agent and conversation related metrics to the managers/leads.
This data provides leads/managers with a holistic details into agents performance and can be used in coaching them.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,Start date for metrics. Enter a date in the format of dd-mm-yyyy. This param will be taken into account only if duration equals to CUSTOM_IN_DATE
string
optional,End date for metrics. Enter a date in the format of dd-mm-yyyy. This param will be taken into account only if duration equals to CUSTOM_IN_DATE
string
required,Duration to filter the metrics. Available values are LAST24HOURS, TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, CUSTOM_IN_DATE, LAST_1_HOUR
string
required,Denotes which attribute group data is required. Eg: RESPONSIVENESS - AVG_RESPONSE_TIME comes under responsiveness group. It's Mandatory Param. Available value is RESPONSIVENESS
string
required,Denotes which metrics are required in the response. Its a mandatory Param. Eg: AVG_RESPONSE_TIME of agent.This is a list-based parameter you can pass all the values or the rquired ones. Available values are ATTENDED_CHATS, AVG_PICKUP_TIME, AVG_FIRST_RESPONSE_TIME, AVG_RESPONSE_TIME
string
optional,To filter Agent Metrics only on a list of channelIds. It's a Optional Param
string
optional,To filter Agent Metrics only for particular Agents. It's a Optional Param
long
optionalFilter agent metrics in given department Id
string
optional,Agent metrics for a particular integration service. Available values are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER, INSTAGRAM
string
optional,To get Agent Metrics based on the Conversation Started time or Ended Time. It's a Optional Param. Available values are START_TIME, END_TIME
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
This API lists various session related metrics such as avg. first response time, avg. response time and avg. pickup time.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
string
optional,start date for metrics. Enter a date in the format of dd-mm-yyyy. This param will be taken into account only if duration equals to CUSTOM_IN_DATE
string
optional,end date for metrics. Enter a date in the format of dd-mm-yyyy. This param will be taken into account only if duration equals to CUSTOM_IN_DATE
string
required,Duration to filter the metrics. Available values are LAST24HOURS, TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, CUSTOM_IN_DATE, LAST_1_HOUR
string
required,Provide metrics with time granularity. When timegap is within 24 hours, then HOURLY should be set in the param otherwise DAY should be set in this param. Available values HOURLY, DAY
string
required,Denotes the dimension in metrics - Eg: responsiveness - it gives how responsive the sessions in particular time duration- eg: avg pickup time. Available value is RESPONSIVENESS
string
required,Denotes dimensionValues required in dimension-Eg: Avg Pickup Time, Avg Response time etc. This is a list based parameter, you can pass all the values or the required one. Available values are AVG_PICKUP_TIME, AVG_RESPONSE_TIME, AVG_FIRST_RESPONSE_TIME
string
optional,Session metrics for a particular integration service. Available values are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER, INSTAGRAM
string
optional,Filter Session metrics by channelId
long
optionalFilter session metrics in given department Id
string
optional,Used to select the required metrics, based on Session Started time or Ended Time. Available values are START_TIME, END_TIME
OAuth Scope
Desk.basic.READ , Desk.InstantMessages.READ
Request Example
Response Example
Help center refers to the central self-service portal through which customers can look for solutions and fix issues by themselves.The help center brings together different help modules, such as your knowledge base, community forum, live chat, and ticket submission form
Example
This API lists the help centers configured in your Zoho Desk portal.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
Integer
optional,Index number starting from which the helpcenters must be listed
Integer
optional,Number of helpcenters to list
String
optionalInclude params are autoTranslateSettings
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API fetches the details of a particular help center.
Credit: 1 credit/call
OAuth Scope
Desk.settings.READ , Desk.basic.READ
Request Example
Response Example
This API will generate sitemaps for the given Helpcenter
Credit: 1 credit/call
OAuth Scope
Desk.settings.UPDATE
Request Example
Response Example
Users refer to the end-customers of the product/service who visit the Help Center to find solutions.
long
ID of the user
list
Email address of the user
string
Activation status of the user. The supported values are ACTIVE and DISABLED
Example
This API lists a particular number of help center users, based on the limit defined. It also helps you search for specific users.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the users must be fetched. The default value is 1
int
optional,Number of users to be listed. The default and the maximum allowed value is 50
String
optionalSearch keyword to find a particular user. Note: The keyword must contain at least two characters
String
optional Key that sorts the list of users by a particular attribute: -(email or modifiedTime)
String
optionalActivation status of the users to list
long
optionalID of the help center from which the users must be fetched
string
optional,Additional information related to the user. Value allowed is count.
OAuth Scope
Desk.search.READ
, Desk.contacts.READ
,
Desk.settings.READ
,
Desk.basic.READ
Request Example
Response Example
This API fetches the details of a particular help center user.
Credit: 1 credit/call
string
optional,Additional information related to the user. Value allowed is contact.
long
optionalID of the help center from which the user must be fetched
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
,
Desk.basic.READ
Request Example
Response Example
This API helps update the details of a particular help center user.
Credit: 1 credit/call
long
optionalID of the help center from which the user must be updated
list
optionalEmail ID of the user
string
optional,Activation status of the user. Values supported are ACTIVE and DISABLED.
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API permanently deletes all identifying information about a user from your help center.
Credit: 1 credit/call
string
optional,Display name of the user in tickets and community topics after anonymization
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists a particular number of user groups in a help center, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the groups must be fetched. The default value is 1
int
optional,Number of groups to list. The default value and the maximum value allowed is 50
String
optionalSearch keyword to use for finding a particular user. The keyword must contain at least two characters.
String
optionalKey that sorts the list of user groups by a particular attribute: -(addedTime)
long
optionalID of the help center from which the groups must be fetched
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API adds a user to the groups specified.
Credit: 1 credit/call
long
optionalID of the help center from which the groups must be validated
list
requiredIDs of the groups to which the user must be added
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API removes a user from the groups specified.
Credit: 1 credit/call
long
optionalID of the help center from which the groups must be removed
list
requiredIDs of the groups from which the user must be removed
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists a particular number of labels associated with a user, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
boolean
optionalKey that filters the primary label assigned to the user
int
optional,Index number, starting from which the labels must be fetched. The default value is 1
int
optional,Number of labels to list. The default value and the maximum value allowed is 50
String
optionalKey that sorts the list of labels by a particular attribute: -(assignedTime)
String
optionalSearch keyword to use for finding a particular user. The keyword must contain at least two characters.
long
optionalID of the help center from which the labels must be fetched
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API assigns the labels you specify to a particular user.
Credit: 1 credit/call
long
optionalID of the help center from which the labels must be validated
list
requiredList containing the details of the labels to assign
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API removes the labels you specify from a particular user.
Credit: 1 credit/call
long
optionalID of the help center from which the labels must be removed
list
requiredList containing the IDs of the labels to remove
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists user's default and custom badges, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the badges must be fetched. The default value is 1
int
optional,Number of badges to list. The default value and the maximum value allowed is 50
string
optional,Type of badge: default or custom
string
optional,Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.
date
optionalStart time should be in GMT time zone
date
optionalEnd time should be in GMT time zone
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API adds specified badges to user.
Credit: 1 credit/call
list
requiredIDs of the badges to which the user must be associated
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API removes specified badges from the users.
Credit: 1 credit/call
list
requiredIDs of the badges from which the user must be dissociated
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
Labels are tags that you add to users to highlight their contribution in your help center.
Example
This API creates a label in your help center.
Credit: 1 credit/call
String
requiredName of the label
long
optionalID of the logo set for the label
long
requiredID of the help center in which the label must be created
JSONObject
optionalVisual preferences related to the label/logo
OAuth Scope
Desk.contacts.CREATE
,
Desk.settings.CREATE
Request Example
Response Example
This API helps update the details of a label.
Credit: 1 credit/call
String
optionalName of the label
long
optionalID of the logo set for the label
JSONObject
optionalVisual preferences related to the label/logo
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API fetches the details of a particular label.
Credit: 1 credit/call
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API lists a particular number of labels, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the labels must be fetched. The default value is 1.
int
optional,Number of labels to list. The default value and the maximum value allowed is 50.
String
optionalKey that sorts the list of labels by a particular attribute: -(createdTime or modifiedTime, or name)
String
optionalSearch keyword to use for finding a particular label. The keyword must contain at least two characters. Three types of search are supported: keyword* (search for values that start with the keyword, *keyword* (search for values that contain the keyword), and keyword (search for values that are exact matches of the keyword)
long
optionalID of the help center from which the labels must be fetched
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API deletes a label from your help center.
Credit: 1 credit/call
OAuth Scope
Desk.contacts.DELETE
,
Desk.settings.DELETE
Request Example
Response Example
This API deletes labels, based on the IDs specified.
Credit: 6 credits/record
long
optionalIDs of the labels to delete
OAuth Scope
Desk.contacts.DELETE
,
Desk.settings.DELETE
Request Example
Response Example
This API assigns a particular label to multiple users.
Credit: 1 credit/call
list
requiredIDs of the users to whom the label must be assigned
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API removes all users under a particular label.
Credit: 1 credit/call
list
requiredIDs of the users from whom the label must be removed
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists a particular number of users under a label, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the users must be fetched. The default value is 1.
int
optional,Number of users to list. The default value is 50 and the maximum value allowed is 100
String
optionalKey that sorts the list of users by a specific attribute: -(assignedTime)
String
optionalSearch keyword to use for finding a particular user. The keyword must contain at least two characters.
OAuth Scope
Desk.search.READ
, Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
Groups are collections of end-users—often related to a specific account, geography, brand, or product—using which you can determine access to your knowledge base and community forums.
Example
This API creates a user group in your help center.
Credit: 1 credit/call
string
required,Name of the group
string
optional,A brief description of the group
long
optionalID of the logo to associate with the group
long
requiredID of the help center in which the group must be created
OAuth Scope
Desk.contacts.CREATE
,
Desk.settings.CREATE
Request Example
Response Example
This API helps update the details of a user group.
Credit: 1 credit/call
string
optional,Name of the group
string
optional,A brief description of the group
long
optionalID of the logo to associate with the group
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API fetches the details of a particular user group.
Credit: 1 credit/call
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API lists a particular number of groups, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the groups must be fetched. The default value is 1.
int
optional,Number of groups to list. The default value and the maximum value allowed is 50.
String
optionalKey that sorts the list of groups by a particular attribute: -(createdTime, modifiedTime, name, or count)
String
optionalSearch keyword to use for finding a particular group The keyword must contain at least two characters. Three types of search are supported: keyword* (search for values that start with the keyword, *keyword* (search for values that contain the keyword), and keyword (search for values that are exact matches of the keyword).
long
optionalID of the help center from which the resource must be fetched
OAuth Scope
Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
This API deletes a user group from your help center.
Credit: 1 credit/call
OAuth Scope
Desk.contacts.DELETE
,
Desk.settings.DELETE
Request Example
Response Example
This API adds users to a particular group.
Credit: 1 credit/call
list
requiredIDs of the users who must be added to the group
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API removes particular users from a group.
Credit: 1 credit/call
list
requiredIDs of the users who must be removed from the group
OAuth Scope
Desk.contacts.UPDATE
,
Desk.settings.UPDATE
Request Example
Response Example
This API lists a particular number of users in a group, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
optional,Index number, starting from which the users must be fetched. The default value is 1.
int
optional,Number of users to list. The default value is 50 and the maximum value allowed is 100.
String
optionalKey that sorts the list of users, based on a specific attribute: -(addedTime)
String
optionalSearch keyword to use for finding a particular user. The keyword must contain at least two characters.
OAuth Scope
Desk.search.READ
, Desk.contacts.READ
,
Desk.settings.READ
Request Example
Response Example
Community is an online forum that provides customers a self-service platform to connect with fellow customers, discuss topics, share ideas, ask questions about products, share suggestions and feedback, receive important notifications, and stay informed about the company's whereabouts.
Example
This API enables users to like a topic.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API enables users to unlike a topic.
Credit: 1 credit/call
OAuth Scope
Desk.forums.UPDATE , Desk.community.UPDATE
Request Example
Response Example
This API enables users to follow a topic.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API enables users to unfollow a topic.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps lock a forum topic, so that further user actions are restricted.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps unlock a forum topic, so that further user actions can be performed.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API allows to set the forum topics as moderate. The comments that are posted during moderation will not be displayed to users and await for the review.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps unmoderate a forum topic, which means user comments are published without reviewing.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API moves a forum topic to trash of your help desk portal.
Credit: 1 credit/call
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API moves a forum topic from one community category to another.
Credit: 1 credit/call
long
requiredID of the community category
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API associates quick access/reference tags to a forum topic.
Credit: 1 credit/call
list
requiredTag phrases
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API removes quick access/reference tags from a forum topic.
Credit: 1 credit/call
list
requiredTag phrases
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API lists a particular number of users who follow a forum topic, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
required,Index number, starting from which the users must be listed.
int
required,Number of users to list
string
optional,Filters based on the type of the user who follows it. The allowed values are AGENT or END_USER.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API lists a particular number of users who participated in a forum topic, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
required,Index number, starting from which the users must be listed
int
required,Number of users to list
string
optional,Filters based on the type of the user who participated in it. The allowed values are AGENT or END_USER.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API lists a particular number of users who voted in a forum topic, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
required,Index number, starting from which the users must be listed
int
required,Number of users to list
string
optional,Filters based on the type of the user who voted for it. The allowed values are AGENT or END_USER.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API lists a particular number of forum topics, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
long
optionalID of the community category from which the topics must be listed
int
required,Index number, starting from which the topics must be listed
int
required,Number of topics to list
boolean
optionalKey that defines whether the topics to list must be sticky posts or not
boolean
optionalKey that defines whether the topics to list must contain comments or not
String
optionalType of topics to list. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.
String
optionalTag by which topics must be filtered
String
optionalStatus label by which topics must be filtered. The value of this key varies according to the topic type. Values allowed are: NOSTATUS, NEEDMOREINFO, WORKINGONIT, ANSWERED, UNANSWERED, MAYBELATER, UNDERREVIEW, IMPLEMENTED, WILLNOTIMPLEMENT, NOTAPROBLEM, TEMPORARYFIX, ANALYZING, SOLVED, UNSOLVED, and MOSTVOTED.
String
required,sort topics list by createdtime or modified time
boolean
required,sort topics list in ascending or decending order
date
optionalStarting time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.
date
optionalEnding time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API fetches a forum topic from the user community.
Credit: 1 credit/call
string
optional,Additional information related to the topics. Values allowed are: seo, featuredImage and participantsCount.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API fetches a forum topic, based on the permalink in the API request.
Credit: 1 credit/call
String
requiredpermalink of the topic
string
optional,Additional information related to the topics. Values allowed are: seo, featuredImage and participantsCount.
OAuth Scope
Desk.community.READ
Request Example
Response Example
This API helps add a forum topic in the user community.
Credit: 1 credit/call
String
requiredTitle of the topic
String
optionalpermalink of the topic to be created
String
requiredBody content of the topic
String
requiredType of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.
long
requiredID of the community category in which the topic must be posted
boolean
optionalKey that defines whether the topic must be pinned to the topics list page or not
boolean
optionalKey that defines whether the creator of the topic must be notified about further user actions on the topic or not
JSONArray
optionalIDs of files to attach to the topic
JSONArray
optionalTag phrases
JSONArray
optionalEmail IDs to which the topic must be sent after publishing
JSONObject
optionalThe list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title
JSONObject
optionalSpecifies the id of the uploaded image to display as a featured image.
OAuth Scope
Desk.community.CREATE
Request Example
Response Example
This API helps update a published forum topic.
Credit: 1 credit/call
String
optionalTitle of the topic
String
optionalBody content of the topic
boolean
optionalKey that defines whether the topic must be pinned to the topics list page or not
String
optionalType of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.
JSONArray
optionalIDs of files to attach to the topic
String
optionalStatus label of the topic. The value of this key varies according to the topic type. Values allowed are: NOSTATUS, NEEDMOREINFO, WORKINGONIT, ANSWERED, UNANSWERED, MAYBELATER, UNDERREVIEW, IMPLEMENTED, WILLNOTIMPLEMENT, NOTAPROBLEM, TEMPORARYFIX, ANALYZING, SOLVED, UNSOLVED, and MOSTVOTED.
boolean
optional,whether to notify mentioned user while updateing content.
long
optionalID of the community category in which the topic must be posted
JSONArray
optionalTag phrases
boolean
optionalKey that defines whether the creator of the topic must be notified about further user actions on the topic or not
JSONObject
optionalThe list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title
JSONObject
optionalSpecifies the id of the uploaded image to display as a featured image.
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps add a comment to a forum topic.
Credit: 1 credit/call
string
required,Content of the comment
JSONArray
optionalIDs of files to attach to the comment
OAuth Scope
Desk.community.CREATE
Request Example
Response Example
This API helps add a reply to a comment on a forum topic.
Credit: 1 credit/call
string
required,Content of the reply
JSONArray
optionalIDs of files to attach to the reply
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps update a published comment.
Credit: 1 credit/call
string
optional,Content of the comment/reply
JSONArray
optionalIds of the attachments added for this topic
boolean
optionalKey that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.
boolean
optional,whether to notify mentioned user while updateing content.
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API helps update a published reply.
Credit: 1 credit/call
string
optional,Content of the comment/reply
JSONArray
optionalIds of the attachments added for this topic
boolean
optionalKey that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.
boolean
optional,whether to notify mentioned user while updateing content.
OAuth Scope
Desk.community.UPDATE
Request Example
Response Example
This API lists a particular number of comments on a topic, based on the limit defined.
Credit: 3 credits/call
Note: Credits depends on the range where the records are fetched. Refer for details
int
required,Index number, starting from which the comments must be listed
int
required,The end limit to list the comments
boolean
optional,Key that defines the listing order of the comments. Setting TRUE lists the latest comments first (descending order) and setting FALSE lists the oldest comments first (ascending order).
date
optionalStarting time interval to list the comments that are created within the specified timezone. The value must be provided in GMT format. Example: " 2018-10-06T09:29:15.219Z "
date
optionalEnding time interval to list the comments that are created within the specified timezone. The value must be provided in GMT format. Example: " 2018-10-16T10:29:15.219Z "
OAuth Scope
Desk.community.READ
Request Example
Response Example