API Documentation
CURL
select client library
CURL
Java

Introduction

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

Getting Started

All Zoho Desk APIs require these two mandatory fields in the header.

  1. Authorization - Authentication request token
  2. orgId -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"

HTTP Methods

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"

Errors

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.

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.

UNAUTHORIZED

This errorCode value appears if the authentication token in the API request is invalid

INVALID_OAUTH

This errorCode value appears if the OAuthToken is invalid or expired.

SCOPE_MISMATCH

This errorCode value appears if the OAuthToken does not contain the scope required to perform the operation.

OAUTH_ORG_MISMATCH

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.

FORBIDDEN

This errorCode value appears if the user does not have all the permissions required to access the resource.

LICENSE_ACCESS_LIMITED

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

  • AGENTS
  • LIGHT_AGENTS
  • TEAM

The possible values for the editionType key are

  • FREE
  • EXPRESS
  • STANDARD
  • PROFESSIONAL
  • ENTERPRISE

URL_NOT_FOUND

This errorCode value appears if the URL provided is invalid or does not exist.

METHOD_NOT_ALLOWED

This errorCode value appears if the method in the API request is known by the server but disabled for the API requested.

RESOURCE_SIZE_EXCEEDED

This errorCode value appears if the size of the resource exceeds the limit defined by the server.

UNSUPPORTED_MEDIA_TYPE

This errorCode value appears if the server refuses the request as a result of receiving the input in an unsupported format.

INVALID_DATA

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:

  • invalid - the field contains an invalid value
  • duplicate - the field contains a value that already exists
  • missing - the field does not contain a value

The field that contains the inaccurate value is returned in the fieldName param, which is represented in the JSON Pointer convention

UNPROCESSABLE_ENTITY

This errorCode value appears if the input does not fulfil the conditions necessary for successfully executing the API.

ONLY_LIVECHAT_USER

This errorCode value appears if the API request tries to remove the last user remaining in a department that has live chat enabled

DUPLICATE_CONTRACT

This errorCode value appears if the user creates a contract for an SLA with existing or overlapping time periods.

  • The key existingContracts is an array containing one or more contract entities.

INTEGRATION_ADMIN_ERROR

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 :

  • LIVECHAT

THRESHOLD_EXCEEDED

This errorCode value appears if the user sends too many requests within a given amount of time ("rate limiting").

TOO_MANY_REQUESTS

This errorCode value appears if the user fires too many requests in a simultaneous/concurrent manner ("rate limiting").

INTERNAL_SERVER_ERROR

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


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


Include

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.

Conventions

  1. Always ignore undocumented fields or enum values present in the api response.These fields could be either experimental or deprecated.
  2. Data fields in tickets, contacts, accounts, tasks etc are dynamic. This is due to security field filtering applied for user profile. Hence when coding with data from these api always consider them as dynamic.

Compatibility

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.

Zoho Desk API - OpenAPI Specification 3.1.0

Overview

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.

Why OpenAPI Specification 3.1.0?

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:

  • API Endpoints: Clearly defines request URLs, supported HTTP methods, and optional/required parameters required to make an API call. It also specifies response formats for all possible HTTP status codes.
  • Authorization: Supports OAuth 2.0 for secure API authentication.
  • Request and Response Formats: Standardizes formats for GET, POST, PUT, PATCH, and DELETE operations. It also includes detailed response schemas and error handling guidelines, enabling easier debugging.

GitHub Repository Details

The OpenAPI Specification (OAS) for Zoho Desk APIs is hosted on GitHub:

  • The OAS document is available in JSON format.
  • Refer to the Git Repository for all OAS files

Note:

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.

API Credits

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.

Examples:

  • Fetch a single record: 1 credit per call
  • Update many records: 25 credits per call (based on the operation complexity)

Credit Allocation by Edition

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.

  • The base credit is 75,000.
  • Each user gets 500 credits, so 50 x 500 = 25,000
  • Total: 75,000 + 25,000 = 100,000 credits.

Here is a calculator to find the available credit limits based on your edition and the number of users.

Calculate credits limits

200,000 Credits
With the purchase of 100 users for Enterprise/ZohoOne edition

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.

Concurrency Limits

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."
}

Credit Consumption Model

Desk uses two types of credit consumption models depending on the nature of the API


Fixed credit consumption

The number of credits consumed remains fixed, regardless of how much data is processed.

Example:

API: Fetch a single record

Credit: 1 credit/ call


Variable credit consumption

This credit consumption depends on how many records you are working with or how intensive the operation is.

1. Credits for bulk write operations

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


Credit consumption for each operation:
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.

2. Credits for fetching multiple records

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.

Credit Breakdown by record range:

  • Records from 0 to 2,000 : 3 credits
  • Records from 2001 to 10000 : 10 credits
  • Records from 10,001 to 100,000 : 50 credits
  • Records above 100,001 : 100 credit

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.

Increase API Credits

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

  • You are the super admin of the account.
  • Your account is on a paid plan.

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:

  • First 25,000 credits ->25 x $4.20 = $105.00
  • Next 75,000 credits ->75 x $1.80 = $135.00
  • Next 150,000 credits ->150 x $1.50 = $225.00
  • Remaining 50,000 credits ->50 x $0.75 = $37.50

Total Monthly Cost: $502.50


Use the calculator below to check the monthly payable amount for the add-on credits.

Calculate Add-on limits


240 USD
The total amount payable for 100,000 Add-on credits

Disclaimer: All calculated rates are approximate and subject to changes in the exchange rate.

Ratelimit Response Headers

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"

Setting Credit Alert Notifications

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.

Authentication(OAuth)

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.


Why should we use OAuth2.0?

  • 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.

How OAuth2.0 works?

Terminologies

The following are some terms you need to know before you start using the Zoho Desk APIs.

Protected resources:

The Zoho Desk resources, such as Tickets, Contacts, Tasks, etc.

Resource server:

The Zoho Desk server that hosts protected resources.

Resource owner:

Any end-user of your account, who can grant access to the protected resources.

Client:

An application that sends requests to the resource server to access the protected resources on behalf of the end-user.

Client ID:

The consumer key generated from the connected application.

Client Secret:

The consumer secret generated from the connected application.

Authentication server:

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.

Authentication code:

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..

Tokens

Access Token:

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.

Refresh Token:

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

Step 1: Register your Application

First, register your app in Zoho's Developer Console, which you can access here.

Choose a client type

  • 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.

Choose Web based client and Enter the following details:

  • 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.


Step2: Making the Authorization Request

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 application

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.


When the user clicks Accept:

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.

  • code={grant_token} - This is used to generate access and refresh tokens.
  • location={domain} - This tells you the domain of the user from which you have to make API calls.
  • accounts-server={accounts_URL} - This is your accounts URL which you have to use to generate access and refresh tokens.

The application exchanges the authorization code for an access token.


When the user clicks Reject:

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.


Generating OAuth Tokens Using Self Client

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.

  1. Go to Zoho Developer Console.

  2. Choose Self Client from the list of client types, and click Create Now.

  3. Click OK in the pop up to enable a self client for your account.

  4. Now, your client ID and client secret are displayed under the Client Secret tab.

  5. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details.

  6. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.

  7. Enter a description and click Generate.

  8. 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


Step 3: Generating Tokens

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

Step 4: Refreshing your Access Tokens

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

Step 5: Revoking Tokens

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

Using OAuth Token In API Calls

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

OAuth Scopes

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

Organization Binding

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.


Webhook

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.

Help Center

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

Java SDK

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

Organizations

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}

ATTRIBUTES

Attribute Name
Data Type
Description
companyName

string

Actual name of the organization/business

portalName

string

Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.

phoneNumber

string

Phone number of the organization

edition

string

Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, PROFESSIONAL, STANDARD and EXPRESS.

id

long

Unique ID of the organization

isDefault

boolean

Key that returns if the organization is the default organization of the user

isAdminInOrg

boolean

Key that returns if the user is an admin in the organization

portalURL

string

URL of the help desk portal

logoURL

string

URL of the image file displaying the organization's logo

alias

string

Alternative name for the help desk portal

employeeCount

string

Number of employees in the organization

description

string

Brief description of the organization

mobile

string

Mobile number of the organization

website

string

Website of the organization

fax

string

Fax number of the organization

primaryContact

string

Primary contact person in the organization

street

string

Street in which the organization's office is located

city

string

City in which the organization's office is located

state

string

State in which the organization's office is located

zip

string

Zip code of the organization's address

country

string

Country in which the organization's office is located

currencyLocale

string

Currency locale in which the organization operates

currencySymbol

string

Currency symbol used in the organization

Example

{
  "country" : "United States",
  "city" : "Bernierview",
  "companyName" : "Zylker INC.",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "isAdminInOrg" : true,
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "portalName" : "zylker",
  "street" : "70961 Powlowski Crossing",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "isPayloadEncryptionEnabled" : "false",
  "fax" : "8392839821",
  "zip" : "68838-2640",
  "website" : "www.zylker.com",
  "mobile" : "9848022338",
  "currencySymbol" : "$",
  "logoURL" : "http://static.zohocdn.com/desk/app/images/portalLogo.de847024ebc0131731a3.png",
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
  "primaryContact" : "steve@zylker.com",
  "currencyCode" : "USD",
  "isSandboxPortal" : "false"
}


Get organization

This API fetches the details of an organization from your help desk.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
includeCustomDomain

boolean

optional,
default : false

Key that denotes if the customDomain field must be included in the API response

GET /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311?includeCustomDomain=true
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "country" : "United States",
  "city" : "Bernierview",
  "companyName" : "Zylker INC.",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "isAdminInOrg" : true,
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "portalName" : "zylker",
  "street" : "70961 Powlowski Crossing",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "isPayloadEncryptionEnabled" : "false",
  "fax" : "8392839821",
  "zip" : "68838-2640",
  "website" : "www.zylker.com",
  "mobile" : "9848022338",
  "currencySymbol" : "$",
  "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
  "customDomain" : "support.zylker.com",
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
  "primaryContact" : "steve@zylker.com",
  "currencyCode" : "USD",
  "isSandboxPortal" : "false"
}

Get all organizations

This API lists all organizations to which the current user belongs.

GET /api/v1/organizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizations
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "country" : "United States",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "employeeCount" : "10",
    "isAdminInOrg" : true,
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
    "portalName" : "zylker",
    "street" : "70961 Powlowski Crossing",
    "currencyLocale" : "US",
    "alias" : "Zylker Teams",
    "id" : "3981311",
    "state" : "NC",
    "isPayloadEncryptionEnabled" : "false",
    "fax" : "8392839821",
    "zip" : "68838-2640",
    "website" : "www.zylker.com",
    "mobile" : "9848022338",
    "currencySymbol" : "$",
    "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
    "isDefault" : "false",
    "phoneNumber" : "9884358081",
    "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
    "primaryContact" : "steve@zylker.com",
    "currencyCode" : "USD",
    "isSandboxPortal" : "false"
  }, {
    "country" : "United States",
    "city" : "Port Cierra",
    "companyName" : "Nshlerin LLC.",
    "description" : "We are Nshlerin Support.",
    "edition" : "PROFESSIONAL",
    "employeeCount" : "20",
    "isAdminInOrg" : true,
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/5988319/favicon?no-cache=b31a9627de49fge046fcab71sf3359eq",
    "portalName" : "nshlerin",
    "street" : "269 Adam Flats",
    "currencyLocale" : "US",
    "alias" : "Nshlerinians",
    "id" : "5988319",
    "state" : "Port Cierra",
    "isPayloadEncryptionEnabled" : "false",
    "fax" : "987654321",
    "zip" : "33560-8932",
    "website" : "www.nshlerin.com",
    "mobile" : "987654321",
    "currencySymbol" : "$",
    "logoURL" : "http://static.zohocdn.com/desk/app/images/portalLogo.de847024ebc0131731a3.png",
    "isDefault" : "false",
    "phoneNumber" : "9884309090",
    "portalURL" : "http://support.nshlerin.com/support/nshlerin/ShowHomePage.do",
    "primaryContact" : "kelvin@zylker.com",
    "currencyCode" : "USD",
    "isSandboxPortal" : "true"
  } ]
}

Get accessible organizations

This API lists all organizations which can be accessed using the current Oauth token.

GET /api/v1/accessibleOrganizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accessibleOrganizations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "country" : "United States",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "employeeCount" : "10",
    "isAdminInOrg" : true,
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
    "portalName" : "zylker",
    "street" : "70961 Powlowski Crossing",
    "currencyLocale" : "US",
    "alias" : "Zylker Teams",
    "id" : "3981311",
    "state" : "NC",
    "isPayloadEncryptionEnabled" : "false",
    "fax" : "8392839821",
    "zip" : "68838-2640",
    "website" : "www.zylker.com",
    "mobile" : "9848022338",
    "currencySymbol" : "$",
    "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
    "isDefault" : "false",
    "phoneNumber" : "9884358081",
    "portalURL" : "https://support.zylker.com/support/zylker/ShowHomePage.do",
    "primaryContact" : "steve@zylker.com",
    "currencyCode" : "USD",
    "isSandboxPortal" : "false"
  } ]
}

Update organization

This API updates the details of an organization.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
companyName

string

optional,
max chars : 50

Actual name of the organization/business

portalName

string

optional,
max chars : 100

Unique name for the help desk portal. Only lower-case letters and numbers are allowed in the name.

phoneNumber

string

optional,
max chars : 30

Phone number of the organization

edition

string

optional,
max chars : 100

Zoho Desk edition purchased. Values allowed are: FREE, ENTERPRISE, PROFESSIONAL, STANDARD and EXPRESS.

alias

string

optional,
max chars : 50

Alternative name for the help desk portal

employeeCount

string

optional,
max chars : 19

Number of employees in the organization

description

string

optional,
max chars : 250

Brief description of the organization

mobile

string

optional,
max chars : 30

Mobile number of the organization

website

string

optional,
max chars : 50

Website of the organization

fax

string

optional,
max chars : 100

Fax number of the organization

primaryContact

string

optional,
max chars : 100

Primary contact person in the organization

street

string

optional,
max chars : 50

Street in which the organization's office is located

city

string

optional,
max chars : 50

City in which the organization's office is located

state

string

optional,
max chars : 50

State in which the organization's office is located

zip

string

optional,
max chars : 100

Zip code of the organization's address

country

string

optional,
max chars : 50

Country in which the organization's office is located

currencyLocale

string

optional,
max chars : 100

Currency locale in which the organization operates

PATCH /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/organizations/3981311
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "portalName" : "zylkerdesk",
  "companyName" : "Zylker Desk",
  "primaryContact" : "kelvin@zylker.com",
  "mobile" : "9848022338",
  "employeeCount" : "10"
}'

Response Example

{
  "country" : "United States",
  "city" : "Bernierview",
  "companyName" : "Zylker Desk",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "isAdminInOrg" : true,
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "portalName" : "zylkerdesk",
  "street" : "70961 Powlowski Crossing",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "isPayloadEncryptionEnabled" : "false",
  "fax" : "8392839821",
  "zip" : "68838-2640",
  "website" : "www.zylker.com",
  "mobile" : "9848022338",
  "currencySymbol" : "$",
  "logoURL" : "http://static.zohocdn.com/desk/app/images/portalLogo.de847024ebc0131731a3.png",
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalURL" : "http://support.zylker.com/support/zylkerdesk/ShowHomePage.do",
  "primaryContact" : "kelvin@zylker.com",
  "currencyCode" : "USD",
  "isSandboxPortal" : "false"
}

Get organization favicon

This API fetches the favicon set for an organization/portal in your help desk.

Query Params

Param Name
Data Type
Description
no-cache

string

optional,
max chars : 100

Key that helps avoid browser cache. Only alphanumeric values are allowed.

fileSize

string

optional,
max chars : 100

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.

GET /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311/favicon
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Update organization favicon

This API updates the favicon set for an organization/portal in your help desk.

Credit: 1 credit/call

File Params

favicon

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

POST /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/organizations/3981311/favicon
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "faviIconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=ffc59c3ba6585c12fb306f5174948ff6"
}

Delete organization favicon

This API updates the favicon set for an organization/portal in your help desk.

Credit: 1 credit/call

DELETE /api/v1/organizations/{organization_Id}/favicon

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/organizations/3981311/favicon
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Update default organization

This API updates the default organization for the current user in Zoho Desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
id

long

required

Unique ID of the organization to be marked as default org

POST /api/v1/organizations/markDefault

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/organizations/markDefault
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "id" : "3981311"
}'

Response Example

204

Agents

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.

ATTRIBUTES

Attribute Name
Data Type
Description
emailId

string

Email ID of the agent

status

string

Activation status of the agent: ACTIVE or DISABLED

lastName

string

Last name of the agent

firstName

string

First name of the agent

name

string

Full name of the agent

phone

string

Phone number of the agent

mobile

string

Mobile number of the agent

extn

string

Extension number of the agent

associatedDepartmentIds

list

Departments with which the agent is associated

associatedChatDepartmentIds

list

Chat departments with which the agent is associated

id

long

ID of the agent

zuid

long

Zoho user ID of the agent

roleId

long

Role ID of the agent

profileId

long

Profile ID of the agent

photoURL

string

URL of the image file displaying the agent's photo

isConfirmed

boolean

Key that returns if the agent is a confirmed user in the portal or not

rolePermissionType

string

The Role Permission type of Agent

aboutInfo

string

Agent's about info

channelExpert

list

The channels handled for the Agent

countryCode

string

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

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.

langCode

string

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

Example

{
  "lastName" : "case",
  "extn" : "3298",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "case@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
  "firstName" : "",
  "photoURL" : null,
  "phone" : "492-736-6424",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "case",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "Expert in handling tickets and Automations",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}


Get agent

This API fetches details of an agent in your help desk.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/agents/1892000000056096?include=profile,role,associatedDepartments,associatedChatDepartments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> Agent response = agent.getAgent( agentId, include );

Response Example

{
  "associatedChatDepartments" : [ {
    "name" : "Developement",
    "id" : "1892000000006907"
  } ],
  "lastName" : "case",
  "extn" : "3298",
  "role" : {
    "name" : "CEO",
    "id" : "1892000000056099"
  },
  "langCode" : "fr_FR",
  "emailId" : "case@zylker.com",
  "photoURL" : null,
  "countryCode" : "en_US",
  "isConfirmed" : true,
  "id" : "1892000000056096",
  "roleId" : "1892000000056099",
  "profile" : {
    "name" : "Administrator",
    "id" : "1892000000056091"
  },
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "associatedChatDepartmentIds" : [ "1892000000006907" ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "associatedDepartments" : [ {
    "name" : "Developement",
    "id" : "1892000000006907"
  }, {
    "name" : "R & D",
    "id" : "1892000000082069"
  } ],
  "firstName" : "",
  "phone" : "492-736-6424",
  "profileId" : "1892000000056091",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "case",
  "rolePermissionType" : "Admin",
  "aboutInfo" : "Expert in handling tickets and Automations",
  "status" : "ACTIVE"
}

List agents

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the agents must be fetched

limit

integer

optional,
range : 0-200

Number of agents to fetch. The default value is 10 and the maximum value supported is 200.

status

string

optional,
max chars : 100

Key that filters agents based on their activation status: ACTIVE, DISABLED, DELETED or IMPORTED

departmentIds
see documentation

long

optional

Comma-separated array of department IDs. Maximum number of IDs allowed is 50.

profileIds
see documentation

long

optional

Comma-separated array of profile IDs. Maximum number of IDs allowed is 50.

roleIds
see documentation

long

optional

Comma-separated array of role IDs. Maximum number of IDs allowed is 50.

rolePermissionType

string

optional,
max chars : 100

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.

isConfirmed

boolean

optional

Key that denotes if the agents must be confirmed or unconfirmed.

isLightAgent

boolean

optional

Key that denotes if the agents must be light or non light.

include
see documentation

string

optional,
max chars : 100

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.

searchStr

string

optional,
max chars : 100

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

fieldName

string

optional,
max chars : 100

Name of the field that must be used for searching and listing agents. The allowed values are: firstName, lastName, name, and emailId

cfSearchStr

string

optional,
max chars : 100

String to search for agents by custom field. The string must contain at least one character

cfFieldName

string

optional,
max chars : 100

API name of the custom field that must be used for searching and listing agents

sortOrder

string

optional,
max chars : 100

To sort the available list of agents in either ascending or descending order. The allowed values are: asc or desc

GET /api/v1/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> GetAgentsFilter filter = new GetAgentsFilter.Builder().setFieldName(fieldName).build(); <br/> List&lt;Agent&gt; response = agent.getAgents( from, limit, include, filter );

Response Example

{
  "data" : [ {
    "lastName" : "case",
    "extn" : "3298",
    "isZiaAgent" : false,
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "case@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "zyl",
    "photoURL" : null,
    "phone" : "492-736-6424",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "zyl case",
    "rolePermissionType" : "Admin",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "jade",
    "extn" : "3203",
    "isZiaAgent" : false,
    "roleId" : "1892000000056899",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "jade@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10657727",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ],
    "firstName" : "",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3981311",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web" ],
    "name" : "jade",
    "rolePermissionType" : "Light",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tasks",
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "john",
    "extn" : "3228",
    "isZiaAgent" : false,
    "roleId" : "1892000000056004",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "john@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10713988",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "68779989",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Chat", "Phone", "Twitter", "Web", "Email" ],
    "name" : "john",
    "rolePermissionType" : "AgentPersonal",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling Workflows and Agents",
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "Waugh",
    "extn" : "4020",
    "isZiaAgent" : false,
    "roleId" : "1892000000056004",
    "langCode" : "ja_JP",
    "mobile" : "",
    "timeZone" : "Asia/Tokyo",
    "emailId" : "stephen@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : null,
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "Steve",
    "photoURL" : null,
    "phone" : "",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ ],
    "name" : "Steve Waugh",
    "rolePermissionType" : "Custom",
    "isConfirmed" : false,
    "aboutInfo" : "Expert in handling Knowledge base and comunity ",
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get agents count

This API lists the agents count by status, confirmed and include light

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
status

string

optional,
max chars : 100

Parameter that filters agents based on their activation status: ACTIVE or DISABLED

isConfirmed

boolean

optional

Filters Confirmed & Unconfirmed agents

includeLightAgent

boolean

optional

Count light agent.

GET /api/v1/agents/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/count
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get agent details by agentId

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

Query Params

Param Name
Data Type
Description
agentIds

long

required

Comma-separated array of agent IDs. Maximum number of IDs allowed is 50.

GET /api/v1/agentsByIds?agentIds={agent_ids}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/agentsByIds?agentIds=1892000000056007,1892000000042001,1892000000888059
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> List&lt;Agent&gt; response = agent.getAgentsByIds(agentIds );

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "case",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "case@zylker.com",
    "id" : "1892000000056007",
    "zuid" : "437793"
  }, {
    "firstName" : "",
    "lastName" : "jade",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3981311",
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "jade@zylker.com",
    "id" : "1892000000042001",
    "zuid" : "279392"
  }, {
    "firstName" : "Steve",
    "lastName" : "Waugh",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000888059/photo?orgId=3981311",
    "roleId" : "70000000127346",
    "profileId" : "70000000120834",
    "emailId" : "stephen@zylker.com",
    "id" : "1892000000888059",
    "zuid" : "91723912"
  } ]
}

Get My Information

This API fetches details of the currently logged in agent.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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

GET /api/v1/myinfo

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/myinfo?include=profile,role,associatedDepartments,associatedChatDepartments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> Agent response = agent.getMyInfo( include );

Response Example

{
  "associatedChatDepartments" : [ {
    "sanitizedName" : "Developement",
    "name" : "Developement",
    "id" : "1892000000006907"
  } ],
  "lastName" : "Emard",
  "extn" : "",
  "role" : {
    "name" : "CEO",
    "id" : "1892000000056099"
  },
  "langCode" : "fr_FR",
  "emailId" : "emardtorrey@zylker.com",
  "photoURL" : null,
  "countryCode" : "en_US",
  "isConfirmed" : true,
  "id" : "1892000000056007",
  "roleId" : "1892000000056099",
  "profile" : {
    "name" : "Administrator",
    "id" : "1892000000056091"
  },
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "associatedChatDepartmentIds" : [ "1892000000006907" ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "associatedDepartments" : [ {
    "sanitizedName" : "Developement",
    "name" : "Developement",
    "id" : "1892000000006907"
  }, {
    "sanitizedName" : "r-d",
    "name" : "R & D",
    "id" : "1892000000082069"
  } ],
  "firstName" : "Torrey",
  "phone" : "",
  "profileId" : "1892000000056091",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "Torrey Emard",
  "rolePermissionType" : "Admin",
  "aboutInfo" : "Expert in handling tickets and Automations",
  "status" : "ACTIVE"
}

Activate agents

This API activates agents in your help desk.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/activate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/activate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

204

Deactivate agent

This API deactivates an agent in your help desk.

Credit: 1 credit/call

POST /api/v1/agents/{agent_id}/deactivate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/deactivate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Reinvite unconfirmed agents

This API sends reinvitation mails to unconfirmed agents.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/reinvite

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/reinvite
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

204

Add agent

This API adds an agent to your help desk.


Keep in mind the following points while adding an agent:

  1. The emailId, lastName, associatedDepartmentIds, and rolePermissionType are mandatory in the API request.
  2. To assign the profile and role for the agents, pass any of the following values with the rolePermissionType key:
    1. For the Support Administrator profile and CEO role, pass "rolePermissionType":"Admin"
    2. For the Agent profile and public role, pass "rolePermissionType":"AgentPublic"
    3. For the Agent profile and personal role, pass "rolePermissionType":"AgentPersonal"
    4. For custom profiles and roles, pass "rolePermissionType":"Custom" and "roleId":"<actual role ID>", "profileId":"<actual profile ID>"
    5. For the light agent profile and role, pass "rolePermissionType":"Light"
    6. For the Agent profile and Personal Team role, pass "rolePermissionType":"AgentTeamPersonal"

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
emailId

string

required,
max chars : 100

Email ID of the agent

lastName

string

required,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

required

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

required,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 255

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

string

optional,
max chars : 100

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.

langCode

string

optional,
max chars : 100

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

POST /api/v1/agents

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "lastName" : "Walsh",
  "firstName" : "Marisol",
  "countryCode" : "en_US",
  "langCode" : "fr_FR",
  "rolePermissionType" : "Admin",
  "emailId" : "marisol51@zylker.com",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ]
}'

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> Agent agentObj = new Agent();</br> agentObj.setLastName(lastName);<br/>agentObj.setExtn(extn);<br/>agentObj.setLangCode(langCode);<br/>agentObj.setMobile(mobile);<br/>agentObj.setEmailId(emailId);<br/>agentObj.setFirstName(firstName);<br/> Agent response = agent.addAgent( agentObj );

Response Example

{
  "lastName" : "Walsh",
  "extn" : "",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "marisol51@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "firstName" : "Marisol",
  "photoURL" : null,
  "phone" : "",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ ],
  "name" : "Walsh Marisol",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Update agent

This API updates details of an agent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
emailId

string

optional,
max chars : 100

Email ID of the agent

lastName

string

optional,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

optional

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

optional,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 255

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

Country code of the agent. Agents can update only their countryCode. They cannot update the countryCode of other users.

timeZone

string

optional,
max chars : 100

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.

langCode

string

optional,
max chars : 100

Language code of the agent. Agents can update only their langCode. They cannot update the langCode of other users.

PATCH /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

$ curl -X PATCH https://desk.zoho.com/api/v1/agents/1892000000056007
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "lastName" : "Marisol Walsh",
  "firstName" : "K",
  "phone" : "764-484-8068",
  "rolePermissionType" : "Light",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ]
}'

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> Agent agentObj = new Agent();</br> agentObj.setLastName(lastName);<br/>agentObj.setExtn(extn);<br/>agentObj.setLangCode(langCode);<br/>agentObj.setMobile(mobile);<br/>agentObj.setEmailId(emailId);<br/>agentObj.setFirstName(firstName);<br/> Agent response = agent.updateAgent( agentId, agentObj );

Response Example

{
  "lastName" : "Marisol Walsh",
  "extn" : "3298",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "marisol51@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ],
  "firstName" : "K",
  "photoURL" : null,
  "phone" : "764-484-8068",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ "Facebook", "Email", "Forums" ],
  "name" : "K Marisol Walsh",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "Expert in handling Reports",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Delete unconfirmed agents

This API deletes unconfirmed agents from your help desk.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/deleteUnconfirmed

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/deleteUnconfirmed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIds" : [ 1892000000056007, 1892000000056008 ]
}'

Response Example

204

Delete confirmed agent

This API deletes a confirmed agent from your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
anonymizedName

string

optional,
max chars : 50

Nickname of the agent, which will appear on their entity history page

isAnonymize

boolean

optional

Key that determines if the deleted agent must be anonymized in the help desk

POST /api/v1/agents/{agent_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/delete
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "anonymizedName" : "Anonyme",
  "isAnonymize" : true
}'

Response Example

204

Anonymize deleted agent

This API removes the identification details of a deleted agent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
anonymizedName

string

optional,
max chars : 50

Nickname of the agent, which will appear on their entity history page

POST /api/v1/deletedAgents/{agent_id}/anonymize

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/deletedAgents/19000001075071/anonymize
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "anonymizedName" : "Anonyme"
}'

Response Example

204

Upload my photo

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

File Params

userPhoto

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.

POST /api/v1/uploadMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/uploadMyPhoto
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=3981311"
}

Get agent photo

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

Query Params

Param Name
Data Type
Description
fileSize

string

optional,
max chars : 100

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.

GET /api/v1/agents/{agent_id}/photo?orgId={org_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=3981311&fileSize=THUMBNAIL
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Delete My Photo

This API deletes the profile photo of the currently logged in agent.

Credit: 1 credit/call

POST /api/v1/deleteMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/deleteMyPhoto
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get My Preferences

This API fetches the preferences of the currently logged in agent.

Credit: 1 credit/call

GET /api/v1/myPreferences

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myPreferences
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "namePattern" : [ "FIRST_NAME", "LAST_NAME" ],
  "articleAutoSuggestion" : "ENABLED",
  "keyBoardShortcuts" : "ENABLED",
  "pinAllAccounts" : "ENABLED",
  "outBoxDelayTime" : "60S",
  "collapseSidePanel" : "DISABLED",
  "pinAllTickets" : "ENABLED",
  "ticketConversationView" : "ENABLED",
  "contactsView" : "LIST",
  "accountsView" : "LIST",
  "pinAllContacts" : "ENABLED",
  "ticketsView" : "DUEDATE_QUEUE",
  "datePattern" : "dd/MM/yyyy",
  "defaultSendBehavior" : "Send",
  "currentDepartment" : "allDepartment",
  "timeFormat" : "12-hour",
  "outBoxDelay" : "DISABLED",
  "pinAllDashboards" : "DISABLED",
  "loginLandingPage" : "LISTVIEW",
  "loadGettingStartedPage" : "DISABLED",
  "pinAllReports" : "ENABLED"
}

Update My Preferences

This API updates the preferences of the currently logged in agent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
namePattern

List

optional

Pattern that defines how the names should be displayed

currentDepartment

long

optional

A valid active departmentId to which the agent is associated | 'allDepartment'

reportDurationFormat

string

optional,
max chars : 100

Pattern that defines which duration format is used for duration fields in Reports

ui_appearance

string

optional,
max chars : 100

Select the App appearance: light or dark or auto or pureDark

ui_lhsTheme

string

optional,
max chars : 100

Select the Left panel appearance: light or dark

ui_pureDarkMode

string

optional,
max chars : 100

Enable or Disable the pure dark Mode: ENABLED or DISABLED

ui_themes

string

optional,
max chars : 100

Select the App theme: red or green or blue or yellow or orange or pink or skyBlue or teal

ui_displayLayout

string

optional,
max chars : 100

Select the App layout that is optimal for your screen resolution: smartFocus or focusedWidth or fullWidth

ui_displayLayoutWidth

string

optional,
max chars : 100

Select the App layout width: 59 to 89

ui_appFontFamily

string

optional,
max chars : 100

Select the App font family: Zoho Puvi or Lato or Roboto or Vazirmatn or OpenDyslexic

ui_appFontSize

string

optional,
max chars : 100

Select the App font size: 8 to 24

core_editorFontFamily

string

optional,
max chars : 100

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

core_editorFontSize

string

optional,
max chars : 100

Select the Editor Font Size: 8 or 10 or 12 or 14 or 18 or 24 36

core_isPublicComment

string

optional,
max chars : 100

Enable or Disable the Public comment: ENABLED or DISABLED

a11y_criticalLink

string

optional,
max chars : 100

Highlight the Critical link: ENABLED or DISABLED

a11y_underlineLink

string

optional,
max chars : 100

Highlight the link by Underline: ENABLED or DISABLED

a11y_highlightClick

string

optional,
max chars : 100

Highlight the Clickable area: ENABLED or DISABLED

a11Y_animationControls

string

optional,
max chars : 100

Enable or Disable the Animations: regularmotion or reducedmotion or autoReducedmotion

a11y_customScroll

string

optional,
max chars : 100

Enable or Disable the Custom scroll: ENABLED or DISABLED

a11y_zoomLevel

string

optional,
max chars : 100

Select the App Zoom level: 8 to 24

a11y_isFontSizeAdaptToZoom

string

optional,
max chars : 100

Set the App Font size based on the zoom level: ENABLED or DISABLED

a11y_needAccessibilityShortCutInWms

string

optional,
max chars : 100

Enable or Disable the Accessibility ShortCut in wms: ENABLED or DISABLED

a11y_contrast

string

optional,
max chars : 100

Enable or Disable the App Increased Contrast: ENABLED or DISABLED

a11y_contrastLevel

string

optional,
max chars : 100

Select the App Contrast level: low or medium or high

a11y_isContrastRatioAdaptForBg

string

optional,
max chars : 100

Automatically Adapt the Contrast ratio for backgrounds: ENABLED or DISABLED

a11y_readingMask

string

optional,
max chars : 100

Enable or Disable the App Rading Mask: ENABLED or DISABLED

a11y_readingMaskLevel

string

optional,
max chars : 100

Select the Reading mask level: small or medium or full or custom

a11y_readingMaskHeight

string

optional,
max chars : 100

Select the Reading mask height: 10 to 90

a11y_readingMaskWidth

string

optional,
max chars : 100

Select the Reading mask width: 10 to 100

a11y_readingMaskOpacity

string

optional,
max chars : 100

Select the Reding mask opacity: 0.15 to 0.9

core_ticketReplyActions

string

optional,
max chars : 100

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

core_ticketReplyActionsOrder

string

optional,
max chars : 100

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

core_needEmptyQueueColumn

string

optional,
max chars : 100

Enable or Disable the Empty Queue column: ENABLED or DISABLED

communityListViewMode

string

optional,
max chars : 100

The way in which the community topics should be displayed. The allowed values are CLASSIC or COMPACT

communityTopicsSortOrder

string

optional,
max chars : 100

Sort the list of community topics based on order. The allowed values are ascending or descending

communityTopicsSortBy

string

optional,
max chars : 100

Sort the list of community topics based on time. The allowed values are createdTime or modifiedTime

communityTopicsRecordsPerPage

string

optional,
max chars : 100

The number of community topics to be listed on a single page

core_dviBarTabWidth

string

optional,
max chars : 100

Set the width for detail view ibarTab: 357 or 1 to 100 as the decimal value

a11y_focusRing

string

optional,
max chars : 100

Enable or Disable the focusRing: ENABLED or DISABLED

a11y_focusRingEnabledPlaces

string

optional,
max chars : 100

Select the focusRing enabled places: all or main

a11y_notificationView

string

optional,
max chars : 100

Select the notification view: stack or list

a11y_isSuccessNotificationAutoClose

string

optional,
max chars : 100

Enable or Disable the Success notification autoClose: ENABLED or DISABLED

a11y_successNotifcationAutoCloseTime

string

optional,
max chars : 100

Select the Success notification auto close time: 01 or 03 or 05 or 10 or 15 or 20

a11y_isErrorNotificationAutoClose

string

optional,
max chars : 100

Enable or Disable the Error notification autoClose: ENABLED or DISABLED

a11y_errorNotificationAutoCloseTime

string

optional,
max chars : 100

Select the Error notification auto close time: 01 or 03 or 05 or 10 or 15 or 20

a11y_customCursor

string

optional,
max chars : 100

Enable or Disable the App Custom cursor: ENABLED or DISABLED

a11y_customCursorSize

string

optional,
max chars : 100

Select the App Custom cursor size: 8 or 16 or 24 or 32

a11y_customCursorColor

string

optional,
max chars : 100

Select the App Custom cursor color: black or white

a11y_adhdFriendly

string

optional,
max chars : 100

Enable or Disable the adhdFriendly persona: ENABLED or DISABLED

a11y_astigmatism

string

optional,
max chars : 100

Enable or Disable the astigmatism persona: ENABLED or DISABLED

a11y_blindness

string

optional,
max chars : 100

Enable or Disable the blindness persona: ENABLED or DISABLED

a11y_colorBlindness

string

optional,
max chars : 100

Enable or Disable the colorBlindness persona: ENABLED or DISABLED

a11y_dyslexia

string

optional,
max chars : 100

Enable or Disable the dyslexia persona: ENABLED or DISABLED

a11y_epilepsy

string

optional,
max chars : 100

Enable or Disable the epilepsy persona: ENABLED or DISABLED

a11y_elderly

string

optional,
max chars : 100

Enable or Disable the elderly persona: ENABLED or DISABLED

a11y_motorDisabilities

string

optional,
max chars : 100

Enable or Disable the motorDisabilities persona: ENABLED or DISABLED

a11y_seizureSafe

string

optional,
max chars : 100

Enable or Disable the seizureSafe persona: ENABLED or DISABLED

a11y_visuallyImpaired

string

optional,
max chars : 100

Enable or Disable the visuallyImpaired persona: ENABLED or DISABLED

core_ticketsDvIbarPanelView

string

optional,
max chars : 100

Select the Tickets module Detailview Ibar Panel view: collapse or expand

core_contactsDvIbarPanelView

string

optional,
max chars : 100

Select the Contacts module Detailview Ibar Panel view: collapse or expand

core_accountsDvIbarPanelView

string

optional,
max chars : 100

Select the Accounts module Detailview Ibar Panel view: collapse or expand

core_contractsDvIbarPanelView

string

optional,
max chars : 100

Select the Contracts module Detailview Ibar Panel view: collapse or expand

core_callsDvIbarPanelView

string

optional,
max chars : 100

Select the Calls module Detailview Ibar Panel view: collapse or expand

core_tasksDvIbarPanelView

string

optional,
max chars : 100

Select the Tasks module Detailview Ibar Panel view: collapse or expand

core_eventsDvIbarPanelView

string

optional,
max chars : 100

Select the Events module Detailview Ibar Panel view: collapse or expand

core_isTicketReplySendAndUpdateStatus

string

optional,
max chars : 100

Enable or Disable Ticket Reply Send and Update status: ENABLED or DISABLED

ui_tagColorVariant

string

optional,
max chars : 100

Select Tag color variant: bold or subtle or minimal

ui_isTagTextDefaultColor

string

optional,
max chars : 100

Enable or Disable the Tag text default color: ENABLED or DISABLED

core_ticketsTableViewContentStyle

string

optional,
max chars : 100

Select the Tickets Table View content style: wrap or clip

core_contactsTableViewContentStyle

string

optional,
max chars : 100

Select the Contacts Table View content style: wrap or clip

core_accountsTableViewContentStyle

string

optional,
max chars : 100

Select the Accounts Table View content style: wrap or clip

core_contractsTableViewContentStyle

string

optional,
max chars : 100

Select the Contracts Table View content style: wrap or clip

core_callsTableViewContentStyle

string

optional,
max chars : 100

Select the Calls Table View content style: wrap or clip

core_tasksTableViewContentStyle

string

optional,
max chars : 100

Select the Tasks Table View content style: wrap or clip

core_eventsTableViewContentStyle

string

optional,
max chars : 100

Select the Events Table View content style: wrap or clip

a11y_strikeThroughDisabledButton

string

optional,
max chars : 100

Enable or Disable the strikeThrough disabled button: ENABLED or DISABLED

a11y_switchLabel

string

optional,
max chars : 100

Enable or Disable the switch label: ENABLED or DISABLED

feedNotificationFilterPreference

string

optional,
max chars : 100

Feeds Notification Preference value

core_conversationNestedViewLineStyle

string

optional,
max chars : 100

Select the line style for conversation in nested view: curved or straight

core_conversationNestedViewShowIcons

string

optional,
max chars : 100

Enable or Disable the icons display in conversation nested view: ENABLED or DISABLED

core_conversationViewType

string

optional,
max chars : 100

Select the conversation subtab view type: recentTop or recentBottom or nestedView

core_threadCommentViewType

string

optional,
max chars : 100

Select the threads and comments subtabs view type: recentTop or recentBottom

essp_displayContext

string

optional,
max chars : 100

Select the employee portals displayContext: inApp or newTab

essp_displayMode

string

optional,
max chars : 100

Select the employee portals displayMode: compactView or splitView or fullScreenView

a11y_isSearchKeywordHighlighted

string

optional,
max chars : 100

Enable or Disable the highlight search keyword: ENABLED or DISABLED

a11y_isHighlightedSearchKeywordProminent

string

optional,
max chars : 100

Enable or Disable the highlight search keyword more prominent: ENABLED or DISABLED

a11y_mandatoryFieldIndication

string

optional,
max chars : 100

Select the Mandatory Field Indication: asterisk or requiredText

a11y_mandatoryFieldLabelColor

string

optional,
max chars : 100

Select the Mandatory Field Label Color: default (default - Uses the application’s standard label color defined by the active theme appearance.) or red

a11y_colorFilter

string

optional,
max chars : 100

Select the Color Filter: none or grayscale

a11y_grayScaleFilterExcludedPlaces

string

optional,
max chars : 100

Select the places excluded from Grayscale Filter: none or richText_richTextEditor

module_visibilityType

string

optional,
max chars : 100

Select the module visibility type: topBand or unifiedLHS

PATCH /api/v1/myPreferences

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

$ curl -X PATCH https://desk.zoho.com/api/v1/myPreferences
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "namePattern" : [ "LAST_NAME", "FIRST_NAME" ],
  "articleAutoSuggestion" : "ENABLED",
  "keyBoardShortcuts" : "ENABLED",
  "pinAllAccounts" : "ENABLED",
  "outBoxDelayTime" : "60S",
  "collapseSidePanel" : "DISABLED",
  "pinAllTickets" : "ENABLED",
  "ticketConversationView" : "ENABLED",
  "contactsView" : "LIST",
  "accountsView" : "LIST",
  "pinAllContacts" : "ENABLED",
  "ticketsView" : "STATUS_QUEUE",
  "defaultSendBehavior" : "Send",
  "datePattern" : "dd/MM/yyyy",
  "currentDepartment" : "1892000000082069",
  "timeFormat" : "12-hour",
  "outBoxDelay" : "DISABLED",
  "pinAllDashboards" : "DISABLED",
  "loginLandingPage" : "LISTVIEW",
  "loadGettingStartedPage" : "DISABLED",
  "pinAllReports" : "ENABLED"
}'

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId); <br/> boolean response = agent.updateMyPreferences( namePattern, currentDepartment );

Response Example

204

Get agent by email ID

This API fetches details of an agent via the email ID passed in the API request.

Credit: 1 credit/call

GET /api/v1/agents/email/{email}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/email/case@zylker.com
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "lastName" : "case",
  "extn" : "3298",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "timeZone" : "Pacific/Majuro",
  "emailId" : "case@zylker.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
  "firstName" : "",
  "photoURL" : null,
  "phone" : "492-736-6424",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
  "name" : "case",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "aboutInfo" : "Expert in handling Tasks and Automations",
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Schedule reassignment for deactivated or deleted agents

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

Attributes

Param Name
Data Type
Description
agentReassignment

list

required

Details of agents to whom the resources associated with the agent will be reassigned

POST /api/v1/agents/{agent_id}/reassignment

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/19000001075071/reassignment
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentReassignment" : [ {
    "departmentId" : 19000000012754,
    "taskNewOwner" : "19000000008734",
    "ticketNewOwner" : "19000000142005"
  }, {
    "departmentId" : 19000000010674,
    "taskNewOwner" : "19000000008872",
    "ticketNewOwner" : "19000000182001"
  }, {
    "departmentId" : 19000000007073,
    "taskNewOwner" : "19000000008872",
    "ticketNewOwner" : "19000000182001"
  } ]
}'

Response Example

204

Get My Entity Preferences

This API fetches the entity preferences of the currently logged in agent.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
entityType

string

required,
max chars : 25

Entity Type of the preference.

GET /api/v1/myEntityPreferences

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myEntityPreferences
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "entityType" : "department",
    "entityId" : "13658932748374",
    "propValue" : "DISABLED",
    "propName" : "isNotificationEnabled"
  }, {
    "entityType" : "department",
    "entityId" : "13658932748375",
    "propValue" : "ENABLED",
    "propName" : "isNotificationEnabled"
  } ]
}

Update My Entity Preferences

This API updates the entity preferences of the currently logged in agent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
data

list

optional

User entity preferences

PATCH /api/v1/myEntityPreferences

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/myEntityPreferences
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "data" : [ {
    "entityType" : "department",
    "entityId" : 13658932748374,
    "propValue" : "DISABLED",
    "propName" : "isNotificationEnabled"
  }, {
    "entityType" : "department",
    "entityId" : 13658932748375,
    "propValue" : "ENABLED",
    "propName" : "isNotificationEnabled"
  } ]
}'

Response Example

204

Profiles

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

Name of the profile

description

string

Description of the profile

isVisible

boolean

If the profile is visible in UI

type

string

Type of the profile. Possible values are Administrator, Standard, Light, Portal, and Custom

default

boolean

If the profile is system generated

id

long

Id of the profile

permissions

object

Details of the permissions for the profile

Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "import" : false,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "managerDashboard" : {
      "myView" : true,
      "allView" : true,
      "customize" : false
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : true,
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "recycleBin" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "buttons" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "sandbox" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "5000000015288",
  "isVisible" : true,
  "type" : "Administrator"
}


List profiles

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

Query Params

Param Name
Data Type
Description
visible

boolean

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

Key that denotes whether the profiles must be default profiles or custom profiles

searchStr

string

optional,
max chars : 100

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

GET /api/v1/profiles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/profiles?visible=true
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "revokeBlueprint" : true,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : true
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : true,
        "editOthers" : true,
        "delete" : true
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "moderate" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "manageKB" : true,
        "edit" : true,
        "create" : true,
        "admin" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "localization" : true,
        "timeTracking" : true,
        "fetchAcrossDepartment" : true,
        "globalReports" : true,
        "exportPortalUsers" : true,
        "layouts" : true,
        "automation" : true,
        "featureConfig" : true,
        "customerHappiness" : true,
        "department" : true,
        "portal" : true,
        "webForm" : true,
        "rebranding" : true,
        "email" : true,
        "recycleBin" : true,
        "tabsAndFields" : true,
        "exportUsers" : true,
        "teams" : true,
        "social" : true,
        "templates" : true,
        "sandbox" : true,
        "moveRecords" : true,
        "permission" : true,
        "signUpApproval" : true,
        "community" : true,
        "importHistory" : true,
        "manageAgents" : true,
        "portalUsers" : true,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : true,
        "telephony" : true,
        "manageMarketplace" : true
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Support Administrator",
    "description" : "Set the privileges for support administrators.",
    "id" : "5000000015288",
    "isVisible" : true,
    "type" : "Administrator"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : false,
        "import" : false,
        "handleUnassigned" : false,
        "edit" : false,
        "closeTicket" : false,
        "revokeBlueprint" : false,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : false,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : false,
        "editOthers" : true,
        "delete" : false
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "community" : {
        "view" : false
      },
      "products" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : false,
        "import" : false,
        "manageKB" : false,
        "edit" : false,
        "create" : false,
        "admin" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : false,
        "create" : false,
        "delete" : false
      },
      "contacts" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      }
    },
    "name" : "Light Agent",
    "description" : "Set the privilege for light agents",
    "id" : "5000000015306",
    "isVisible" : true,
    "type" : "Light"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : true,
        "import" : false,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : false,
        "revokeBlueprint" : false,
        "mailReview" : false,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : false,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : false,
        "editOthers" : true,
        "delete" : false
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : false,
        "manageKB" : true,
        "edit" : true,
        "create" : true,
        "admin" : true,
        "delete" : true,
        "export" : false
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "tasks" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      }
    },
    "name" : "Newbie Agent",
    "description" : "Set the privileges for new agents.",
    "id" : "5000000015303",
    "isVisible" : true,
    "type" : "Custom"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "tickets" : {
        "mergeTickets" : false,
        "changeOwner" : false,
        "import" : false,
        "handleUnassigned" : false,
        "edit" : false,
        "closeTicket" : false,
        "revokeBlueprint" : false,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : false,
        "edit" : false,
        "editOthers" : false,
        "delete" : false
      },
      "social" : {
        "view" : false,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "community" : {
        "view" : false
      },
      "products" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : false,
        "import" : false,
        "manageKB" : false,
        "edit" : false,
        "create" : false,
        "admin" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "timeEntry" : {
        "view" : false,
        "edit" : false,
        "create" : false,
        "delete" : false
      },
      "contacts" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      },
      "tasks" : {
        "view" : false,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : false
      }
    },
    "name" : "Help Center",
    "description" : "This profile will have the permissions of End Users",
    "id" : "5000000015294",
    "isVisible" : false,
    "type" : "Portal"
  }, {
    "default" : true,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "revokeBlueprint" : false,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : true,
        "editOthers" : true,
        "delete" : true
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "moderate" : false
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "manageKB" : true,
        "edit" : true,
        "create" : true,
        "admin" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Agent",
    "description" : "Set the privileges for standard agents",
    "id" : "5000000015291",
    "isVisible" : true,
    "type" : "Standard"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "revokeBlueprint" : false,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : true,
        "editOthers" : true,
        "delete" : true
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "moderate" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "manageKB" : true,
        "edit" : true,
        "create" : true,
        "admin" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : false,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : false,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Supervisor",
    "description" : "Set the privileges for supervisory users.",
    "id" : "5000000015297",
    "isVisible" : true,
    "type" : "Custom"
  }, {
    "default" : false,
    "permissions" : {
      "crmInteg" : {
        "crmContactsActivityEvents" : false,
        "crmAccountsActivityEvents" : false,
        "crmAccountsActivityTasks" : false,
        "crmAccountsInfo" : false,
        "crmContactsActivityCalls" : false,
        "crmAccountsNotes" : false,
        "crmAccountsActivityCalls" : false,
        "crmContactsInfo" : false,
        "crmContactsNotes" : false,
        "crmContactsActivityTasks" : false,
        "crmAccountsPotentials" : false,
        "crmContactsPotentials" : false
      },
      "reports" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tickets" : {
        "mergeTickets" : true,
        "changeOwner" : true,
        "import" : true,
        "handleUnassigned" : true,
        "edit" : true,
        "closeTicket" : true,
        "revokeBlueprint" : false,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "deleteOthers" : true,
        "edit" : true,
        "editOthers" : true,
        "delete" : true
      },
      "social" : {
        "view" : true,
        "twitterPostDelete" : true,
        "twitterPostCreate" : true,
        "twitterConversationReply" : true
      },
      "mobileapp" : {
        "radar" : true,
        "deskapp" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "moderate" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "agents" : {
        "overview" : true,
        "edit" : false,
        "create" : true,
        "delete" : true,
        "viewAllFields" : true
      },
      "kbCategory" : {
        "view" : true,
        "editAllArticles" : true,
        "import" : true,
        "manageKB" : true,
        "edit" : true,
        "create" : true,
        "admin" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "localization" : false,
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "automation" : true,
        "featureConfig" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "recycleBin" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "teams" : false,
        "social" : false,
        "templates" : false,
        "sandbox" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "manageAgents" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "googleAnalytics" : true,
        "chat" : false,
        "telephony" : false,
        "manageMarketplace" : false
      },
      "financeInteg" : {
        "sendInvoice" : false,
        "createEstimate" : false,
        "createContact" : false,
        "viewInvoice" : false,
        "createInvoice" : false,
        "sendEstimate" : false,
        "viewEstimate" : false
      },
      "accounts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "timeEntry" : {
        "view" : true,
        "edit" : true,
        "create" : true,
        "delete" : true
      },
      "contacts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "tasks" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      }
    },
    "name" : "Support Manager",
    "description" : "Set the privileges for managerial users.",
    "id" : "5000000015300",
    "isVisible" : true,
    "type" : "Custom"
  } ]
}

Get profile count

This API fetches the number of profiles configured in your help desk.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
visible

boolean

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

Key that denotes whether the profiles must be default profiles or custom profiles

GET /api/v1/profiles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/profiles/count?visible=true
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 8
}

Get profile

This API fetches the details of a particular profile.

Credit: 1 credit/call

GET /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/profiles/4000000008464
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : true,
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "recycleBin" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "sandbox" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true,
      "manageMarketplace" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "4000000008464",
  "isVisible" : true,
  "type" : "Administrator"
}

Clone profile

This API replicates an existing profile.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 50

Name of the profile to be created

description

String

optional

Description of the profile to be created

POST /api/v1/profiles/{profile_id}/clone

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/profiles/4000000008543/clone
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Admin Advisors",
  "description" : "Advisors from management to assist the Support Administrators."
}'

Response Example

{
  "default" : false,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : false,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : false,
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "recycleBin" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "sandbox" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Admin Advisors",
  "description" : "Advisors from management to assist the Support Administrators.",
  "id" : "5000000046001",
  "isVisible" : true,
  "type" : "Custom"
}

Update profile

This API updates the details of an existing profile.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 50

Name of the profile

description

string

optional,
max chars : 3200

Description of the profile

permissions

object

optional

Details of the permissions for the profile

PATCH /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/profiles/4000000018001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "permissions" : {
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : false,
      "delete" : false,
      "export" : false
    }
  },
  "name" : "Agent Advisors",
  "description" : "Advisors from CRM to assist the Support Agents."
}'

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : false,
      "delete" : false,
      "export" : false
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : false,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : false
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "import" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "managerDashboard" : {
      "myView" : true,
      "allView" : true,
      "customize" : false
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : false,
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "recycleBin" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "sandbox" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Agent Advisors",
  "description" : "Advisors from CRM to assist the Support Agents.",
  "id" : "4000000018001",
  "isVisible" : true,
  "type" : "Custom"
}

Delete profile

This API deletes a profile from your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
transferToProfileId

long

required

The profile id to which the agents in the delete profile to be transferred to

POST /api/v1/profiles/{profile_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/profiles/4000000018001/delete
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "transferToProfileId" : "4000000008454"
}'

Response Example

204

Get my profile details

This API fetches the configuration details and permissions defined for the profile of the currently logged in user.

Credit: 1 credit/call

GET /api/v1/myProfile

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myProfile
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : true,
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "recycleBin" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "sandbox" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "35483000000008343",
  "isVisible" : true,
  "type" : "Administrator"
}

Get my profile permissions

This API fetches the permissions associated with the profile of the currently logged in user.

Credit: 1 credit/call

GET /api/v1/myProfilePermissions

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myProfilePermissions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "revokeBlueprint" : true,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : true,
      "editOthers" : true,
      "delete" : true
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "manageKB" : true,
      "edit" : true,
      "create" : true,
      "admin" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "localization" : true,
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "recycleBin" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "sandbox" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  }
}

List agents by profile

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

Query Params

Param Name
Data Type
Description
active

boolean

optional

Activation status of the agents to list

confirmed

boolean

optional

Confirmation status of the agents to list

GET /api/v1/profiles/{profile_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/profiles/6000000011303/agents?active=true
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "agents" : [ {
    "firstName" : "",
    "lastName" : "John",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=437793",
    "roleId" : "7000000012324",
    "profileId" : "6000000011303",
    "emailId" : "john@zylker.com",
    "id" : "7000000013328",
    "zuid" : "437793"
  }, {
    "firstName" : "Steve",
    "lastName" : "Kyle",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "6000000011303",
    "emailId" : "kyle@zylker.com",
    "id" : "7000000012958",
    "zuid" : "5625416"
  } ]
}

Get light agent profile

This API fetches the different permissions configured for the light agent profile.

Credit: 1 credit/call

GET /api/v1/lightAgentProfile

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/lightAgentProfile
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : false,
      "changeOwner" : false,
      "import" : false,
      "handleUnassigned" : false,
      "edit" : false,
      "closeTicket" : false,
      "revokeBlueprint" : false,
      "mailReview" : false,
      "delete" : false,
      "view" : true,
      "create" : false,
      "addFollowers" : false,
      "export" : true,
      "mailSend" : false,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "deleteOthers" : true,
      "edit" : false,
      "editOthers" : true,
      "delete" : false
    },
    "social" : {
      "view" : true,
      "twitterPostDelete" : true,
      "twitterPostCreate" : true,
      "twitterConversationReply" : true
    },
    "mobileapp" : {
      "radar" : true,
      "deskapp" : true
    },
    "contracts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "community" : {
      "view" : false
    },
    "products" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : false,
      "import" : false,
      "manageKB" : false,
      "edit" : false,
      "create" : false,
      "admin" : false,
      "delete" : false,
      "export" : true
    },
    "setup" : {
      "localization" : false,
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : false,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "recycleBin" : false,
      "tabsAndFields" : false,
      "exportUsers" : false,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "sandbox" : false,
      "moveRecords" : false,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : false,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : false,
      "telephony" : false,
      "manageMarketplace" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false
    },
    "contacts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    }
  },
  "name" : "Light Agent",
  "description" : "Set the privilege for light agents",
  "id" : "15000000012421",
  "isVisible" : true,
  "type" : "Light"
}

Roles

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

Name of the role

description

string

A short description of the role

isVisible

boolean

Key that denotes if the role is visible in the UI

isDefault

boolean

Key that denotes if the role is the default role

shareDataWithPeers

boolean

Key that denotes if the role shares data with its peer roles

id

long

ID of the role

reportsTo

long

ID of the role to which the current role reports

immediateSubRoles

list

IDs of roles that directly report to the current role

Example

{
  "isDefault" : true,
  "shareDataWithPeers" : true,
  "immediateSubRoles" : [ "5000000054103", "5000000008813", "5000000057018" ],
  "name" : "CEO",
  "description" : "Agent belongs to this role can access all other user's data.",
  "reportsTo" : null,
  "id" : "5000000008807",
  "isVisible" : true
}


List roles

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the roles must be listed

limit

integer

optional,
range : 0-500

Number of roles to display. The default value is 15 and the maximum value allowed is 500.

isVisible

boolean

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

Key that denotes whether the roles must be default roles or custom roles

searchStr

string

optional,
max chars : 100

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

GET /api/v1/roles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/roles
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "shareDataWithPeers" : true,
    "immediateSubRoles" : [ "50000785582324", "50000000779019", "50000001319909" ],
    "name" : "CEO",
    "description" : "Agent belongs to this role can access all other user's data.",
    "reportsTo" : null,
    "id" : "50000000008337",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ "50000091844659" ],
    "name" : "Manager",
    "description" : "Agents belongs to this cannot see admin role users data",
    "reportsTo" : "50000000008337",
    "id" : "50000000008339",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "PortalUser",
    "description" : "User belongs to this role are portal users they can access their cases and solutions only",
    "reportsTo" : "50000000008337",
    "id" : "50000000008341",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Development Team Member",
    "description" : "Development team members from Engineering",
    "reportsTo" : "50000000008337",
    "id" : "50000000469017",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Product Team Member",
    "description" : "Products Managers",
    "reportsTo" : "50000000008337",
    "id" : "50000000551386",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : true,
    "immediateSubRoles" : [ ],
    "name" : "Sales Team Member",
    "description" : "",
    "reportsTo" : "50000000008337",
    "id" : "50000000779019",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Personal",
    "description" : "Agents belongs to this role can see only unassigned and his/her data",
    "reportsTo" : null,
    "id" : "50000002634005",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Marketing Team Member",
    "description" : "",
    "reportsTo" : "50000000008337",
    "id" : "50000009610999",
    "isVisible" : true
  }, {
    "isDefault" : true,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "LightAgent",
    "description" : "Agents belonging to this role can access all user's data.",
    "reportsTo" : null,
    "id" : "50000565365005",
    "isVisible" : false
  } ]
}

List agents by role

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

GET /api/v1/roles/{role_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/roles/50000000008446/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "associatedAgents" : [ "50000000009163", "50000000009300", "50000000010007", "50000000010011", "50000000062391", "50000000062393" ]
}

Create role

This API creates a role in your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

required

Key that denotes if the role shares data with its peer roles

reportsTo

long

optional

ID of the role to which the current role reports

POST /api/v1/roles

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/roles
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "shareDataWithPeers" : true,
  "name" : "Customer Care Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807
}'

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : true,
  "immediateSubRoles" : [ ],
  "name" : "Customer Care Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807,
  "id" : "5000000002973",
  "isVisible" : true
}

Update role

This API updates details of an existing role.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

optional

Key that denotes if the role shares data with its peer roles

reportsTo

long

optional

ID of the role to which the current role reports

PATCH /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/roles/5000000002973
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "shareDataWithPeers" : true,
  "name" : "Customer Care and Sales Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807
}'

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : true,
  "immediateSubRoles" : [ ],
  "name" : "Customer Care and Sales Associate",
  "description" : "Can work on own tickets and can not re-assign tickets.",
  "reportsTo" : 5000000008807,
  "id" : "5000000002973",
  "isVisible" : true
}

Delete role

This API deletes a role from your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
transferToRoleId

long

required

Transfer the child-roles to the given role

POST /api/v1/roles/{role_id}/delete

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/roles/5000000002973/delete
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "transferToRoleId" : "5000000008807"
}'

Response Example

204

Get role

This API fetches the details of a particular role.

Credit: 1 credit/call

GET /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/roles/4000000012414
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDefault" : true,
  "shareDataWithPeers" : false,
  "immediateSubRoles" : [ "4000000012420", "4000000012417" ],
  "name" : "CEO",
  "description" : "Agent belongs to this role can access all other user's data.",
  "reportsTo" : null,
  "id" : "4000000012414",
  "isVisible" : true
}

Get role count

This API fetches the number of roles configured in your help desk.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
isVisible

boolean

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

Key that denotes whether the roles must be default roles or custom roles

GET /api/v1/roles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/roles/count
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get personal role

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

GET /api/v1/personalRole

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/personalRole
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDefault" : false,
  "shareDataWithPeers" : false,
  "immediateSubRoles" : [ ],
  "name" : "Personal",
  "description" : "Agents belongs to this role can see only unassigned and his/her data",
  "reportsTo" : null,
  "id" : "4000000012423",
  "isVisible" : false
}

List roles by role IDs

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

Query Params

Param Name
Data Type
Description
roleIds
see documentation

long

required

Comma separated role ids. Maximum allowed count is 50

GET /api/v1/rolesByIds

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/rolesByIds?roleIds=4000000012423,4000000012420,4000000012414
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ "4000000012420", "4000000012417" ],
    "name" : "CEO",
    "description" : "Agent belongs to this role can access all other user's data.",
    "reportsTo" : null,
    "id" : "4000000012414",
    "isVisible" : true
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "PortalUser",
    "description" : "User belongs to this role are portal users they can access their cases and solutions only",
    "reportsTo" : "4000000012414",
    "id" : "4000000012420",
    "isVisible" : false
  }, {
    "isDefault" : false,
    "shareDataWithPeers" : false,
    "immediateSubRoles" : [ ],
    "name" : "Personal",
    "description" : "Agents belongs to this role can see only unassigned and his/her data",
    "reportsTo" : null,
    "id" : "4000000012423",
    "isVisible" : false
  } ]
}

Teams

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the team

description

String

A short description of the team

departmentId

Long

ID of the department to which the team belongs

subTeams

list

List of sub-teams within the team

roles

list

List of roles to add to the team

rolesWithSubordinates

list

List of roles with subordinates to add to the team

agents

list

List of agents to add to the team

derivedAgents

list

List of agents derived with the properties set for the team

Example

{
  "rolesWithSubordinates" : [ "6000000008684" ],
  "departmentId" : "6000000007245",
  "roles" : [ "6000000008686", "6000000011307" ],
  "name" : "Sales Representatives",
  "description" : "Sales teams for customer engagement.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014005",
  "subTeams" : [ "6000000011305" ],
  "logoUrl" : null,
  "agents" : [ "6000000009086", "6000000012003" ]
}


Create team

This API creates a team in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the team

description

String

optional

A short description of the team

departmentId

Long

required

ID of the department to which the team belongs

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

POST /api/v1/teams

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011307", "6000000011309", "6000000011311" ],
  "name" : "Sales Representatives",
  "description" : "Sales teams for customer engagement.",
  "subTeams" : [ "6000000012001" ],
  "agents" : [ "6000000009086" ]
}'

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
  "name" : "Sales Representatives",
  "description" : "Sales teams for customer engagement.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000012001" ],
  "logoUrl" : null,
  "agents" : [ "6000000009086" ]
}

Update team

This API updates details of an existing team.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the team

description

String

optional

A short description of the team

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

PATCH /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/teams/6000000014007
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "roles" : [ "6000000011307", "6000000011311" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "subTeams" : [ "6000000011303" ],
  "agents" : [ "6000000009086" ]
}'

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011307" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000011303" ],
  "logoUrl" : null,
  "agents" : [ "6000000009086" ]
}

Delete team

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

Attributes

Param Name
Data Type
Description
ticketNewTeam

long

required

Assign open and on hold tickets of the team being deleted to this team.

ticketNewAgent

long

required

Assign open and on hold tickets of the team being deleted to this agent.

taskNewTeam

long

required

Assign open tasks of the team being deleted to this team.

taskNewAgent

long

required

Assign open tasks of the team being deleted to this agent.

POST /api/v1/teams/{team_id}/deleteTeam

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/teams/6000000014007/deleteTeam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketNewAgent" : "5000000013005",
  "ticketNewTeam" : "5000000013001",
  "taskNewTeam" : "5000000013001",
  "taskNewAgent" : "5000000013009"
}'

Response Example

200

Get team

This API fetches the details of a team.

Credit: 1 credit/call

GET /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000014007
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
  "departmentId" : "6000000009893",
  "roles" : [ "6000000011311", "6000000011307" ],
  "name" : "Sales Reps.",
  "description" : "Sales teams for winning customers.",
  "derivedAgents" : [ "6000000009086", "6000000012003" ],
  "id" : "6000000014007",
  "subTeams" : [ "6000000011303" ],
  "logoUrl" : null,
  "agents" : [ "6000000009086" ]
}

List teams from all associated departments

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

GET /api/v1/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000007253",
    "roles" : [ ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ ],
    "id" : "17000000013003",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000009326",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ ],
    "id" : "17000000013005",
    "subTeams" : [ ],
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/6000000011303/logo?orgId=3458634",
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000007253",
    "roles" : [ ],
    "name" : "Engineering",
    "description" : "Developers and Engineers.",
    "derivedAgents" : [ ],
    "id" : "17000000013001",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ ]
  } ]
}

List details of team members

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

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/teams/{team_id}/members

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000011303/members
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "members" : [ {
    "firstName" : "",
    "lastName" : "John",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=437793",
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "john@zylker.com",
    "id" : "7000000013328",
    "zuid" : "437793"
  }, {
    "firstName" : "Steve",
    "lastName" : "Kyle",
    "photoURL" : null,
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "kyle@zylker.com",
    "id" : "7000000012958",
    "zuid" : "5625416"
  } ]
}

List associable teams

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

GET /api/v1/teams/{team_id}/associables

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/teams/6000000011303/associables
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ 6000000011303, 6000000017021, 6000000017023, 6000000016013, 6000000017017, 6000000016015, 6000000017019, 6000000017013, 6000000017015, 6000000017009, 6000000012001, 6000000017011, 6000000017005, 6000000016025, 6000000017007, 6000000017059, 6000000016027, 6000000017001, 6000000016029, 6000000017003, 6000000016031, 6000000016017, 6000000015001, 6000000016019, 6000000016021 ]
}

List associated teams of agent

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

GET /api/v1/agents/{agent_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/6000000011313/teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ "60000000098623" ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ "6000000011313", "60000000120230" ],
    "id" : "6000000083003",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ "6000000011313" ]
  } ]
}

List associated teams for a role

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

GET /api/v1/roles/{role_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/roles/6000000008684/teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ "6000000008684" ],
    "departmentId" : "60000000839483",
    "roles" : [ "60000000098623" ],
    "name" : "Sales Reps.",
    "description" : "Sales teams for winning customers.",
    "derivedAgents" : [ "6000000011313", "60000000120230" ],
    "id" : "6000000083003",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ "6000000008684" ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ "6000000011313" ]
  } ]
}

List teams in department

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

GET /api/v1/departments/{department_id}/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/6000000007245/teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "teams" : [ {
    "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
    "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
    "departmentId" : "6000000007245",
    "name" : "Field Agents",
    "derivedAgents" : [ "6000000009086" ],
    "description" : "Field Agents team for customer issues",
    "id" : "6000000017039",
    "subTeams" : [ ],
    "logoUrl" : null,
    "agents" : [ "6000000009086" ]
  }, {
    "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
    "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
    "departmentId" : "6000000007245",
    "name" : "Managers",
    "derivedAgents" : [ "6000000009086" ],
    "description" : "Managers",
    "id" : "6000000016007",
    "subTeams" : [ "6000000016011", "6000000014005" ],
    "logoUrl" : null,
    "agents" : [ "6000000009086" ]
  } ]
}

Departments

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the department

name

string

Name of the department

nameInCustomerPortal

string

Display name of the department in the help center

description

string

A short description of the department

isVisibleInCustomerPortal

boolean

Key that denotes if the department is visible in the help center or not

isEnabled

boolean

Key that denotes if the department is enabled or not

isAssignToTeamEnabled

boolean

Key that denotes if the assign to team functionality is enabled or not

hasLogo

boolean

Key that denotes if the department has a logo or not

creatorId

long

ID of user who created the department

createdTime

timestamp

Time of creating the department

associatedAgentIds

list

IDs of agents associated with the department

isDefault

boolean

Key that denotes if the department is the default department in the help desk portal

chatStatus

string

Chat status of the departments: AVAILABLE, DISABLED, NOT_CREATED

Example

{
  "isAssignToTeamEnabled" : true,
  "chatStatus" : "NOT_CREATED",
  "hasLogo" : true,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ],
  "isDefault" : true,
  "isEnabled" : true,
  "name" : "Zylker",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082069",
  "nameInCustomerPortal" : "ZylCares"
}


Get department

This API fetches the details of a department from your help desk

Credit: 1 credit/call

GET /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000082069
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isAssignToTeamEnabled" : true,
  "chatStatus" : "AVAILABLE",
  "hasLogo" : true,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ],
  "isDefault" : true,
  "isEnabled" : true,
  "name" : "Zylker",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082069",
  "nameInCustomerPortal" : "ZylCares"
}

List departments

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

Query Params

Param Name
Data Type
Description
isEnabled

boolean

optional

Key that filters departments based on their enabled status

from

integer

optional,
range : >=0

Index number, starting from which the departments must be fetched

searchStr

string

optional,
max chars : 100

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

limit

integer

optional,
range : 0-200

Number of departments to fetch; default value is 10 and maximum value supported is 200

chatStatus

string

optional,
max chars : 100

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.

GET /api/v1/departments

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments?isEnabled=true&chatStatus=AVAILABLE
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : true,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "Zylker",
    "creatorId" : "1892000000042001",
    "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
    "createdTime" : "2019-07-26T13:11:02.000Z",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : false,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "zPad",
    "creatorId" : "1892000000042001",
    "description" : "zPad is the most advanced tablet that brings you the never-experienced-before processing power.",
    "createdTime" : "2019-08-25T10:12:04.000Z",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

List agents in department

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the agents must be listed

limit

integer

optional,
range : 0-200

Number of agents to fetch; default value is 10 and maximum value is 200

status

string

optional,
max chars : 100

Key that filters agents, based on their activation status: ACTIVE or DISABLED

isLightAgent

boolean

optional

Key that denotes if the agents must be light or non light.

isConfirmed

boolean

optional

Key that denotes if the agents must be confirmed or unconfirmed.

searchStr

string

optional,
max chars : 100

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

fieldName

string

optional,
max chars : 100

Name of the field that must be used for searching and listing agents. Values allowed are: firstName, lastName, name, and emailId.

sortOrder

string

optional,
max chars : 100

To sort the available list of agents in either ascending or descending order. Values allowed are: asc or desc

GET /api/v1/departments/{department_id}/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "case",
    "extn" : "3298",
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "case@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "12121",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "case",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "jade",
    "extn" : "3203",
    "roleId" : "1892000000056899",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "jade@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10657727",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ],
    "firstName" : "",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Email", "Forums" ],
    "name" : "jade",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets",
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "john",
    "extn" : "3228",
    "roleId" : "1892000000056004",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "john@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10713988",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "68779989",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat", "Phone", "Twitter", "Web", "Email", "Forums" ],
    "name" : "john",
    "isConfirmed" : true,
    "aboutInfo" : "Expert in handling tickets and Automations",
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "Waugh",
    "extn" : "4020",
    "roleId" : "1892000000056004",
    "langCode" : "ja_JP",
    "mobile" : "",
    "emailId" : "stephen@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : null,
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "Steve",
    "photoURL" : null,
    "phone" : "",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "channelExpert" : [ "Facebook", "Chat" ],
    "name" : "Steve Waugh",
    "isConfirmed" : false,
    "aboutInfo" : "Expert in handling Departments",
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get department count

This API returns the number of departments configured in your help desk portal.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
isEnabled

boolean

optional

Key that filters departments based on their enabled status

GET /api/v1/departments/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907/count?isEnabled=true
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 5
}

Get department details by department IDs

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

Query Params

Param Name
Data Type
Description
departmentIds

long

required

Comma-separated array of department IDs. Maximum number of IDs allowed is 50.

GET /api/v1/departmentsByIds?departmentIds={department_ids}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departmentsByIds?departmentIds=1892000000082069,1892000000082085
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "AVAILABLE",
    "isDefault" : true,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "Zylker",
    "creatorId" : "1892000000042001",
    "description" : "Zylker Inc. is a multinational technology company that designs, develops, and sells consumer electronics.",
    "createdTime" : "2019-07-26T13:11:02.000Z",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "chatStatus" : "DISABLED",
    "isDefault" : false,
    "hasLogo" : true,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "name" : "zPad",
    "creatorId" : "1892000000042001",
    "description" : "zPad is the most advanced tablet that brings you the never-experienced-before processing power.",
    "createdTime" : "2018-07-06T13:11:12.000Z",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

Check for duplicate departments

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

Query Params

Param Name
Data Type
Description
departmentName

string

required,
max chars : 150

Name of the department for which you want to check duplicate entries

GET /api/v1/departments/checkExists

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/checkExists?departmentName=zPad
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDepartmentNameExist" : true
}

Add department

This API adds a department to your help desk portal.

Credit: 50 credits/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

Key that denotes if the department is visible in the help center or not

isAssignToTeamEnabled

boolean

optional

Key that denotes if the assign to team functionality is enabled or not

associatedAgentIds

list

required

IDs of agents associated with the department

POST /api/v1/departments

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/departments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isAssignToTeamEnabled" : false,
  "isVisibleInCustomerPortal" : true,
  "name" : "zPhone",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "nameInCustomerPortal" : "zPhone"
}'

Response Example

{
  "isAssignToTeamEnabled" : false,
  "chatStatus" : "NOT_CREATED",
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "isDefault" : false,
  "isEnabled" : true,
  "name" : "zPhone",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone"
}

Update department

This API updates the details of an existing department.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

Key that denotes if the department is visible in the help center or not

isAssignToTeamEnabled

boolean

optional

Key that denotes if the assign to team functionality is enabled or not

associatedAgentIds

list

optional

IDs of agents associated with the department

PATCH /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/departments/1892000000082085
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isAssignToTeamEnabled" : true,
  "nameInCustomerPortal" : "zPhone Support"
}'

Response Example

{
  "isAssignToTeamEnabled" : true,
  "chatStatus" : "DISABLED",
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "isDefault" : false,
  "isEnabled" : true,
  "name" : "zPhone",
  "createdTime" : "2019-07-26T13:11:02.000Z",
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone Support"
}

Disable department

This API disables a department in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
agentNewDepartment

Long

optional

Agents move to new department ID

emailNewDepartment

Long

optional

Email move to new department ID

POST /api/v1/departments/{department_id}/disable

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/disable
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "emailNewDepartment" : "1892000000082069",
  "agentNewDepartment" : "1892000000082069"
}'

Response Example

204

Enable department

This API enables a department in your help desk portal.

Credit: 1 credit/call

POST /api/v1/departments/{department_id}/enable

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/enable
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Associate agents to department

This API associates agents to a department.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/departments/{department_id}/associateAgents

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/associateAgents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIds" : [ "1892000000042001", "1892000000056007" ]
}'

Response Example

204

Dissociate agents from department

This API dissociates agents from a department.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/departments/{department_id}/dissociateAgents

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/departments/1892000000082085/dissociateAgents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIds" : [ "1892000000056007" ]
}'

Response Example

204

Channels

Channels in Zoho Desk represents the source of the tickets & threads. A channel represents the characteristic of a reply source such as reply configuration.

ATTRIBUTES

Attribute Name
Data Type
Description
type

string

Type of the channel. Possible values are SYSTEM, INTEGRATION, INSTANT_MESSAGE

name

string

Name of the channel

code

string

Unique Identifier Code of the channel

appName

string

Name of the application that handles the channel

photoURL

string

Photo URL of the channel

departmentId

string

Default department ID of the channel in which the tickets will be created unless customized

acceptsReplies

string

Specifies whether the channel accepts replies for tickets or threads

replyConfig

JSONObject

Reply configuration of the channel if the channel accepts replies for tickets or threads

mappedIntegration

string

Type of integration, only if the type is INSTANT_MESSAGE

Example

{
  "photoURL" : null,
  "code" : "EMAIL",
  "appName" : null,
  "departmentId" : null,
  "name" : "EMail",
  "mappedIntegration" : null,
  "replyConfig" : {
    "updateRecords" : false,
    "acceptsAttachments" : true,
    "contentTypes" : [ "text/plain", "text/html" ],
    "includeQuotedMessage" : true
  },
  "type" : "SYSTEM",
  "acceptsReplies" : true
}


List configured channels

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

GET /api/v1/channels

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/channels
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : "https://desk.zoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948",
    "code" : "SALES_WHATSAPP_ACCOUNT",
    "appName" : "Sales Whatsapp Account",
    "departmentId" : "76389000000006907",
    "name" : "Sales Whatsapp Account",
    "externalId" : "109000000002003",
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "INSTANT_MESSAGE",
    "acceptsReplies" : true
  }, {
    "photoURL" : "https://desk.zoho.com/api/v1/channels/youtubecat/photo?orgId=647164567",
    "code" : "YOUTUBECAT",
    "appName" : "Youtube Cat",
    "departmentId" : "188422000009189044",
    "name" : "Youtube Cat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "INTEGRATION",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "EMAIL",
    "appName" : null,
    "departmentId" : null,
    "name" : "Email",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : true,
      "contentTypes" : [ "text/plain", "text/html" ],
      "includeQuotedMessage" : true
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "TWITTER",
    "appName" : null,
    "departmentId" : null,
    "name" : "Twitter",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "TWITTER_DM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Twitter",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "FACEBOOK",
    "appName" : null,
    "departmentId" : null,
    "name" : "Facebook",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "FACEBOOK_DM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Facebook",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "INSTAGRAM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Instagram",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "INSTAGRAM_DM",
    "appName" : null,
    "departmentId" : null,
    "name" : "Instagram",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain" ],
      "includeQuotedMessage" : false
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "WEB",
    "appName" : null,
    "departmentId" : null,
    "name" : "Web",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "ONLINE_CHAT",
    "appName" : null,
    "departmentId" : null,
    "name" : "Chat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "OFFLINE_CHAT",
    "appName" : null,
    "departmentId" : null,
    "name" : "Chat",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FORUMS",
    "appName" : null,
    "departmentId" : null,
    "name" : "Forums",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : {
      "updateRecords" : false,
      "acceptsAttachments" : false,
      "contentTypes" : [ "text/plain", "text/html" ],
      "includeQuotedMessage" : true
    },
    "type" : "SYSTEM",
    "acceptsReplies" : true
  }, {
    "photoURL" : null,
    "code" : "PHONE",
    "appName" : null,
    "departmentId" : null,
    "name" : "Phone",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "ZTI",
    "appName" : null,
    "departmentId" : null,
    "name" : "Phone",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "CUSTOMERPORTAL",
    "appName" : null,
    "departmentId" : null,
    "name" : "Web",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FEEDBACK",
    "appName" : null,
    "departmentId" : null,
    "name" : "FeedBack",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  }, {
    "photoURL" : null,
    "code" : "FEEDBACK_WIDGET",
    "appName" : null,
    "departmentId" : null,
    "name" : "Feedback Widget",
    "externalId" : null,
    "mappedIntegration" : null,
    "replyConfig" : null,
    "type" : "SYSTEM",
    "acceptsReplies" : false
  } ]
}

Tickets

Tickets are organizing units using which service agents handle customer enquiries, requests, complaints, and other such interactions in Zoho Desk.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the ticket

subject

string

Subject of the ticket

departmentId
see documentation

long

ID of the department to which the ticket belongs

contactId
see documentation

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

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.

productId

referred object

ID of the product to which the ticket is mapped

uploads
see documentation

list

File attachments in the ticket. For more information, refer to the Uploads section

email

string

Email ID in the ticket

phone

string

Phone number in the ticket

description

string

Description in the ticket

status

string

Status of the ticket. Includes the custom statuses configured in your help desk portal.

statusType

string

Type of ticket resolution status.The values supported are OPEN and ON HOLD and CLOSED.

assigneeId

long

ID of agent to whom the ticket is assigned

category

string

Category of the ticket

subCategory

string

Subcategory of the ticket

resolution

string

Resolution notes recorded in the ticket

dueDate

timestamp

Due date for resolving the ticket

priority

string

Priority of the ticket

language

string

Language preference to set for the ticket

channel

string

Channel through which the ticket originated.

channelCode

string

Code of the ticket's source channel

source

object

Details of the ticket source from channel

classification

string

Type of ticket. Values supported are Problem, Request, Question, and Others.

customFields 

deprecated

JSONObject

Custom fields in the ticket

cf

JSONObject

Custom fields in the ticket

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the ticket

modifiedTime

timestamp

Time of modifying the ticket

timeEntryCount

integer

Number of time entries recorded in the ticket

approvalCount

integer

Number of approvals associated with the ticket

commentCount

integer

Number of comments in the ticket

attachmentCount

integer

Number of attachments in the ticket

taskCount

integer

Number of tasks associated with the ticket

threadCount

integer

Number of threads associated in the ticket

isDeleted

boolean

Key that returns if the ticket is deleted or not

isTrashed

boolean

Field that denotes whether the ticket is in trash

product

Product

Product associated with the ticket. You obtain this information using the include:product query parameter to fetch this information.

closedTime

timestamp

Time of closing the ticket

ticketNumber

String

Index/Serial number of the ticket

customerResponseTime

timestamp

Time of receiving customer response

isRead

boolean

Key that denotes if the current user has read the ticket or not

sharedDepartments

list

List of departments to which the ticket is shared and the access privileges corresponding to each department

assignee

object

Agent assigned to resolve the ticket. Use the include:assignee query param to fetch this information.

teamId

long

ID of the team assigned to resolve the ticket

isFollowing

boolean

Key that returns if the current user follows the ticket or not

department

object

Details of the department to which the ticket belongs

team

object

Details of the team assigned to resolve the ticket

channelRelatedInfo

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.

secondaryContacts
see documentation

list

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

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

{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "modifiedTime" : "2016-06-21T13:16:14.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ {
    "name" : "Sample Department Name",
    "id" : "1892000000006909",
    "type" : "READ_WRITE"
  }, {
    "name" : "Sample Department Name",
    "id" : "1892000000006911",
    "type" : "READ_ONLY"
  } ],
  "closedTime" : null,
  "approvalCount" : "1",
  "timeEntryCount" : "3",
  "isOverDue" : false,
  "isTrashed" : false,
  "contact" : {
    "lastName" : "Carol",
    "firstName" : "Lucas",
    "phone" : "1 888 900 9646",
    "mobile" : "8838109870",
    "id" : "1892000000042032",
    "isSpam" : false,
    "type" : "paid",
    "email" : "carol@zylker.com",
    "account" : {
      "website" : "www.desk.com",
      "accountName" : "desk Account",
      "id" : "1892000000975382"
    }
  },
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "department" : {
    "name" : "dasdasdasd",
    "id" : "1892000000006907"
  },
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "product" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "secondaryContacts" : [ "1892000000042038", "1892000000042042", "1892000000042056" ],
  "team" : {
    "name" : "kjsdfjks",
    "id" : "8920000000069071",
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
  },
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "teamId" : "8920000000069071",
  "attachmentCount" : "1",
  "isEscalated" : false,
  "assignee" : {
    "firstName" : "dasca",
    "lastName" : "vins",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo",
    "id" : "1892000000056007",
    "email" : "jack@zylker.com"
  },
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}


Get a ticket

This API fetches a single ticket from your helpdesk.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237?include=contacts,products,assignee,departments,team
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2016-06-21T13:16:14.000Z",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "onholdTime" : null,
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ {
    "name" : "Sample Department Name",
    "id" : "1892000000006909",
    "type" : "READ_WRITE"
  }, {
    "name" : "Sample Department Name",
    "id" : "1892000000006911",
    "type" : "READ_ONLY"
  } ],
  "closedTime" : null,
  "sharedCount" : "3",
  "approvalCount" : "1",
  "isOverDue" : false,
  "isTrashed" : false,
  "contact" : {
    "lastName" : "Carol",
    "firstName" : "Lucas",
    "phone" : "1 888 900 9646",
    "mobile" : "8838486174",
    "id" : "1892000000042032",
    "isSpam" : false,
    "type" : null,
    "email" : "carol@zylker.com",
    "account" : {
      "website" : "www.desk.com",
      "accountName" : "desk Account",
      "id" : "1892000000975382"
    }
  },
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "secondaryContacts" : [ "1892000000042038", "1892000000042042", "1892000000042056" ],
  "priority" : "High",
  "classification" : null,
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false,
  "assignee" : {
    "firstName" : "dasca",
    "lastName" : "vins",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
    "id" : "1892000000056007",
    "email" : "jack@zylker.com"
  },
  "status" : "Open",
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "ticketNumber" : "101",
  "isRead" : false,
  "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : {
    "topicId" : "1892000000056253",
    "isTopicDeleted" : false,
    "forumStatus" : "ANALYSING",
    "sourceLink" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Community/singlepost/problem-topic-forum-ticket-18-5-2018",
    "topicType" : "PROBLEM"
  },
  "isDeleted" : "false",
  "department" : {
    "name" : "dasdasdasd",
    "id" : "1892000000006907"
  },
  "followerCount" : "5",
  "email" : "carol@zylker.com",
  "layoutDetails" : {
    "id" : "5000000013466",
    "layoutName" : "Default Ticket Layout"
  },
  "channelCode" : null,
  "product" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "isFollowing" : "true",
  "team" : {
    "name" : "kjsdfjks",
    "id" : "8920000000069071",
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
  },
  "assigneeId" : "1892000000056007",
  "teamId" : "8920000000069071",
  "contractId" : null,
  "tagCount" : "2",
  "attachmentCount" : "1",
  "isEscalated" : false,
  "category" : "general"
}

List all tickets

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the tickets must be fetched

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentIds
see documentation

long

optional

Departments 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.

teamIds
see documentation

string

optional,
max chars : 100

Key that filters tickets by Teams. Values allowed are Unassigned or a valid teamId. Multiple teamIds can be passed as comma-separated values.

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

string

optional,
max chars : 100

assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.

channel

string

optional,
max chars : 100

Filter by channel through which the tickets originated. You can include multiple values by separating them with a comma

status

string

optional,
max chars : 100

Filter by resolution status of the ticket. You can include multiple values by separating them with a comma

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: responseDueDate or customerResponseTime or createdTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

receivedInDays

integer

optional

Fetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.

include
see documentation

string

optional,
max chars : 100

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.

fields

string

optional,
max chars : 100

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.

priority

string

optional,
max chars : 100

Key that filters tickets by priority. Multiple priority levels can be passed as comma-separated values.

GET /api/v1/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets?include=contacts,assignee,departments,team,isRead
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "onholdTime" : null,
    "language" : "English",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543210",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "accountId" : "189200000005345",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@zylker.com"
    },
    "isSpam" : false,
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "176",
    "subCategory" : null,
    "statusType" : "Closed",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-01T14:04:07.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Forums",
    "isRead" : false,
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : "9876543211",
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker sAccount",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-06T09:49:50.000Z",
    "id" : "1892000000094004",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@zylker.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "On Hold",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "isRead" : true,
    "onholdTime" : "2014-03-28T12:09:10.736Z",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:16:03.000Z",
    "id" : "1892000000137057",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "category" : null,
    "status" : "Custom On Hold"
  } ]
}

Get Archived Ticket List

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : 0-4999

Index number, starting from which the tickets must be fetched

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

required

ID of the department from which the tickets must be fetched

viewType

int

optional

View 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

include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/tickets/archivedTickets

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/archivedTickets?from=1&limit=50&departmentId=5853000000006907&viewType=1
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "836",
    "sentiment" : null,
    "subCategory" : null,
    "statusType" : "Closed",
    "subject" : "Subject updated by bulk update",
    "isArchived" : true,
    "dueDate" : "2017-02-16T05:04:01.000Z",
    "departmentId" : "5853000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "permalink" : null,
      "type" : "SYSTEM",
      "appPhotoURL" : null
    },
    "closedTime" : "2017-02-20T10:21:02.000Z",
    "responseDueDate" : null,
    "createdTime" : "2017-02-15T08:23:11.000Z",
    "id" : "5853000001102037",
    "email" : "carol@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2017-02-15T08:23:11.000Z",
    "productId" : null,
    "contactId" : "5853000000273060",
    "threadCount" : "6",
    "lastThread" : {
      "channel" : "EMAIL",
      "isDraft" : true,
      "isForward" : false,
      "direction" : "out"
    },
    "priority" : null,
    "layoutId" : "5853000001987014",
    "assigneeId" : "5853000000281047",
    "commentCount" : "1",
    "accountId" : "189200000005345",
    "phone" : "123421412125",
    "webUrl" : "https://desk.zoho.com/support/arunasales/ShowHomePage.do#Cases/dv/5853000001102037",
    "teamId" : null,
    "isSpam" : false,
    "category" : null,
    "status" : "Closed"
  } ]
}

List all associated tickets

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the tickets must be listed

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

assignee

string

optional,
max chars : 100

assignee - Key that filters tickets by assignee. Values allowed are Unassigned or a valid assigneeId. Multiple assigneeIds can be passed as comma-separated values.

status

string

optional,
max chars : 100

Filter by resolution status of the ticket. You can include multiple values by separating them with a comma

follower

string

optional,
max chars : 100

Filter by followers of the ticket. Values allowed : a valid agentId.

commenter

string

optional,
max chars : 100

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.

sharedDepartmentId

long

optional

Fetches 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.

isShared

boolean

optional

Filter 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).

receivedInDays

integer

optional

Fetches recent tickets, based on customer response time. Values allowed are 15, 30 , 90.

include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/associatedTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/associatedTickets?include=contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543212",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "email" : "carol@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "accountId" : "189200000005345",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@zylker.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "176",
    "subCategory" : null,
    "statusType" : "Closed",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-01T14:04:07.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Forums",
    "onholdTime" : null,
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker sAccount",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-06T09:49:50.000Z",
    "id" : "1892000000094004",
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "accountId" : "189200000005345",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@zylker.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "onholdTime" : "2014-03-28T12:09:10.736Z",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : null,
      "mobile" : "9876543212",
      "id" : "1892000000045028",
      "type" : null,
      "email" : "casie@zylker.com",
      "account" : {
        "website" : "www.zylker.com",
        "accountName" : "Zylker Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:16:03.000Z",
    "id" : "1892000000137057",
    "email" : "casie@zylker.com",
    "channelCode" : null,
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "accountId" : "189200000005345",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

Create a ticket

This API creates a ticket in your helpdesk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

string

required,
max chars : 255

Subject of the ticket

departmentId
see documentation

long

required,
range : >0

ID of the department to which the ticket belongs

contactId
see documentation

referred object

optional

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

Contact

optional

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.

productId

referred object

optional

ID of the product to which the ticket is mapped

uploads
see documentation

list

optional

File attachments in the ticket. For more information, refer to the Uploads section

email

string

optional,
max chars : 150

Email ID in the ticket

phone

string

optional,
max chars : 120

Phone number in the ticket

description

string

optional,
max chars : 65535

Description in the ticket

status

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

assigneeId

long

optional

ID of agent to whom the ticket is assigned

category

string

optional,
max chars : 300

Category of the ticket

subCategory

string

optional,
max chars : 300

Subcategory of the ticket

resolution

string

optional,
max chars : 65535

Resolution notes recorded in the ticket

dueDate

timestamp

optional

Due date for resolving the ticket

priority

string

optional,
max chars : 120

Priority of the ticket

language

string

optional,
max chars : 255

Language preference to set for the ticket

channel

string

optional,
max chars : 120

Channel through which the ticket originated.

classification

string

optional,
max chars : 120

Type of ticket. Values supported are Problem, Request, Question, and Others.

customFields 
deprecated

JSONObject

optional

Custom fields in the ticket

cf

JSONObject

optional

Custom fields in the ticket

webUrl

string

optional,
max chars : 5000

URL to access the resource

sharedDepartments

list

optional

List of departments to which the ticket is shared and the access privileges corresponding to each department

teamId

long

optional

ID of the team assigned to resolve the ticket

secondaryContacts
see documentation

list

optional

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

optional

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.

POST /api/v1/tickets

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "subCategory" : "Sub General",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : "",
  "contactId" : "1892000000042032",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "Hai This is Description",
  "language" : "English",
  "priority" : "High",
  "classification" : "",
  "assigneeId" : "1892000000056007",
  "phone" : "1 888 900 9646",
  "category" : "general",
  "email" : "carol@zylker.com",
  "status" : "Open"
}'

Response Example

{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "modifiedTime" : "2016-06-21T12:50:04.000Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T18:50:04.573Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Hai This is description",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "isOverDue" : false,
  "channelRelatedInfo" : null,
  "isDeleted" : "false",
  "isTrashed" : false,
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "carol@zylker.com",
  "layoutDetails" : {
    "id" : "5000000013466",
    "layoutName" : "Default Ticket Layout"
  },
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "isEscalated" : false,
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Update a ticket

This API updates an existing ticket.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
disableClosureNotification

boolean

optional

Key that enables or disables sending notifications to the corresponding contact when a ticket is closed

Attributes

Param Name
Data Type
Description
subject

string

optional,
max chars : 255

Subject of the ticket

departmentId
see documentation

long

optional,
range : >0

ID of the department to which the ticket belongs

contactId
see documentation

referred object

optional

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

Contact

optional

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.

productId

referred object

optional

ID of the product to which the ticket is mapped

uploads
see documentation

list

optional

File attachments in the ticket. For more information, refer to the Uploads section

email

string

optional,
max chars : 150

Email ID in the ticket

phone

string

optional,
max chars : 120

Phone number in the ticket

description

string

optional,
max chars : 65535

Description in the ticket

status

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

assigneeId

long

optional

ID of agent to whom the ticket is assigned

category

string

optional,
max chars : 300

Category of the ticket

subCategory

string

optional,
max chars : 300

Subcategory of the ticket

resolution

string

optional,
max chars : 65535

Resolution notes recorded in the ticket

dueDate

timestamp

optional

Due date for resolving the ticket

priority

string

optional,
max chars : 120

Priority of the ticket

language

string

optional,
max chars : 255

Language preference to set for the ticket

channel

string

optional,
max chars : 120

Channel through which the ticket originated.

classification

string

optional,
max chars : 120

Type of ticket. Values supported are Problem, Request, Question, and Others.

customFields 
deprecated

JSONObject

optional

Custom fields in the ticket

cf

JSONObject

optional

Custom fields in the ticket

webUrl

string

optional,
max chars : 5000

URL to access the resource

sharedDepartments

list

optional

List of departments to which the ticket is shared and the access privileges corresponding to each department

teamId

long

optional

ID of the team assigned to resolve the ticket

secondaryContacts
see documentation

list

optional

Secondary contacts, such as CC'ed users, associated with the ticket

entitySkills
see documentation

list

optional

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.

PATCH /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/3000000024409
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "subCategory" : "Sub General",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : "",
  "contactId" : "1892000000042032",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "channel" : "FORUMS",
  "description" : "Sample Ticket",
  "language" : "English",
  "priority" : "Low",
  "classification" : "",
  "assigneeId" : "1892000000056007",
  "phone" : "1 888 900 9646",
  "category" : "general",
  "email" : "carol@zylker.com",
  "status" : "Open"
}'

Response Example

{
  "entitySkills" : [ "18921000000379001", "18921000000364001", "18921000000379055", "18921000000379031" ],
  "modifiedTime" : "2016-06-21T12:58:09.122Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-23T12:58:09.211Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "onholdTime" : null,
  "description" : "Sample Ticket",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "isOverDue" : false,
  "channelRelatedInfo" : {
    "isTopicDeleted" : false,
    "forumStatus" : "ANALYSING",
    "sourceLink" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Community/singlepost/problem-topic-forum-ticket-18-5-2018",
    "topicType" : "PROBLEM"
  },
  "isDeleted" : "false",
  "isTrashed" : false,
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "carol@zylker.com",
  "layoutDetails" : {
    "id" : "5000000013466",
    "layoutName" : "Default Ticket Layout"
  },
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "Low",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "isEscalated" : false,
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Move Tickets to trash

This API moves tickets to the Recycle Bin

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ticketIds

list

required

IDs of the tickets to move to the Recycle Bin

POST /api/v1/tickets/moveToTrash

OAuth Scope

Desk.tickets.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketIds" : [ "2000032002032" ]
}'

Response Example

204

Delete spam tickets

This API deletes the given spam tickets

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ticketIds

list

required

IDs of the spam tickets. The maximum allowed number of IDs is 50.

POST /api/v1/tickets/deleteSpam

OAuth Scope

Desk.tickets.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/deleteSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketIds" : [ "1892000000006907", "1892000000006908" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000006907",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000006908",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422",
      "errorJson" : { }
    }
  } ]
}

Merge two tickets

This API merges two different tickets.

Credit: 30 credits/call

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the tickets to merge

source

object

optional

JSON object of the tickets to merge

POST /api/v1/tickets/{ticket_id}/merge

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000008749/merge
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "4000000018011" ],
  "source" : {
    "contactId" : "4000000018011",
    "subject" : "4000000018011",
    "priority" : "4000000018011",
    "status" : "4000000018011"
  }
}'

Response Example

{
  "entitySkills" : [ "42000000000364001", "42000000000379001", "42000000000379031" ],
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "42000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Real Time analysis Requirement",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "isOverDue" : false,
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "4000000008749",
  "email" : "carol@zylker.com",
  "layoutDetails" : {
    "id" : "5000000013466",
    "layoutName" : "Default Ticket Layout"
  },
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "42000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "42000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isEscalated" : false,
  "attachmentCount" : "1",
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Move ticket

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

optional

ID of the department to which you want to move the ticket

Attributes

Param Name
Data Type
Description
departmentId

long

optional

ID of the department in which the ticket exists

forumId

long

optional

ID of the community sub-category to which the forum ticket (forum topic converted into a ticket) must be moved

POST /api/v1/tickets/{ticket_id}/move

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000093303/move
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "1892000000082069",
  "forumId" : "1892000000052355"
}'

Response Example

200

Split tickets

This API splits an incoming ticket thread into a new ticket.

Credit: 2 credits/call

Query Params

Param Name
Data Type
Description
POST /api/v1/tickets/{ticket_id}/threads/{thread_id}/split

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000047005/threads/1892000000133023/split
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "onholdTime" : null,
  "description" : "Real Time analysis Requirement",
  "language" : "English",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "uuid" : null,
    "appPhotoURL" : null
  },
  "resolution" : null,
  "sharedDepartments" : [ ],
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "isOverDue" : false,
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "email" : "carol@zylker.com",
  "channelCode" : null,
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_dateofpurchase" : null,
    "cf_phone" : null,
    "cf_numberofitems" : null,
    "cf_url" : null,
    "cf_secondaryemail" : null,
    "cf_severitypercentage" : "0.0",
    "cf_modelname" : "F3 2017"
  },
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "isEscalated" : false,
  "isSpam" : false,
  "category" : "general",
  "status" : "Open"
}

Bulk update tickets

This API updates multiple tickets at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 32000

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/tickets/updateMany

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "subject",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "Ticket for support"
}'

Response Example

200

Closed many tickets

This API closes multiple tickets at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of tickets to close. Note : A maximum of 50 tickets can be closed in a single API request.

POST /api/v1/closeTickets

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/closeTickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ]
}'

Response Example

200

Mark as read

This API marks a ticket as read by the user.

Credit: 1 credit/call

POST api/v1/tickets/{ticket_id}/markAsRead

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000988091/markAsRead
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Mark as unread

This API marks a ticket as unread by the user.

Credit: 1 credit/call

POST api/v1/tickets/{ticket_id}/markAsUnRead

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000988091/markAsUnRead
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Mark ticket as spam

This API marks tickets as spam.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
isSpam

boolean

required

Key that marks or unmarks a single ticket or multiple tickets as spam

ids

list

required

ID(s) of the ticket(s) that must be marked or unmarked as spam

contactSpam

boolean

optional

Key that marks or unmarks the associated contact as spam

handleExistingTickets

boolean

optional

Key that marks or unmarks the other tickets from the contact(s) as spam

POST /api/v1/tickets/markSpam

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/markSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactSpam" : "true",
  "handleExistingTickets" : "true",
  "ids" : [ "1000000121176", "1000000016435", "1000000016435" ],
  "isSpam" : "true"
}'

Response Example

200

List all ticketQueueView count

This API returns the number of tickets in a particular view.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

ID of the view whose ticket count must be fetched

departmentId
see documentation

String

required

ID of the department from which the ticket count must be fetched

agentId

long

optional

ID of the agent assigned to resolve the tickets

GET api/v1/ticketQueueView/count

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketQueueView/count?viewId=40000000004567&departmentId=allDepartment
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

List all agentsTicketsCount

This API returns the number of tickets assigned to multiple agents.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId
see documentation

String

optional

ID of the department from which the ticket count must be fetched. To fetch ticket count of agents from all departments, pass the value allDepartments.

agentIds

long

optional

IDs of the agents whose ticket count must be fetched

GET api/v1/agentsTicketsCount

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agentsTicketsCount?agentIds=4000000008734,4000000056010
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "onholdCount" : 1,
    "agentId" : "4000000008734",
    "dueIn1HrCount" : 0,
    "overDueCount" : 2,
    "channel" : [ "Mail", "Phone" ],
    "isOnline" : true,
    "openCount" : 18
  }, {
    "onholdCount" : 1,
    "agentId" : "4000000056010",
    "dueIn1HrCount" : 0,
    "overDueCount" : 0,
    "isOnline" : false,
    "openCount" : 0
  } ]
}

Get ticket history

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 0

Index number, starting from which the events must be fetched

limit

int

optional,
range : 1-50

Number of events to list

eventFilter

string

optional,
max chars : 100

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

agentId

long

optional

Key that filters details of actions performed by a particular agent. Value allowed is the agent's ID in Zoho Desk.

fieldName

string

optional,
max chars : 100

Key that filters the history of a particular field. The value for this key must be the apiName of the field.

GET api/v1/tickets/{ticket_id}/History

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/7000000025045/History?eventFilter=CommentHistory
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "actor" : {
      "name" : "Aadavan",
      "id" : "7000000025001",
      "type" : "Contact"
    },
    "eventInfo" : [ {
      "propertyName" : "Department",
      "propertyType" : "Entity",
      "systemProperty" : true,
      "propertyValue" : {
        "name" : "Zylker Primary",
        "id" : "7000000013224",
        "type" : "Department"
      }
    }, {
      "propertyName" : "Account Name",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Primary Account"
    }, {
      "propertyName" : "Contact Name",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Aadavan"
    }, {
      "propertyName" : "Email",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "aathavan@zylker.com"
    }, {
      "propertyName" : "Subject",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Ticket Subject"
    }, {
      "propertyName" : "Description",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "<div>Description.<br /></div>"
    }, {
      "propertyName" : "Status",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Open"
    }, {
      "propertyName" : "Case Owner",
      "propertyType" : "Entity",
      "systemProperty" : true,
      "propertyValue" : {
        "name" : "Imman",
        "id" : "7000000000059",
        "type" : "Agent"
      }
    }, {
      "propertyName" : "Channel",
      "propertyType" : "Text",
      "systemProperty" : true,
      "propertyValue" : "Email"
    }, {
      "propertyName" : "Is Escalated",
      "propertyType" : "Boolean",
      "systemProperty" : true,
      "propertyValue" : false
    } ],
    "eventTime" : "2020-06-03T11:14:52.000Z",
    "eventName" : "TicketCreated",
    "source" : "Email",
    "actorInfo" : [ ]
  } ]
}

Get ticket resolution

This API fetches details related to the resolution of a ticket.

Credit: 1 credit/call

GET api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2015-12-12T00:00:00Z",
  "author" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
    "id" : 160200000000068000,
    "email" : "carol@zylker.com"
  },
  "content" : "test resolution API"
}

Get resolution history

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

Query Params

Param Name
Data Type
Description
from

int

optional

Index number starting from which records must be fetched

limit

int

optional,
range : 1-100

Number of records to fetch

GET api/v1/tickets/{ticket_id}/resolutionHistory

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/resolutionHistory
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2015-12-12T00:00:00Z",
    "author" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
      "id" : 160200000000068000,
      "email" : "carol@zylker.com"
    },
    "content" : "update ticket resolution"
  }, {
    "modifiedTime" : "2015-11-12T00:00:00Z",
    "author" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
      "id" : 160200000000068000,
      "email" : "carol@zylker.com"
    },
    "content" : "add ticket resolution"
  } ]
}

Update ticket resolution

This API updates the resolution field of a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 65535

Content to add in the field

isNotifyContact

boolean

optional

Key that specifies if the contact associated must be notified about the resolution

PATCH api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isNotifyContact" : false,
  "content" : "test resolution API"
}'

Response Example

{
  "modifiedTime" : "2015-12-12T00:00:00Z",
  "author" : {
    "firstName" : "pandi",
    "lastName" : "raj",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/160200000000068005/photo",
    "id" : 160200000000068000,
    "email" : "pandeeswaran@zylker.com"
  },
  "content" : "test resolution API"
}

Delete ticket resolution

This API deletes a resolution added to a ticket.

Credit: 1 credit/call

DELETE api/v1/tickets/{ticket_id}/resolution

OAuth Scope

Desk.tickets.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000190069/resolution
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get ticket metrics

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

GET /api/v1/tickets/([0-9]+)/metrics

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000085990/metrics
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "firstResponseTime" : "01:50 hrs",
  "reassignCount" : 1,
  "outgoingCount" : 2,
  "threadCount" : 2,
  "totalResponseTime" : "02:50 hrs",
  "responseCount" : 1,
  "agentsHandled" : [ {
    "handlingTime" : "00:50 hrs",
    "agentId" : 4000000012629,
    "agentName" : "XXX"
  }, {
    "handlingTime" : "01:50 hrs",
    "agentId" : 4000000080003,
    "agentName" : "YYY"
  } ],
  "resolutionTime" : "02:50 hrs",
  "stagingData" : [ {
    "handledTime" : "01:50 hrs",
    "status" : "Open"
  }, {
    "handledTime" : "00:50 hrs",
    "status" : "onhold"
  } ],
  "reopenCount" : 0
}

Empty spam tickets

This API deletes all spam tickets.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department to which the tickets belong

POST /api/v1/tickets/emptySpam

OAuth Scope

Desk.tickets.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/emptySpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "1892000000006907"
}'

Response Example

202

Execute Skill Based Assignment

This API assigns tickets to agents according to their designated skills and routing preferences.

Credit: 1 credit/call

POST /api/v1/tickets/{ticket_id}/executeSkillbasedAssignment

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1000000159323/executeSkillbasedAssignment?orgId=15157826
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isAssigned" : true,
  "newAssignee" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000000059/photo?orgId=111111",
    "firstName" : "Alex",
    "lastName" : "John",
    "name" : "Alex",
    "roleName" : null,
    "externalId" : null,
    "emailId" : "alex@zylker.com",
    "id" : "1000000000059",
    "type" : "AGENT",
    "email" : "alex@zylker.com",
    "zuid" : "1231232"
  },
  "team" : {
    "name" : "Automation Team",
    "id" : "1000000000089"
  }
}

Recalculate Skills

This API removes existing skills and reapplies the required ones based on the ticket's current circumstances.

Credit: 1 credit/call

POST /api/v1/tickets/{ticket_id}/recalculateSkills

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1000000159323/recalculateSkills
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-24T07:36:33.000Z",
  "skillsInfo" : [ {
    "weightage" : "10",
    "skillName" : "Middle East",
    "skillId" : "1000000174138",
    "skillTypeId" : "1000000173007",
    "mappingType" : "SYSTEM",
    "skillTypeName" : "Region"
  }, {
    "weightage" : "9",
    "skillName" : "Asia",
    "skillId" : "1000000174140",
    "skillTypeId" : "1000000173007",
    "mappingType" : "SYSTEM",
    "skillTypeName" : "Region"
  } ],
  "modifiedBy" : "1000000032001",
  "id" : "1000000170017"
}

Suggest relevant articles for ticket

This API suggests help articles that could be relevant to resolving a ticket.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
from

int

optional,
range : >=0

Index number, starting from which the articles must be fetched

limit

int

optional,
range : 1-50

Number of articles to list

departmentId

long

optional

ID 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

GET /api/v1/tickets/{ticket_id}/articleSuggestion

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/22372000000103001/articleSuggestion?departmentId=40000000012359orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-06-24T11:46:43.000Z",
    "creatorId" : "4000000000059",
    "dislikeCount" : "0",
    "modifierId" : "4000000000059",
    "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
    "likeCount" : "0",
    "locale" : "en",
    "latestVersionModifierId" : "4000000000060",
    "ownerId" : "4000000000059",
    "title" : "Answering your first ticket.",
    "isTrashed" : false,
    "createdTime" : "2020-06-24T11:46:43.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019059",
    "viewCount" : "0",
    "templateUsedUsersCount" : "2",
    "owner" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "permission" : "AGENTS",
    "authorId" : "4000000000059",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "4000000017276",
    "templateUsageCount" : "0",
    "translationId" : "4000000017294",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "latestVersion" : "1.0",
    "isTemplate" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "feedbackCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
    "attachmentCount" : "0",
    "latestPublishedVersion" : "1.0",
    "category" : {
      "name" : "General",
      "id" : "4000000017287",
      "locale" : "en"
    },
    "permalink" : "answering-your-first-ticket",
    "categoryId" : "4000000017287",
    "latestVersionModifiedBy" : {
      "photoURL" : null,
      "name" : "will smith",
      "id" : "4000000000060",
      "status" : "ACTIVE",
      "zuid" : "234544"
    },
    "status" : "Published"
  } ]
}

Threads

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the thread

channel

string

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

status

string

Status of the thread.Values supported are SUCCESS,PENDING,FAILED,DRAFT

content

string

Content of the thread

contentType

string

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

createdTime

timestamp

Time of creating the thread

direction

string

Key that returns whether the thread is incoming or outgoing

author

object

Details of the user who created the thread

fromEmailAddress
see documentation

string

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

to

string

To email ID in the thread, applicable only for EMAIL channel

cc

string

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

phoneno

string

Phone number through which the thread originated, applicable only for the ZTI and TWILIO

summary

string

Summary of the thread

attachments

object

Attachments in the thread

hasAttach

boolean

States whether the thread has attachments

isDescriptionThread

boolean

Key that denotes if the thread is the description of the ticket

channelRelatedInfo

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

actions

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.

respondedIn

string

Time taken by the agent to respond to the customer

canReply

boolean

Specifies whether replies can be added be added to this thread.

source

object

Details of the thread source from channel

ticketStatus

string

Status of the ticket. Includes the custom statuses configured in your help desk portal.

Example

{
  "summary" : "How was our Customer Service",
  "attachments" : [ {
    "size" : "1913",
    "name" : "ScreenShot",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade@zylker.com"
  },
  "channel" : "FORUMS",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "How was our Customer Service ?",
  "hasAttach" : true,
  "createdTime" : "2016-03-21T08:46:48.248Z",
  "id" : "1892000000135387",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}


Get a thread

This API fetches a single thread from your help desk portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Content of the thread in plain text format. Value allowed is plainText.

GET /api/v1/tickets/{ticket_id}/threads/{thread_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000135387?include=plainText
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isDescriptionThread" : true,
  "attachments" : [ {
    "size" : "1913",
    "name" : "ScreenShot",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "bcc" : "",
  "isContentTruncated" : true,
  "canReply" : true,
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "<div>Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation</div>",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "plainText" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "id" : "1892000000135387",
  "contentType" : "text/html",
  "direction" : "in",
  "cc" : "",
  "summary" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  },
  "fullContentURL" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/fullContent",
  "isForward" : false,
  "hasAttach" : true,
  "replyTo" : "jhonwin@zylker.com",
  "attachmentCount" : "1",
  "to" : "techsupport@zylker.com",
  "fromEmailAddress" : "jade12tywin@zylker.com",
  "actions" : [ ],
  "status" : "SUCCESS"
}

Get Original Mail Content

This API get the orginal mail content including mail headers

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
inline

boolean

optional

set this param as true if attachment is to be rendered

GET /api/v1/tickets/{ticket_id}/threads/{thread_id}/originalContent

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET /api/v1/tickets/1892000000094004/threads/1892000011194123/originalContent
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "date" : "Tue, 30 Mar 2021 16:53:12 +0530",
  "returnPath" : "<abc@zylker.com>",
  "subject" : "Testing Mail Service",
  "messageId" : "<17882df63bf.b181c6c3583.8110594270247400030@zylker.com>",
  "from" : "ReplyTo <abc@zylker.com>",
  "to" : "\"support\" <support@zylker.com>",
  "content" : "Delivered-To: support@zylker.com\nReturn-Path: <abc@zylker.com>\nDomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; \n  s=zoho; d=zoho.com; \n  h=date:from:reply-to:to:message-id:subject:mime-version:content-type:user-agent; \n  b=E6QQb4TtZN7WU1zmeUJx3hjj9BL0l/m6NhQU/3Oi+YlvXXhxSL6BFK0+CsAqJ/BJY/Y9hmdGNOM2\n    I62RiQ5y8r9bUrVnGZH+Z9HvO3lPXZ4wM9kXypm9xmOo+gf0Dc2DxJKfPCvGrLT1QDzxeO+3tlPZ\n    Xeqt6AsiCjXsXLcNUwc=  \nReceived: from mail.zoho.com by zohomail.com.in\n\twith SMTP id 1617103392140118.88266397173629; Tue, 30 Mar 2021 16:53:12 +0530 (IST)\nDate: Tue, 30 Mar 2021 16:53:12 +0530\nFrom: ReplyTo <abc@zylker.com>\nReply-To: abc@zylker.com\nTo: \"support\" <support@zylker.com>\nMessage-Id: <17882df63bf.b181c6c3583.8110594270247400030@zylker.com>\nSubject: Testing Mail Service\nMIME-Version: 1.0\nContent-Type: multipart/alternative; \n\tboundary=\"----=_Part_1259_1074835283.1617103381439\"\nImportance: Medium\nUser-Agent: Zoho Mail\nX-Mailer: Zoho Mail\nX-ZohoMail-Owner: <17882df63bf.b181c6c3583.8110594270247400030@zylker.com>+zmo_0_abc@zylker.com\n\n------=_Part_1259_1074835283.1617103381439\nContent-Type: text/plain; charset=\"UTF-8\"\nContent-Transfer-Encoding: 7bit\n\nAldjfh Giri\n\n\n\n\n\nReplyTo\n------=_Part_1259_1074835283.1617103381439\nContent-Type: text/html; charset=\"UTF-8\"\nContent-Transfer-Encoding: 7bit\n\n<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\"><html><head><meta content=\"text/html;charset=UTF-8\" http-equiv=\"Content-Type\" /></head><body><div style=\"font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10pt;\"><div><br /></div><div><br />Aldjfh Giri<br /></div><div id=\"\"><div><br /></div><div><br /></div><div>ReplyTo<br /></div><div><br /></div></div></div><br /></body></html>\n------=_Part_1259_1074835283.1617103381439--\n\n"
}

Get Latest thread

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

Query Params

Param Name
Data Type
Description
needPublic

boolean

optional,
default : false

Key that denotes if the thread must be a public thread

needIncomingThread

boolean

optional,
default : false

Key that denotes if the thread must be an incoming threads only

include
see documentation

string

optional,
max chars : 100

Content of the thread in plain text format. Value allowed is plainText.

threadStatus

string

optional,
max chars : 100

Receipt status of the thread. Values allowed are success and failed

GET /api/v1/tickets/{ticket_id}/latestThread

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/latestThread
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "cc" : "",
  "summary" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "attachments" : [ {
    "size" : "1913",
    "name" : "ScreenShot",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "bcc" : "",
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation",
  "isForward" : false,
  "hasAttach" : true,
  "replyTo" : "jhonwin@zylker.com",
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "to" : "techsupport@zylker.com",
  "id" : "1892000001083008",
  "fromEmailAddress" : "jade12tywin@zylker.com",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "in"
}

Send For Review

This API saves drafts of agent's responses to customers and sends them to a manager/senior agent for review.

Credit: 1 credit/call

POST /api/v1/tickets/{ticket_id}/threads/{thread_id}/sendForReview

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000012313/sendForReview
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List all threads

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the threads must be fetched

limit

integer

required,
default : 100,
range : 1-200

Number of threads to fetch

sortBy

string

optional,
max chars : 100

Key that sorts the threads by sendDateTime.
If the value of sortBy key is:

  • "sendDateTime" - sorting will be done in ascending order
  • "-sendDateTime " - (prefix the value with a "-") sorting will be done in descending order

Note: If this sortBy key is not specified, the sorting will be done in descending order by default based on sendDateTime.

GET /api/v1/tickets/{ticket_id}/threads

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/threads
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isDescriptionThread" : true,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FORUMS",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : null,
    "hasAttach" : false,
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true",
      "externalLink" : null
    },
    "respondedIn" : null,
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "7",
    "id" : "1892000000413186",
    "fromEmailAddress" : "jade12tywin@zylker.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "summary" : "Customer Rating",
    "cc" : "",
    "isDescriptionThread" : false,
    "bcc" : "",
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "EMAIL",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "isForward" : false,
    "hasAttach" : true,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : null,
    "respondedIn" : "00:05:14",
    "createdTime" : "2016-05-25T10:06:09.686Z",
    "attachmentCount" : "4",
    "id" : "1892000001004072",
    "to" : "carol@zylker.com",
    "fromEmailAddress" : "techsupport@zylker.com",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/resendFailedThread?threadId=1892000001083008"
    } ],
    "contentType" : "text/html",
    "status" : "FAILED",
    "direction" : "out"
  }, {
    "summary" : "Please fix this problem, since it is urgent posted the issue on Facebook ",
    "isDescriptionThread" : false,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FACEBOOK",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : "https://desk.zoho.com/api/v1/ratingOptions/31138000005998227/logo?orgId=54983163",
    "hasAttach" : false,
    "responderId" : "2150000000043591",
    "channelRelatedInfo" : null,
    "respondedIn" : "00:04:09",
    "createdTime" : "2016-07-25T10:04:43.739Z",
    "attachmentCount" : "6",
    "id" : "2150000002498038",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
    }, {
      "method" : "DELETE",
      "rel" : "delete",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
    } ],
    "contentType" : "text/html",
    "status" : "DRAFT",
    "direction" : "out"
  }, {
    "isDescriptionThread" : false,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FEEDBACK",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "lastRatingIconURL" : null,
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "respondedIn" : null,
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "5",
    "id" : "1892000000413189",
    "fromEmailAddress" : "jade12tywin@zylker.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  } ]
}

List conversations

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Starting index from which the conversations should be fetched.

limit

integer

required,
default : 100,
range : 1-200

Number of conversations to fetch

GET /api/v1/tickets/{ticket_id}/conversations

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000321001/conversations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "We have found the root cause for the issue and fixed it. How would you rate our customer service? Good Okey Bad",
    "isDescriptionThread" : true,
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FORUMS",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "type" : "thread",
    "lastRatingIconURL" : "https://desk.zoho.com/api/v1/ratingOptions/31138000005998227/logo?orgId=54983163",
    "isForward" : false,
    "hasAttach" : false,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true",
      "externalLink" : null
    },
    "respondedIn" : "00:05:14",
    "createdTime" : "2016-07-07T10:12:04.177Z",
    "attachmentCount" : "7",
    "id" : "1892000001080014",
    "fromEmailAddress" : "techsupport@zylker.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "out"
  }, {
    "summary" : "Any update regarding the issue",
    "cc" : "productmanagement@zylker.com",
    "isDescriptionThread" : false,
    "bcc" : "",
    "canReply" : true,
    "visibility" : "public",
    "author" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : null,
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "EMAIL",
    "source" : {
      "appName" : null,
      "extId" : null,
      "type" : "SYSTEM",
      "permalink" : null,
      "appPhotoURL" : null
    },
    "type" : "thread",
    "lastRatingIconURL" : null,
    "isForward" : false,
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "respondedIn" : null,
    "createdTime" : "2016-07-07T10:02:04.663Z",
    "attachmentCount" : "6",
    "id" : "1892000001080004",
    "to" : "techsupport@zylker.com",
    "fromEmailAddress" : "jade12tywin@zylker.com",
    "actions" : [ ],
    "contentType" : "text/html",
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "modifiedTime" : "2016-02-16T14:12:20.000Z",
    "commentedTime" : "2016-02-16T09:21:58.000Z",
    "isPublic" : true,
    "id" : "1892000000886025",
    "type" : "comment",
    "content" : "There is a major issue with the real time dashboard feature . Kindly look into it",
    "commenterId" : "1892000000042001",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Send Reply via Integrated Custom Channels

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.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "YOUTUBE",
  "content" : "Thank you for your valueable comment."
}'

Response Example

{
  "summary" : "Thank you for your valueable comment.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "YOUTUBE",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thank you for your valueable comment.",
  "isForward" : false,
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "respondedIn" : "00:05:14",
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "Zylker Vlogs",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "PENDING",
  "direction" : "out"
}

Send Email Reply

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/call

Query Params

Param Name
Data Type
Description
isPrivate

boolean

optional,
default : false

Specify whether the thread is Private

sendImmediately

boolean

optional,
default : false

Specify whether the reply has to sent immediately

Attributes

Param Name
Data Type
Description
channel

string

optional,
max chars : 100

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

content

string

required,
max chars : 16000000

Content of the thread

contentType

string

optional,
max chars : 100

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

optional

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

optional

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

optional

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

optional

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

direction

string

optional,
max chars : 100

Key that returns whether the thread is incoming or outgoing

fromEmailAddress
see documentation

string

optional,
max chars : 300

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

to

string

optional,
max chars : 13000

To email ID in the thread, applicable only for EMAIL channel

cc

string

optional,
max chars : 13000

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

optional,
max chars : 13000

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

hasAttach

boolean

optional

States whether the thread has attachments

ticketStatus

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketStatus" : "Closed",
  "channel" : "EMAIL",
  "attachmentIds" : [ "1312123141313" ],
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "contentType" : "plainText",
  "content" : "We have identified the root cause and fixed it.",
  "isForward" : "true"
}'

Response Example

{
  "summary" : "We have identified the root cause and fixed it.",
  "cc" : "",
  "isDescriptionThread" : true,
  "bcc" : "",
  "attachments" : [ {
    "size" : "818",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We have identified the root cause and fixed it.",
  "isForward" : true,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "respondedIn" : "00:03:10",
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "PENDING",
  "direction" : "out"
}

Send Facebook Reply

This API adds a reply to a Facebook post

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "FACEBOOK",
  "content" : "We are looking into the issue."
}'

Response Example

{
  "summary" : "We are looking into the issue.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We are looking into the issue.",
  "hasAttach" : false,
  "responderId" : "2150000000043591",
  "channelRelatedInfo" : null,
  "respondedIn" : "00:07:07",
  "createdTime" : "2016-07-25T10:04:43.739Z",
  "id" : "2150000002498038",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Send Twitter Reply

This API sends a reply to a tweet.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "TWITTER",
  "content" : "The problem has been fixed. Sorry for the inconvenience caused."
}'

Response Example

{
  "summary" : "The problem has been fixed. Sorry for the inconvenience caused.",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "TWITTER",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "respondedIn" : "00:10:24",
  "createdTime" : "2016-07-25T10:01:14.536Z",
  "id" : "2150000002498018",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Send Forum Reply

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.

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback"
}'

Response Example

{
  "summary" : "Thanks for your feedback",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true",
    "externalLink" : null
  },
  "respondedIn" : "00:06:54",
  "createdTime" : "2016-07-25T09:50:03.578Z",
  "id" : "1892000001121138",
  "actions" : [ ],
  "contentType" : "text/html",
  "status" : "SUCCESS",
  "direction" : "out"
}

Draft Email Reply

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

Query Params

Param Name
Data Type
Description

Attributes

Param Name
Data Type
Description
channel

string

optional,
max chars : 100

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

content

string

required,
max chars : 16000000

Content of the thread

contentType

string

optional,
max chars : 100

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

optional

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

optional

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

optional

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

optional

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

direction

string

optional,
max chars : 100

Key that returns whether the thread is incoming or outgoing

fromEmailAddress
see documentation

string

optional,
max chars : 300

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

to

string

optional,
max chars : 13000

To email ID in the thread, applicable only for EMAIL channel

cc

string

optional,
max chars : 13000

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

optional,
max chars : 13000

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

hasAttach

boolean

optional

States whether the thread has attachments

ticketStatus

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "EMAIL",
  "attachmentIds" : [ "1312123141313" ],
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "contentType" : "plainText",
  "content" : "We have escaled the issue. Will update you regarding the progress.",
  "isForward" : "true"
}'

Response Example

{
  "summary" : "We have escaled the issue. Will update you regarding the progress.",
  "cc" : "",
  "isDescriptionThread" : false,
  "bcc" : "",
  "attachments" : [ {
    "size" : "324",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We have escaled the issue. Will update you regarding the progress.",
  "isForward" : false,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Draft Facebook Reply

This API drafts a reply to a Facebook post.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "FACEBOOK",
  "content" : "The issue has been fixed"
}'

Response Example

{
  "summary" : "The issue has been fixed",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "The issue has been fixed",
  "hasAttach" : false,
  "responderId" : "2150000000043591",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:04:43.739Z",
  "id" : "2150000002498038",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Draft Forum Reply

This API drafts a reply to a forum post.

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback"
}'

Response Example

{
  "summary" : "Thanks for your feedback",
  "isDescriptionThread" : false,
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true",
    "externalLink" : null
  },
  "createdTime" : "2016-07-25T09:50:03.578Z",
  "id" : "1892000001121138",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Update Draft

This API updates a draft thread created via the EMAIL, FACEBOOK, or FORUM channel.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
channel

string

optional,
max chars : 100

Channel through which the thread originated. Values supported are FACEBOOK, TWITTER, EMAIL and FORUMS .

content

string

optional,
max chars : 16000000

Content of the thread

contentType

string

optional,
max chars : 100

Formatting type of the content. Applicable only for the EMAIL channel. Values supported are html and plainText (default).

isForward

boolean

optional

Key that returns if the thread was sent as a forward. Applicable only for the EMAIL channel.

isPrivate

boolean

optional

Specifies whether the thread is Private or Public. Forwarded threads are always private.

inReplyToThreadId

long

optional

ID of the thread to which current thread is a reply, applicable only for EMAIL channel

attachmentIds
see documentation

list

optional

List of attachment IDs, applicable only for EMAIL channel. For information on how to retrieve attachment IDs, refer to the Uploads section.

direction

string

optional,
max chars : 100

Key that returns whether the thread is incoming or outgoing

fromEmailAddress
see documentation

string

optional,
max chars : 300

Mandatory parameter for creating an email thread. Applicable for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS channels.

to

string

optional,
max chars : 13000

To email ID in the thread, applicable only for EMAIL channel

cc

string

optional,
max chars : 13000

Email ID to be CC-ed. Applicable only for EMAIL channel

bcc

string

optional,
max chars : 13000

Email ID to be BCC-ed., if any exist. Applicable only for EMAIL channel

hasAttach

boolean

optional

States whether the thread has attachments

ticketStatus

string

optional,
max chars : 120

Status of the ticket. Includes the custom statuses configured in your help desk portal.

PATCH /api/v1/tickets/{ticket_id}/draftReply/{thread_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "channel" : "EMAIL",
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "contentType" : "plainText",
  "content" : "We are analysing the issue currently , will update you with a solution as early as possible"
}'

Response Example

{
  "summary" : "We are analysing the issue currently , will update you with a solution as early as possible",
  "cc" : "",
  "isDescriptionThread" : false,
  "bcc" : "",
  "canReply" : true,
  "visibility" : "public",
  "author" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "source" : {
    "appName" : null,
    "extId" : null,
    "type" : "SYSTEM",
    "permalink" : null,
    "appPhotoURL" : null
  },
  "content" : "We are analysing the issue currently , will update you with a solution as early as possible",
  "isForward" : false,
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zylker.com",
  "fromEmailAddress" : "techsupport@zylker.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "contentType" : "text/html",
  "status" : "DRAFT",
  "direction" : "out"
}

Delete attachment

This API deletes an attachment from a draft thread.

Credit: 1 credit/call

DELETE /api/v1/tickets/{ticket_id}/threads/{thread_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Contacts

Contacts are the end-customers who raise requests or make enquiries/complaints with your customer service team. Each contact is mapped to an account.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the contact

customFields 

deprecated

object

User-defined fields related to the contact

cf

JSONObject

User-defined fields related to the contact

lastName

string

Last name of the contact

firstName

string

First name of the contact

facebook

string

Facebook ID of the contact

twitter

string

Twitter ID of the contact

secondaryEmail

string

Secondary email ID of the contact

email

string

Email ID of the contact

phone

string

Phone number of the contact

mobile

string

Mobile number of the contact

city

string

Contact's city of residence

country

string

Contact's country of residence

state

string

Contact's state of residence

street

string

Contact's address

zip

string

Zip code

description

string

Contact description

title

string

Contact title

type

string

Contact type

ownerId

long

ID of the user who creates the contact

owner

object

Details of the user to whom the contact is assigned.

accountId
see documentation

long

Account to which the contact is mapped

zohoCRMContact

object

Contact details fetched from Zoho CRM

customerHappiness

object

Average customer happiness rating of the contact

isDeleted

boolean

Key that returns if the contact is deleted or not

isTrashed

boolean

Field that denotes whether the contact is in trash

isSpam

boolean

Field that denotes whether the contact is spam

photoURL

string

URL of the file containing the image of the contact

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the contact

modifiedTime

timestamp

Time of modifying the contact

language

string

Language preference to set for the Contact

Example

{
  "lastName" : "Smith",
  "modifiedTime" : "2015-03-02T14:49:32.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "description" : null,
  "ownerId" : "3263000000057001",
  "type" : null,
  "title" : null,
  "photoURL" : null,
  "twitter" : null,
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : null,
  "createdTime" : "2015-02-16T14:46:24.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "potentials"
  },
  "state" : null,
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "id" : "3263000000064001",
  "email" : "lawrence@zylker.com",
  "zip" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : null,
  "mobile" : null,
  "accountId" : null,
  "firstName" : "Jade",
  "phone" : "123 99 888 23",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}


Get Contact

This API fetches a single contact from your help desk portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Allowed values are : accounts , owner

GET /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000000042032?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "lastName" : "Lawrence",
  "modifiedTime" : "2016-05-04T09:57:17.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "description" : null,
  "language" : "English",
  "ownerId" : "1892000000042001",
  "type" : null,
  "title" : null,
  "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
  "twitter" : null,
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "contacts_leads"
  },
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "state" : null,
  "id" : "1892000000042032",
  "email" : "lawrence@zylker.com",
  "zip" : null,
  "owner" : {
    "firstName" : "Twin",
    "lastName" : "john",
    "id" : "1892000000042001"
  },
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : null,
  "mobile" : null,
  "accountId" : "1892000000975382",
  "firstName" : "Jennifer",
  "isAnonymous" : false,
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

List contacts

This API lists a particular number of contacts, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

list

optional

Secondary information related to the contact.Value supported is accounts.

from

integer

optional

Index number, starting from which the contacts must be fetched

limit

string

optional,
max chars : 100,
range : 1-100

Number of contacts to fetch

viewId

integer

optional

ID of the view to apply while fetching the resources

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: firstName, lastName, or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

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: photoURL, webUrl. Maximum of 30 fields is supported as comma separated values.

GET /api/v1/contacts

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "mobile" : "+91 8508569683",
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : false,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T14:46:24.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "mobile" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : false,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T14:46:24.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

Create Contact

This API creates a contact in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

object

optional

User-defined fields related to the contact

cf

JSONObject

optional

User-defined fields related to the contact

lastName

string

required,
max chars : 200

Last name of the contact

firstName

string

optional,
max chars : 40

First name of the contact

facebook

string

optional,
max chars : 100

Facebook ID of the contact

twitter

string

optional,
max chars : 100

Twitter ID of the contact

secondaryEmail

string

optional,
max chars : 100

Secondary email ID of the contact

email

string

optional,
max chars : 255

Email ID of the contact

phone

string

optional,
max chars : 50

Phone number of the contact

mobile

string

optional,
max chars : 50

Mobile number of the contact

city

string

optional,
max chars : 100

Contact's city of residence

country

string

optional,
max chars : 100

Contact's country of residence

state

string

optional,
max chars : 100

Contact's state of residence

street

string

optional,
max chars : 250

Contact's address

zip

string

optional,
max chars : 30

Zip code

description

string

optional,
max chars : 65535

Contact description

title

string

optional,
max chars : 100

Contact title

type

string

optional,
max chars : 120

Contact type

ownerId

long

optional

ID of the user who creates the contact

accountId
see documentation

long

optional

Account to which the contact is mapped

language

string

optional,
max chars : 255

Language preference to set for the Contact

POST /api/v1/contacts

OAuth Scope

Desk.contacts.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "zip" : "123902",
  "lastName" : "Jack",
  "country" : "USA",
  "secondaryEmail" : "hughjack@zylker.com",
  "city" : "Texas",
  "facebook" : "hugh jacks",
  "mobile" : "+10 2328829010",
  "description" : "first priority contact",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "accountId" : "1892000000052077",
  "firstName" : "hugh",
  "twitter" : "Hugh jack",
  "phone" : "91020080878",
  "street" : "North street",
  "state" : "Austin",
  "email" : "jack@zylker.com"
}'

Response Example

{
  "lastName" : "Jack",
  "modifiedTime" : "2016-07-26T13:11:02.000Z",
  "country" : "USA",
  "secondaryEmail" : "hughjack@zylker.com",
  "city" : "Texas",
  "description" : "first priority contact",
  "language" : "English",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "photoURL" : null,
  "twitter" : "Hugh jack",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : "North street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "Austin",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "jack@zylker.com",
  "zip" : "123902",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : "hugh jack",
  "mobile" : "+10 2328829010",
  "accountId" : "1892000000052077",
  "firstName" : "hugh",
  "isAnonymous" : false,
  "phone" : "91020080878",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

Update a contact

This API updates details of an existing contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

object

optional

User-defined fields related to the contact

cf

JSONObject

optional

User-defined fields related to the contact

lastName

string

optional,
max chars : 200

Last name of the contact

firstName

string

optional,
max chars : 40

First name of the contact

facebook

string

optional,
max chars : 100

Facebook ID of the contact

twitter

string

optional,
max chars : 100

Twitter ID of the contact

secondaryEmail

string

optional,
max chars : 100

Secondary email ID of the contact

email

string

optional,
max chars : 255

Email ID of the contact

phone

string

optional,
max chars : 50

Phone number of the contact

mobile

string

optional,
max chars : 50

Mobile number of the contact

city

string

optional,
max chars : 100

Contact's city of residence

country

string

optional,
max chars : 100

Contact's country of residence

state

string

optional,
max chars : 100

Contact's state of residence

street

string

optional,
max chars : 250

Contact's address

zip

string

optional,
max chars : 30

Zip code

description

string

optional,
max chars : 65535

Contact description

title

string

optional,
max chars : 100

Contact title

type

string

optional,
max chars : 120

Contact type

ownerId

long

optional

ID of the user who creates the contact

accountId
see documentation

long

optional

Account to which the contact is mapped

language

string

optional,
max chars : 255

Language preference to set for the Contact

PATCH /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/1892000001128052
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "zip" : "123902",
  "lastName" : "john"
}'

Response Example

{
  "lastName" : "john",
  "modifiedTime" : "2016-07-26T13:11:02.000Z",
  "country" : "USA",
  "secondaryEmail" : "stephen@zylker.com",
  "city" : "Texas",
  "description" : "first priority contact",
  "language" : "English",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "photoURL" : null,
  "twitter" : "stephen john",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : "East street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "Austin",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "stephent@zylker.com",
  "zip" : "123902",
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : "Steve john",
  "mobile" : "+129737289298",
  "accountId" : "1892000000052077",
  "firstName" : "Stephen",
  "isAnonymous" : "false",
  "phone" : "8981901921",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "isSpam" : false
}

Delete Contacts

This API moves the contacts specified to the Recycle Bin.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
contactIds

list

required

IDs of the contacts to move to the Recycle Bin

POST /api/v1/contacts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactIds" : [ "2000032002145" ]
}'

Response Example

204

Delete spam contacts

This API deletes the given spam contacts

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
contactIds

list

required

IDs of the spam contacts

POST /api/v1/contacts/deleteSpam

OAuth Scope

Desk.contacts.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/deleteSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactIds" : [ "1892000000004507", "1892000000004508" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000004507",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000004508",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422",
      "errorJson" : { }
    }
  } ]
}

Get Contact Profiles

This api fetches the list of profiles of this contact from various channels.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

list

optional

Additional information related to the profile's channel. Values allowed are: source

GET /api/v1/contacts/{contact_id}/profiles

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/18289300000002/profiles
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : "https://www.youtube.com/user/iwe3in2/photo",
    "displayName" : "Jade Vlogs",
    "name" : "Jade Zylker",
    "channel" : "YOUTUBE",
    "id" : "3923923923",
    "source" : {
      "appName" : "Youtube Sync App",
      "permalink" : "https://www.examplechannel.com/apps/redirect.php?entity=profile&id=3290dweiod",
      "appPhotoURL" : "https://desk.zoho.com/api/v1/channels/youtube/photo?orgId=666236571"
    }
  }, {
    "photoURL" : "https://www.intagram.com/johninsta/photo",
    "displayName" : "John Insta",
    "name" : "John Zylker",
    "channel" : "INSTAGRAM",
    "id" : "3923923924",
    "source" : {
      "appName" : "Instagram Syncing App",
      "permalink" : "https://www.examplechannel.com/apps/redirect.php?entity=profile&id=3290dweiod",
      "appPhotoURL" : "https://desk.zoho.com/api/v1/channels/instagram/photo?orgId=666236571"
    }
  } ]
}

Update many contacts

This API updates multiple contacts at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/contacts/updateMany

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "mobile",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "8508569875"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

List Contacts By Ids

This API lists details of specific contacts, based on the IDs passed in the request.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
ids

long

required

List of Contact Ids (separated by comma) which must be fetched. The maximum number of IDs allowed is 20.

GET /api/v1/contacts/contactsByIds

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/contactsByIds?ids=1892000000772001,1892000000772003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "mobile" : "+91 8508569683",
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : false,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "mobile" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : false,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : false,
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "isSpam" : false,
    "email" : "jade@zylker.com"
  } ]
}

List tickets by contact

This API lists tickets received from a specific contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/contacts/{contact_id}/tickets

OAuth Scope

Desk.search.READ , Desk.tickets.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/18944000000421011/tickets?include=departments,team,assignee
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zylker.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "accountId" : "189200000005345",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "status" : "Open"
  } ]
}

List products by contact

This API lists products associated for a specific contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

From index

limit

integer

optional,
range : 1-100

Number of products to fetch

departmentId
see documentation

long

optional

Department from which the products need to be queried

GET /api/v1/contacts/{contact_id}/products

OAuth Scope

Desk.products.READ , Desk.settings.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000009277/products
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "unitPrice" : "0.0",
    "productCode" : null,
    "id" : "4000000012009",
    "productName" : "Dell"
  } ]
}

Get contacts count

This API displays the count for the number of contacts in a custom view

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

Custom view ID

startsWith

String

optional

Displays the number of contacts whose first name or last name begins with the letter you specify. Displays the total number of contacts if you do not specify a letter.

GET api/v1/contacts/count

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/count?viewId=4000227563021&startsWith=A
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

Get contact statistics

This API fetches the overall statistics of an contact.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the statistics must be fetched. If you do not pass this parameter in the API request, statistics from all permitted departments will be fetched.

GET /api/v1/contacts/{contact_id}/statistics

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000227563022/statistics
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "firstResponseTime" : "120000",
  "openTickets" : "11",
  "responseTime" : "13150000",
  "spamTickets" : "0",
  "totalTickets" : "36",
  "customerHappiness" : {
    "badCount" : "50",
    "goodCount" : "0",
    "okCount" : "50"
  },
  "closedTickets" : "23",
  "resolutionTime" : "0",
  "channelWiseCount" : {
    "Web" : "12",
    "Forums" : "14",
    "Chat" : "10"
  },
  "onholdTickets" : "2",
  "escalatedTickets" : "0",
  "overdueTickets" : "0"
}

Merge Contacts

This API merges two or more contacts

Note:
Though portal users (users who signed up via the help center) are saved as contacts in the help desk, their records cannot be merged with other records/contacts.

Credit: 30 credits/call

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the contacts to merge

source

object

optional

JSON object containing contact details, where each contact is identified by a unique ID.
The attributes in the object provide information based on the specified contact ID

POST /api/v1/contacts/{contact_id}/merge

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/1892000000042032/merge
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "4000000018011", "4000000018021" ],
  "source" : {
    "zip" : "4000000018011",
    "lastName" : "4000000018011",
    "country" : "4000000018011",
    "secondaryEmail" : "4000000018011",
    "cf" : {
      "cf_permanentaddress" : 1892220000042001
    },
    "city" : "4000000018011",
    "facebook" : "4000000018011",
    "mobile" : "4000000018011",
    "description" : "4000000018011",
    "language" : "4000000018011",
    "type" : "4000000018011",
    "title" : "4000000018011",
    "firstName" : "4000000018011",
    "accountId" : "4000000018011",
    "twitter" : "4000000018011",
    "phone" : "4000000018011",
    "street" : "4000000018011",
    "email" : "4000000018011"
  }
}'

Response Example

{
  "lastName" : "Lawrence",
  "modifiedTime" : "2016-05-04T09:57:17.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "description" : null,
  "language" : "English",
  "ownerId" : "1892000000042001",
  "type" : null,
  "title" : null,
  "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
  "twitter" : null,
  "isDeleted" : false,
  "street" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "contacts_leads"
  },
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "state" : null,
  "id" : "1892000000042032",
  "email" : "lawrence@zylker.com",
  "zip" : null,
  "cf" : {
    "cf_permanentaddress" : null,
    "cf_lastcontactedon" : null
  },
  "isFollowing" : "true",
  "facebook" : null,
  "mobile" : null,
  "accountId" : "1892000000975382",
  "firstName" : "Jennifer",
  "isAnonymous" : false,
  "phone" : "1 888 900 9646",
  "isSpam" : false
}

Mark contact as spam

This API marks contacts as spam.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

ID(s) of the contact(s) that must be marked or unmarked as spam

isSpam

boolean

required

Key that marks or unmarks a single contact or multiple contacts as spam

handleExistingTickets

boolean

optional

Key that marks or unmarks tickets from the contact(s) as spam

POST /api/v1/contacts/markSpam

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/markSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "handleExistingTickets" : "true",
  "ids" : [ "1000000030065", "1000000030068" ],
  "isSpam" : "true"
}'

Response Example

{
  "results" : [ {
    "success" : false,
    "id" : "1000000030068",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : true,
    "id" : "1000000030063",
    "errors" : null
  } ]
}

Associate products with a contact

This API associates products with a contact. Only a maximum of 10 products can be associated with a contact through a single API request.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the resources to associate

departmentId
see documentation

long

optional

ID of the department containing the products

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/contacts/{contact_id}/associateProducts

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/7000000027081/associateProducts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "7000000062800",
  "ids" : [ "7000000027223", "7000000043968" ],
  "associate" : true
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  }, {
    "success" : false,
    "id" : "7000000043968",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Get contact history

This API fetches the ticket history of a contact.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the history details must be fetched

agentId

long

optional

Key that filters ticket activities performed by a particular agent

from

Integer

optional

Index number, starting from which the history details must be fetched

limit

Integer

optional,
range : 1-100

Number of history details to fetch

GET api/v1/contacts/{contact_id}/history

OAuth Scope

Desk.tickets.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000012934/history
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "156648",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "dueDate" : null,
    "departmentId" : "4000000013957",
    "priority" : null,
    "recipients" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012999",
    "eventTime" : "2019-09-19T09:37:11.000Z",
    "operation" : "Comment_Updated",
    "ticketId" : "4000000012999",
    "status" : "Open"
  }, {
    "ticketNumber" : "125289",
    "statusType" : "Open",
    "subject" : "Ticket subject here.",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "dueDate" : null,
    "departmentId" : "4000000013701",
    "priority" : null,
    "recipients" : [ "ragavan@zylker.com", "kannan@zylker.com", "thamizharasi@zylker.com" ],
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012807",
    "eventTime" : "2019-07-22T16:27:20.000Z",
    "operation" : "Mail_Response_Forward",
    "ticketId" : "4000000012807",
    "status" : "Open"
  } ]
}

Invite multiple contacts to help center

This API helps invite multiple contacts as end-users to your help center.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
contactIds

list

required

IDs of the contacts to invite

helpCenterId

long

required

ID of the help center to which you want to add the contacts

POST api/v1/contacts/inviteAsEndUser

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/inviteAsEndUser
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "helpCenterId" : "4000000021302",
  "contactIds" : [ "4000000012902", "40000000212902", "40000002129122" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Invite contact to help center

This API helps invite a particular contact as an end-user to your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
helpCenterId

long

required

ID of the help center to which you want to add the contact

POST api/v1/contacts/{contact_id}/inviteAsEndUser

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/40000000212902/inviteAsEndUser
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "helpCenterId" : "4000000021302"
}'

Response Example

204

Delete contact photo

This API deletes the display picture of a contact.

Credit: 1 credit/call

DELETE api/v1/contacts/{contact_id}/photo

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/40000000212902/photo
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get status of contact in help centers

This API fetches a particular contact's activation status in all the help centers they are part of.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
helpCenterId

Long

optional

To get specific helpcenter info

GET api/v1/contacts/{contact_id}/helpCenters

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/40000000212902/helpcenters
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "helpCenter" : {
      "name" : "Zoho",
      "id" : "4000000016038",
      "url" : "https://help.zoho.com/portal/zoho",
      "status" : "ACTIVE"
    },
    "userStatus" : "ACTIVE",
    "userId" : "4000000023791"
  }, {
    "helpCenter" : {
      "name" : "CRM",
      "id" : "4000010498403",
      "url" : "https://help.zoho.com/portal/crm",
      "status" : "ACTIVE"
    },
    "userStatus" : "ACTIVE",
    "userId" : "4000000023791"
  } ]
}

List accounts of contact

This API lists the accounts associated with a particular contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

optional

Index number, starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to list

startsWith

String

optional

Letter with which the names of the accounts must start

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: accountName or createdTime or mappingType . The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/contacts/{contact_id}/accounts

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000009277/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "website" : "www.zoho.com",
    "accountName" : "ZOHO",
    "phone" : "8822120911",
    "mappingInfo" : {
      "mappingId" : 1892000000052072,
      "mappingType" : "PRIMARY",
      "isAccountTicketsViewable" : true
    },
    "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"
  } ]
}

Associate accounts with contact

This API associates multiple accounts with a particular contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
data

list

optional

Details of the accounts to associate with the contact

POST api/v1/contacts/{contact_id}/associateAccounts

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/7000000027081/associateAccounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "data" : [ {
    "id" : 7000000027223,
    "isAccountTicketsViewable" : true
  }, {
    "id" : 7000000043968,
    "isAccountTicketsViewable" : false
  } ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  }, {
    "success" : null,
    "id" : "7000000043968",
    "errors" : {
      "errorMessage" : "This is a deleted account. You can restore the entry from the Recycle Bin of your Zoho Desk portal.",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Dissociate accounts from contact

This API dissociates multiple accounts from a particular contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the accounts to dissociate from the contact

POST api/v1/contacts/{contact_id}/dissociateAccounts

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/7000000027081/dissociateAccounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "7000000027223", "7000000043968" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  } ]
}

Dissociate account from contact

This API dissociates a particular account from a contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
option

String

optional

Processing option to apply to the tickets after dissociating the account from the contact. Values allowed are: Move Tickets to Contact, Move Tickets To Account, Delete Tickets, and Maintain Same Relationship (default value).

optionValue

long

optional

ID of the account or contact to which the tickets must be moved

PATCH api/v1/contacts/{contact_id}/accounts/{account_id}/dissociate

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/7000000027081/accounts/7000000027223/dissociate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "optionValue" : 7000000027226,
  "option" : "Move Tickets To Contact"
}'

Response Example

204

Approve contact for help center

This API helps approve a particular contact as an end-user to your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
helpCenterIds

list

required

IDs of the help center in which you want to approve/reject the contacts

POST /api/v1/contacts/{contact_id}/approveEndUserInvite

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/40000000212902/approveEndUserInvite
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "helpCenterIds" : [ "4000000021302" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000021302",
    "errors" : null
  } ]
}

Reject contact for help center

This API helps reject a particular contact from being added as an end-user to your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
helpCenterIds

list

required

IDs of the help center in which you want to approve/reject the contacts

POST /api/v1/contacts/{contact_id}/rejectEndUserInvite

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/40000000212902/rejectEndUserInvite
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "helpCenterIds" : [ "4000000021302" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000021302",
    "errors" : null
  } ]
}

Accounts

Account refers to customer organizations that use your products or services. An account can have multiple contacts.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the account

customFields 

deprecated

list

User-defined fields associated with the account

cf

JSONObject

User-defined fields associated with the account

accountName

string

Name of the account

email

string

Email ID of the account

website

string

Website of the account

fax

string

Fax number of the account

ownerId

long

ID of account owner

owner

object

Details of the user to whom the account is assigned.

associatedSLAIds

list

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

Industry in which the account operates

city

string

City in which the account is based

country

string

Country in which the account is based

state

string

State in which the account is based

street

string

Address of the account

code

string

Zip code

description

string

A short description of the account

phone

string

Phone number of the account

annualrevenue

double

Annual revenue of the account

createdTime

timestamp

Time of creating the account

modifiedTime

timestamp

Time of modifying the account

isTrashed

boolean

Field that denotes whether the account is in trash

webUrl

string

URL to access the resource

Example

{
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : "www.zylker.com",
  "code" : "4436",
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : "Automation",
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "phone" : "9382991011",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "id" : "3263000000074571",
  "state" : null,
  "fax" : "+1 444 8439 2350",
  "email" : "support@zylker.com"
}


Get Account

This API fetches an account from your help desk portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Allowed values are : owner

GET /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> Account response = account.getAccount( accountId, include );

Response Example

{
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "code" : "3211",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : "Automation",
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "street" : null,
  "annualrevenue" : null,
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : "+1 444 8656 8732",
  "email" : "support@zylker.com",
  "owner" : {
    "firstName" : "Twin",
    "lastName" : "john",
    "id" : "3263000000057001"
  },
  "website" : "www.zylker.com",
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "phone" : "6218129190",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38"
}

List accounts

This API lists a particular number of accounts, based on the limit specified. 

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the accounts must be listed

limit

integer

optional,
range : 1-100

Number of accounts to fetch

viewId

long

optional

ID of the view to apply while fetching the resources

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: accountName or createdTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

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: photoURL, webUrl. Maximum of 30 fields is supported as comma separated values.

GET /api/v1/accounts

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> GetAccountsFilter filter = new GetAccountsFilter.Builder().setViewId(viewId).build(); <br/> List&lt;Account&gt; response = account.getAccounts( from, limit, sortBy, isAscending, filter );

Response Example

{
  "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"
  }, {
    "website" : "1211212",
    "accountName" : "Agent Account",
    "phone" : "11211",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "customerHappiness" : {
      "badPercentage" : "20",
      "okPercentage" : "40",
      "goodPercentage" : "40"
    },
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

Create Account

This API creates an account in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields associated with the account

cf

JSONObject

optional

User-defined fields associated with the account

accountName

string

required,
max chars : 200

Name of the account

email

string

optional,
max chars : 255

Email ID of the account

website

string

optional,
max chars : 120

Website of the account

fax

string

optional,
max chars : 30

Fax number of the account

ownerId

long

optional

ID of account owner

associatedSLAIds

list

optional

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

optional,
max chars : 120

Industry in which the account operates

city

string

optional,
max chars : 100

City in which the account is based

country

string

optional,
max chars : 100

Country in which the account is based

state

string

optional,
max chars : 100

State in which the account is based

street

string

optional,
max chars : 250

Address of the account

code

string

optional,
max chars : 30

Zip code

description

string

optional,
max chars : 65535

A short description of the account

phone

string

optional,
max chars : 30

Phone number of the account

annualrevenue

double

optional

Annual revenue of the account

POST /api/v1/accounts

OAuth Scope

Desk.contacts.CREATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "accountName" : "Zylker",
  "phone" : "98348229382"
}'

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> Account accountObj = new Account();</br> accountObj.setCountry(country);<br/>accountObj.setWebsite(website);<br/>accountObj.setCode(code);<br/>accountObj.setCity(city);<br/>accountObj.setAccountName(accountName);<br/>accountObj.setDescription(description);<br/> Account response = account.createAccount( accountObj );

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "cf" : {
    "cf_contactcount" : null
  },
  "isFollowing" : "true",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : null,
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "phone" : "98348229382",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Update Account

This API updates details of an existing account.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields associated with the account

cf

JSONObject

optional

User-defined fields associated with the account

accountName

string

optional,
max chars : 200

Name of the account

email

string

optional,
max chars : 255

Email ID of the account

website

string

optional,
max chars : 120

Website of the account

fax

string

optional,
max chars : 30

Fax number of the account

ownerId

long

optional

ID of account owner

associatedSLAIds

list

optional

IDs of the SLAs associated with the account. An account can have multiple SLAs, but only one SLA per department can be mapped to it.

industry

string

optional,
max chars : 120

Industry in which the account operates

city

string

optional,
max chars : 100

City in which the account is based

country

string

optional,
max chars : 100

Country in which the account is based

state

string

optional,
max chars : 100

State in which the account is based

street

string

optional,
max chars : 250

Address of the account

code

string

optional,
max chars : 30

Zip code

description

string

optional,
max chars : 65535

A short description of the account

phone

string

optional,
max chars : 30

Phone number of the account

annualrevenue

double

optional

Annual revenue of the account

PATCH /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL
  • Java

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/3263000000074571
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "accountName" : "Zylker Agents",
  "phone" : "82301023900123"
}'

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> Account accountObj = new Account();</br> accountObj.setCountry(country);<br/>accountObj.setWebsite(website);<br/>accountObj.setCode(code);<br/>accountObj.setCity(city);<br/>accountObj.setAccountName(accountName);<br/>accountObj.setDescription(description);<br/> Account response = account.updateAccount( accountId, accountObj );

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "accountName" : "Zylker Agents",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : null,
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "phone" : "82301023900123",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Delete Accounts

This API moves the accounts specified to the Recycle Bin.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
accountIds

list

required

IDs of the accounts to move to the Recycle Bin

POST /api/v1/accounts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/accounts/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "accountIds" : [ "2000032003232" ]
}'

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> boolean response = account.moveToTrash( accountIds );

Response Example

204

Get contract

Getting contracts of an Account

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

From index,DEFAULT 1

limit

integer

optional,
range : 1-50

Number of contracts to fetch, Ranges from 1-50, DEFAULT 50

departmentId

long

optional

ID of the department from which the contracts must be fetched

contractStatus

string

optional,
max chars : 100

Contract Status,Indicates the Current Status of the Contract, Values are ACTIVE, EXPIRED, FUTURE

GET /api/v1/accounts/{account_id}/contracts

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571/contracts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "slaName" : "Priority-based SLAs",
    "endDate" : "2016-07-16",
    "slaGroupId" : "4000000007069",
    "departmentId" : "4000000007043",
    "contractId" : "4000000032003",
    "contractNumber" : "1212",
    "description" : "contract for all desk account",
    "contractName" : "Contract for desk account",
    "ownerId" : "4000000008692",
    "startDate" : "2016-06-16"
  } ]
}

List all contracts count

This API lists the number of contracts made with the account.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

Custom view Id

departmentId
see documentation

String

required

Mandatory param to fetch the count of the contracts for a given ID of a department. You can also provide department as allDepartment to fetch the count of the contracts from all the departments

ownerId

long

optional

Displays the number of contracts of only a particular owner

GET api/v1/contracts/count

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contracts/count?viewId=4000227563021&departmentId=4000000007096&ownerId=4000227563909
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

List all accounts count

Get accounts count

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

Custom view ID

startsWith

String

optional

Displays the number of accounts whose first name or last name begins with the letter you specify. Displays the total number of accounts if you do not specify a letter.

GET api/v1/accounts/count

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/count?viewId=4000227563021&startsWith=A
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

List Associated contacts

This API lists the contacts associated with an account

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

optional

From index

limit

integer

optional,
range : 1-100

No. of contacts to fetch

sortBy

string

optional,
max chars : 100

Parameter that sorts contacts by one of these attributes:
firstName,

lastName,

fullName,

phone,

email,

createdTime,

modifiedTime

isSpam

boolean

optional,
default : false

Filters Spam contacts

GET api/v1/accounts/{accounts_id}/contacts?from={from}&limit={limit}&sortBy={sortingField}

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000008784/contacts?from=0&limit=20&sortBy=-fullName
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> GetContactsUnderAccountFilter filter = new GetContactsUnderAccountFilter.Builder().setIsSpam(isSpam).build(); <br/> List&lt;Contact&gt; response = account.getContactsUnderAccount( accountId, from, limit, sortBy, isAscending, filter );

Response Example

{
  "data" : [ {
    "lastName" : "Lawrence",
    "secondaryEmail" : null,
    "mappingInfo" : {
      "mappingId" : "18026000003237019",
      "mappingType" : "PRIMARY",
      "isAccountTicketsViewable" : true
    },
    "mobile" : "+91 8508569683",
    "type" : null,
    "ownerId" : "4000000008734",
    "firstName" : null,
    "accountId" : "4000000008784",
    "photoURL" : null,
    "isAnonymous" : true,
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "isEndUser" : "false",
    "zohoCRMContact" : {
      "id" : "5000000014010",
      "type" : "contacts_leads"
    },
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "id" : "4000000008786",
    "isSpam" : false,
    "email" : "support@zylker.com"
  } ]
}

List tickets by account

This API lists tickets received from a specific account.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

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 a comma in the API request.

GET /api/v1/accounts/{account_id}/tickets

OAuth Scope

Desk.tickets.READ , Desk.search.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/accounts/18944000000421015/tickets?include=assignee,departments,team,isRead
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> GetTicketsByAccountFilter filter = new GetTicketsByAccountFilter.Builder().setDepartmentId(departmentId).build(); <br/> List&lt;Ticket&gt; response = account.getTicketsByAccount( accountId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8845678909",
      "id" : "18944000000421011",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zylker.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "accountId" : "189200000005345",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "status" : "Open"
  } ]
}

List products by account

This API lists products associated for a specific account.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

From index

limit

integer

optional,
range : 1-100

Number of products to fetch

departmentId
see documentation

long

optional

Department from which the products need to be queried

GET /api/v1/accounts/{account_id}/products

OAuth Scope

Desk.products.READ , Desk.settings.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000026005/products
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "unitPrice" : "0.0",
    "productCode" : null,
    "id" : "4000000012009",
    "productName" : "Dell"
  } ]
}

Merge Accounts

This API merges two or more accounts.

Credit: 30 credits/call

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the accounts to merge

source

object

optional

JSON object containing details of the account

POST /api/v1/accounts/{account_id}/merge

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000008749/merge
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "4000000018011", "4000000018033" ],
  "source" : {
    "country" : "4000000018011",
    "website" : "4000000018011",
    "code" : "4000000018011",
    "cf" : {
      "cf_contactcount" : 1892220000042001
    },
    "city" : "4000000018011",
    "description" : "4000000018011",
    "industry" : "4000000018011",
    "phone" : "4000000018011",
    "annualrevenue" : "4000000018011",
    "street" : "4000000018011",
    "state" : "4000000018011",
    "fax" : "4000000018011",
    "email" : "4000000018011"
  }
}'

Response Example

{
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : "www.zylker.com",
  "code" : "3211",
  "cf" : {
    "cf_contactcount" : "1"
  },
  "isFollowing" : "true",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "description" : null,
  "industry" : "Automation",
  "zohoCRMAccount" : {
    "id" : "32754000000537001"
  },
  "ownerId" : "3263000000057001",
  "phone" : "6218129190",
  "street" : null,
  "annualrevenue" : null,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : "+1 444 8656 8732",
  "email" : "support@zylker.com"
}

Associate products with an account

This API associates products with an account. Only a maximum of 10 products can be associated with an account through a single API request.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the resources to associate

departmentId
see documentation

long

optional

ID of the department containing the products

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/accounts/{account_id}/associateProducts

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/7000000043860/associateProducts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "7000000062800",
  "ids" : [ "7000000027223", "7000000043968" ],
  "associate" : true
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "7000000027223",
    "errors" : null
  }, {
    "success" : false,
    "id" : "7000000043968",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Update many accounts

This API updates multiple accounts at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/accounts/updateMany

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "phone",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "8508569875"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Get account history

This API fetches the ticket history of an account.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the history details must be fetched

agentId

long

optional

Key that filters ticket activities performed by a particular agent

contactId

long

optional

Key that filters ticket activities related to a particular contact

from

Integer

optional

Index number, starting from which the history details must be fetched

limit

Integer

optional,
range : 1-100

Number of history details to fetch

GET api/v1/accounts/{account_id}/history

OAuth Scope

Desk.tickets.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000012234/history
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "156648",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "dueDate" : null,
    "departmentId" : "4000000013957",
    "priority" : null,
    "recipients" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012999",
    "eventTime" : "2019-09-19T09:37:11.000Z",
    "operation" : "Comment_Updated",
    "ticketId" : "4000000012999",
    "status" : "Open"
  }, {
    "ticketNumber" : "125289",
    "statusType" : "Open",
    "subject" : "Ticket subject here.",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000012902/photo",
      "firstName" : "Admin",
      "lastName" : "Admin",
      "id" : "4000000012902",
      "type" : "AGENT",
      "email" : "saranraj@zylker.com"
    },
    "dueDate" : null,
    "departmentId" : "4000000013758",
    "priority" : null,
    "recipients" : [ "ragavan@zylker.com", "kannan@zylker.com", "thamizharasi@zylker.com" ],
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/4000000012807",
    "eventTime" : "2019-07-22T16:27:20.000Z",
    "operation" : "Mail_Response_Forward",
    "ticketId" : "4000000012807",
    "status" : "Open"
  } ]
}

Get account statistics

This API fetches the overall statistics of an account.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the statistics must be fetched. If you do not pass this parameter in the API request, statistics from all permitted departments will be fetched.

GET /api/v1/accounts/([0-9]+)/statistics

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/([0-9]+)/statistics
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "firstResponseTime" : "120000",
  "openTickets" : "11",
  "responseTime" : "13150000",
  "spamTickets" : "0",
  "totalTickets" : "31",
  "customerHappiness" : {
    "badCount" : "50",
    "goodCount" : "0",
    "okCount" : "50"
  },
  "closedTickets" : "20",
  "resolutionTime" : "0",
  "channelWiseCount" : {
    "Web" : "15",
    "Forums" : "15",
    "Chat" : "1"
  },
  "onholdTickets" : "0",
  "escalatedTickets" : "0",
  "overdueTickets" : "0"
}

List account SLAs

This API lists a particular number of SLAs associated with an account, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

optional,
range : >=0

Index number, starting from which the SLAs must be fetched

limit

integer

optional,
range : 1-100

Number of SLAs to list

departmentId

long

optional

ID of the department from which the SLAs must be fetched. If you do not pass this parameter in the API request, SLAs from all permitted departments will be listed.

status

String

optional

Activation status of the SLAs. Values allowed are: ACTIVE and INACTIVE

GET /api/v1/accounts/{account_id}/sla

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571/sla
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "slaName" : "Priority-based SLAs",
    "id" : "45794000000419372",
    "isActive" : true,
    "department" : {
      "name" : "Tesla",
      "id" : "45794000000418059"
    }
  }, {
    "slaName" : "SLA",
    "id" : "45794000000570017",
    "isActive" : true,
    "department" : {
      "name" : "BMW",
      "id" : "45794000000006907"
    }
  }, {
    "slaName" : "Silver SLAs",
    "id" : "45794000000587464",
    "isActive" : true,
    "department" : {
      "name" : "Jaguar",
      "id" : "45794000000586067"
    }
  } ]
}

Associate or dissociate SLA from account

This API associates or dissociates an SLA from an account. 

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
associate

boolean

required

Key that specifies if the SLA must be associated with the account or not. true is for associating and false is for dissociating.

POST /api/v1/accounts/{account_id}/sla/{sla_id}

OAuth Scope

Desk.contacts.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/3263000000074571/sla/32630000000570017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "associate" : true
}'

Response Example

204

Account Contact Mapping

Account-Contact mapping refers to the connection between a contact and the different accounts they are associated with.

Example

{
  "mappingId" : "4000000023057",
  "accountId" : "4000000022101",
  "contactId" : "4000000020714",
  "mappingType" : "PRIMARY",
  "isAccountTicketsViewable" : true
}


Update association info

This API updates the details of an account-contact mapping.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isAccountTicketsViewable

Boolean

optional

Key that specifies whether the contact can access all tickets related to the account

mappingType

String

optional

Type of mapping connection between the contact and the account. Value allowed is PRIMARY, which sets the account as the primary account of the contact.

PATCH /api/v1/accountContactMapping/{mapping_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/accountContactMapping/4000000023057
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "mappingType" : "PRIMARY",
  "isAccountTicketsViewable" : true
}'

Response Example

{
  "mappingId" : "4000000023057",
  "accountId" : "4000000022101",
  "contactId" : "4000000020714",
  "mappingType" : "PRIMARY",
  "isAccountTicketsViewable" : false
}

Tasks

Tasks are work activities assigned to agents. It is not mandatory for tasks to be related to only ticket resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the task

customFields 

deprecated

list

User-defined fields related to the task

cf

list

User-defined fields related to the task

departmentId
see documentation

long

ID of the department in which the task must be created

subject

string

Subject of the task

ticketId
see documentation

long

ID of the ticket with which the task must be associated

dueDate

timestamp

Due date for completing the task

ownerId

long

ID of the user to whom the task is assigned

category

string

Category of the task

status

string

Status of task completion

priority

string

Priority of the task

description

string

Description of the task

createdTime

timestamp

Time when the task was created

modifiedTime

timestamp

Time when the task was modified

creatorId

string

ID of the user who created the task

ticket

Ticket

Ticket associated with the task

contactId

long

ID of the contact associated with the task

teamId

long

ID of the team to which the task is assigned

reminder

JSONArray

Details of the reminder set for the task

Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "cf" : { },
  "reminder" : [ {
    "alertType" : [ "EMAIL" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T10:32:11.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T16:32:11.000Z"
  }, {
    "relativeReminderInMin" : "10",
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "RELATIVE"
  } ],
  "subject" : "New Task",
  "completedTime" : null,
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-29T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "Normal",
  "createdTime" : "2016-07-26T17:32:11.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000018001",
  "isSpam" : false,
  "category" : null,
  "ticketId" : "3000000008753",
  "status" : "Not Started"
}


Get task

This API fetches a task from your help desk portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams,creator.

GET /api/v1/tasks/{task_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/5000000074002?include=assignee,tickets,contacts,teams,creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2019-04-08T07:26:26.000Z",
  "subject" : "New gadget replacement with latest OS",
  "completedTime" : null,
  "departmentId" : "5000000012710",
  "dueDate" : "2019-04-25T16:52:11.000Z",
  "creatorId" : "5000000015911",
  "description" : "Latest OS Version 32.9.4 ",
  "ownerId" : "5000000015911",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false
  },
  "createdTime" : "2019-04-08T07:26:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000074002",
  "creator" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "emailId" : "zylker@zylker.com",
    "id" : "5000000015911"
  },
  "cf" : { },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : "3691000006805021",
    "id" : "5000000016294",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open"
  },
  "reminder" : [ {
    "alertType" : [ "EMAIL", "SMS", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-24T04:52:13.000Z"
  } ],
  "contactId" : "5000000016252",
  "team" : {
    "name" : "Desk Team",
    "id" : "3691000006805021",
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
  },
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e4d4dad33a9adf3649",
  "teamId" : "3691000006805021",
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "category" : null,
  "ticketId" : "5000000016294",
  "status" : "Deferred"
}

List tasks

This API fetches a particular number of tasks, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams,projects.

from

integer

optional

Index number, starting from which the tasks must be fetched

limit

integer

optional,
range : 1-100

Number of tasks to list

departmentId
see documentation

long

optional

ID of the department from which the tasks must be fetched

departmentIds
see documentation

long

optional

Departments from which the tasks need to be queried

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

dueDate

string

optional,
max chars : 100

Due date for completing the task. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

isCompleted

boolean

optional

Key that denotes whether the task is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the tasks by a specific attribute: dueDate or createdTime.The default sorting order is ascending. A - prefix denotes a descending order of sorting.

GET /api/v1/tasks

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks?departmentId=5000000012710&include=teams,tickets,contacts,assignee
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : null,
    "contactId" : null,
    "subject" : "Iphone charger replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000067003",
    "priority" : "Normal",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/d4c0a5dce55dcf20279262cd8594cd0d",
    "contact" : null,
    "createdTime" : "2019-04-30T14:21:50.000Z",
    "startTime" : "1970-01-01T00:00:00.000Z",
    "id" : "5000000209940",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "36",
      "photoURL" : null,
      "id" : "5000000067003"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : null,
    "status" : "Not Started",
    "direction" : "inbound"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : null,
    "subject" : "Tempered glass replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e46474bbeb6432292e",
    "teamId" : "3691000006805021",
    "contact" : null,
    "createdTime" : "2019-04-09T04:37:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000075033",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred12546",
    "direction" : "inbound"
  } ]
}

Create task

This API creates a task in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the task

cf

list

optional

User-defined fields related to the task

departmentId
see documentation

long

required

ID of the department in which the task must be created

subject

string

required,
max chars : 300

Subject of the task

ticketId
see documentation

long

optional

ID of the ticket with which the task must be associated

dueDate

timestamp

optional

Due date for completing the task

ownerId

long

optional

ID of the user to whom the task is assigned

category

string

optional,
max chars : 120

Category of the task

status

string

optional,
max chars : 120

Status of task completion

priority

string

optional,
max chars : 120

Priority of the task

description

string

optional,
max chars : 65535

Description of the task

contactId

long

optional

ID of the contact associated with the task

teamId

long

optional

ID of the team to which the task is assigned

reminder

JSONArray

optional

Details of the reminder set for the task

POST /api/v1/tasks

OAuth Scope

Desk.activities.CREATE , Desk.activities.tasks.CREATE , Desk.tasks.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "priority" : "High",
  "category" : null,
  "status" : "In Progress"
}'

Response Example

{
  "modifiedTime" : "2016-07-14T09:14:41.000Z",
  "cf" : { },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Update task

This API helps update the details of a task.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the task

cf

list

optional

User-defined fields related to the task

departmentId
see documentation

long

optional

ID of the department in which the task must be created

subject

string

optional,
max chars : 300

Subject of the task

ticketId
see documentation

long

optional

ID of the ticket with which the task must be associated

dueDate

timestamp

optional

Due date for completing the task

ownerId

long

optional

ID of the user to whom the task is assigned

category

string

optional,
max chars : 120

Category of the task

status

string

optional,
max chars : 120

Status of task completion

priority

string

optional,
max chars : 120

Priority of the task

description

string

optional,
max chars : 65535

Description of the task

contactId

long

optional

ID of the contact associated with the task

teamId

long

optional

ID of the team to which the task is assigned

reminder

JSONArray

optional

Details of the reminder set for the task

PATCH /api/v1/tasks/{task_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/3000000054002
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "category" : null,
  "priority" : "High",
  "status" : "In Progress"
}'

Response Example

{
  "modifiedTime" : "2016-07-14T09:14:41.000Z",
  "cf" : { },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Delete tasks

This API moves task entries to the Recycle Bin of your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
entityIds

list

required

IDs of the activities to delete

POST /api/v1/tasks/moveToTrash

OAuth Scope

Desk.activities.DELETE , Desk.activities.tasks.DELETE , Desk.tasks.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "entityIds" : [ "2000032003232" ]
}'

Response Example

204

Delete spam tasks

This API deletes the given spam tasks

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
taskIds

list

required

IDs of the spam tasks

POST /api/v1/tasks/deleteSpam

OAuth Scope

Desk.activities.DELETE , Desk.activities.tasks.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/deleteSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "taskIds" : [ "1892000000012307", "1892000000012308" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000012307",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000012308",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422",
      "errorJson" : { }
    }
  } ]
}

List tasks by ticket

This API lists all tasks associated with a particular ticket.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the tasks must be fetched

isCompleted

boolean

optional

Key that denotes whether the task is completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam tasks or not

limit

integer

optional,
range : 1-100

Number of tasks to list

sortBy

string

optional,
max chars : 100

Key that sorts the tasks by a specific attribute: dueDate or createdTime.The default sorting order is ascending. A - prefix denotes a descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Additional information related to the task. Values allowed are: contacts, assignee,tickets,teams,projects.

GET /api/v1/tickets/{ticket_id}/tasks

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tickets.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/tasks?include=assignee,tickets,contacts,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "subject" : "New gadget replacement with latest OS",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4d4dad33a9adf3649",
    "isCommented" : false,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-08T07:26:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000074002",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "priority" : "High",
    "layoutId" : "5000000013466",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e4d4dad33a9adf3649",
    "teamId" : "3691000006805021",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred"
  }, {
    "subject" : "Tempered glass replacement",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-25T16:52:11.000Z",
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e46474bbeb6432292e",
    "isCommented" : false,
    "contact" : null,
    "createdTime" : "2019-04-09T04:37:26.000Z",
    "startTime" : "2019-04-25T16:52:11.000Z",
    "id" : "5000000075033",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : null,
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013466",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e46474bbeb6432292e",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "status" : "Deferred12546"
  } ]
}

List all tasks count

This API returns the number of tasks in your help desk.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

ID of the view to apply while fetching the resources

departmentId
see documentation

long

required

ID of the department from which the task count must be fetched

assignee

string

optional,
max chars : 100

Key that filters tasks by assignee. A valid assigneeId must be passed for this parameter. Multiple assigneeIds can be passed as comma-separated values.

dueDate

string

optional,
max chars : 100

Filter by task duedate. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today. You can include both values by separating them with a comma

GET /api/v1/tasks/count

OAuth Scope

Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/count?viewId=5000000007880&departmentId=5000000007069
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

Update many tasks

This API updates multiple tasks at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/tasks/updateMany

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "mobile",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "8508569875"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Empty spam tasks

This API deletes all spam tasks.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department to which the activities belong

POST /api/v1/tasks/emptySpam

OAuth Scope

Desk.activities.DELETE , Desk.activities.tasks.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/emptySpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "4000000025121"
}'

Response Example

202

Products

Products are the goods/services your organization sells.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the product

departmentIds
see documentation

list

IDs of departments associated with the product

ownerId

long

ID of user to whom the product is assigned

productName

string

Name of the product

productCode

string

Reference code of the product

productCategory

string

Category to which the product belongs

manufacturer

string

Organization that manufactures the product

unitPrice

double

Price of the product

customFields 

deprecated

list

User-defined fields related to the product

cf

list

User-defined fields related to the product

createdBy

long

User who added the product to the help desk portal

modifiedBy

long

User who modified the details of the product

createdTime

timestamp

Time of adding the product to the help desk portal

modifiedTime

timestamp

Time of modifying product details

description

string

Description of the product

Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2016-06-27T06:33:19.000Z",
  "productCode" : "E7450",
  "createdBy" : "4000000008692",
  "module" : "products",
  "createdTime" : "2016-06-27T06:33:19.000Z",
  "description" : "New Product",
  "modifiedBy" : "4000000008692",
  "id" : "4000000013043",
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "productName" : "DELL"
}


Get product

This API fetches a single product from your helpdesk.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/products/{product_id}

OAuth Scope

Desk.products.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/products/6000000124009
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/6000000009050/photo?orgId=581861259",
    "firstName" : "Aaron",
    "lastName" : "Stone",
    "name" : "Aaron Stone",
    "id" : "6000000009050"
  },
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-06-28T13:25:06.000Z",
  "cf" : { },
  "description" : null,
  "departmentIds" : [ "6000000009450", "6000000009380", "6000000009230" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009",
  "departments" : [ {
    "name" : "Associated Department 1",
    "id" : "6000000009450"
  }, {
    "name" : "Associated Department 2",
    "id" : "6000000009380"
  }, {
    "name" : "Associated Department 3",
    "id" : "6000000009230"
  } ]
}

List products

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

Query Params

Param Name
Data Type
Description
viewId

long

optional

ID of the view to apply while fetching the products

from

integer

optional

Index number, starting from which the products must be fetched

limit

integer

optional,
range : 1-100

No. of products to fetch

departmentId

long

optional

ID 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.

ownerId

long

optional

ID of user to whom the product is assigned

sortBy

string

optional,
max chars : 100

Sort by a specific attribute : productName, productCode, unitPrice, createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

fields

string

optional,
max chars : 100

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.

include
see documentation

list

optional

Secondary information related to the contact.Value supported is owner.

GET /api/v1/products

OAuth Scope

Desk.products.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/products?departmentIds=6000000007239,6000000029263
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121033",
    "productName" : "HTC"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121037",
    "productName" : "Dell"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000145024",
    "productName" : "Lenovo"
  } ]
}

Create product

This API adds a product to your helpdesk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentIds
see documentation

list

required

IDs of departments associated with the product

ownerId

long

optional

ID of user to whom the product is assigned

productName

string

required,
max chars : 200

Name of the product

productCode

string

optional,
max chars : 200

Reference code of the product

productCategory

string

optional,
max chars : 200

Category to which the product belongs

manufacturer

string

optional,
max chars : 200

Organization that manufactures the product

unitPrice

double

optional

Price of the product

customFields 
deprecated

list

optional

User-defined fields related to the product

cf

list

optional

User-defined fields related to the product

description

string

optional,
max chars : 65535

Description of the product

POST /api/v1/products

OAuth Scope

Desk.products.CREATE , Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/products
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "unitPrice" : "100",
  "productCode" : "12345",
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "productName" : "Dell"
}'

Response Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-07-18T10:46:25.667Z",
  "cf" : { },
  "description" : null,
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-07-18T10:46:25.667Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000164001"
}

List tickets by products

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

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department from which the tickets must be fetched

from

Integer

optional

Index number, starting from which the tickets must be fetched

limit

Integer

optional,
range : 1-100

Number of tickets to fetch

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

dueDate

string

optional,
max chars : 100

Filter by ticket duedate. Values allowed are overdue, tomorrow, currentWeek, currentMonth and today. You can include both values by separating them with a comma

isSpam

boolean

optional,
default : false

Filters Spam tickets

include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/products/{product_id}/tickets

OAuth Scope

Desk.tickets.READ , Desk.settings.READ , Desk.search.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/products/18944000000424033/tickets?include=departments,team,assignee
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "sentiment" : "NEGATIVE",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "onholdTime" : null,
    "language" : "English",
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zylker.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "accountId" : "189200000005345",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "status" : "Open"
  } ]
}

Update product

This API updates details of a product in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentIds
see documentation

list

optional

IDs of departments associated with the product

ownerId

long

optional

ID of user to whom the product is assigned

productName

string

optional,
max chars : 200

Name of the product

productCode

string

optional,
max chars : 200

Reference code of the product

productCategory

string

optional,
max chars : 200

Category to which the product belongs

manufacturer

string

optional,
max chars : 200

Organization that manufactures the product

unitPrice

double

optional

Price of the product

customFields 
deprecated

list

optional

User-defined fields related to the product

cf

list

optional

User-defined fields related to the product

description

string

optional,
max chars : 65535

Description of the product

PATCH /api/v1/products/{product_id}

OAuth Scope

Desk.products.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/products/6000000124009
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentIds" : [ "6000000029263", "6000000125041" ],
  "productName" : "Dell"
}'

Response Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-07-18T10:53:40.787Z",
  "cf" : { },
  "description" : null,
  "departmentIds" : [ "6000000029263", "6000000125041" ],
  "ownerId" : "6000000009050",
  "layoutId" : "6000000002556",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009"
}

Move Products to trash

This API moves products to the Recycle Bin of your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

optional

ID of the department containing the products

productIds

list

required

IDs of the products you want to delete

POST /api/v1/products/moveToTrash

OAuth Scope

Desk.products.DELETE , Desk.settings.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/products/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "productIds" : [ "2000032003232" ],
  "departmentId" : "2000032006800"
}'

Response Example

204

Search for duplicate records

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the products must be fetched

limit

integer

optional,
range : 1-100

No. of products to fetch

productName

string

required,
max chars : 200

Name of the product, used as the keyword for the search

GET /api/v1/products/searchDuplicates

OAuth Scope

Desk.products.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/products/searchDuplicates?productName=Dell
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121033",
    "productName" : "Dell"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121037",
    "productName" : "Dell"
  } ]
}

Associate contacts with a product

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

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the resources to associate

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/products/{product_id}/associateContacts

OAuth Scope

Desk.products.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/products/2000000031001/associateContacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "2000000034031", "2000000034029" ],
  "associate" : true
}'

Response Example

200

Associate accounts with a product

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

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the resources to associate

associate

boolean

required

true for associating the resource and false for dissociating the resource

POST api/v1/products/{product_id}/associateAccounts

OAuth Scope

Desk.products.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/products/2000000031001/associateAccounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "2000000029035", "2000000029001" ],
  "associate" : true
}'

Response Example

200

List accounts associated with product

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

Query Params

Param Name
Data Type
Description
from

int

optional

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

sortBy

string

optional,
max chars : 100

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

GET api/v1/products/{products_id}/accounts

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://support.zoho.com/api/v1/products/2000000031001/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AccountAPI account = ZDesk.getAccountAPIInstance(mailId); <br/> List&lt;Account&gt; response = account.getAccountsUnderProduct( productId, from, limit, sortBy, isAscending );

Response Example

{
  "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"
    },
    "id" : "1892000000052077",
    "email" : "admin@zylker.com"
  }, {
    "website" : "1211212",
    "accountName" : "Agent Account",
    "phone" : "11211",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "zohoCRMAccount" : {
      "id" : "32754000000537001"
    },
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

List contacts associated with product

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

Query Params

Param Name
Data Type
Description
from

int

optional

Index number, starting from which the contacts must be listed

limit

integer

optional,
range : 1-100

Number of contacts to fetch

sortBy

string

optional,
max chars : 100

Parameter that sorts contacts by one of these attributes:
firstName,

lastName,

phone,

email,

account,

createdTime,

modifiedTime

include
see documentation

list

optional

Key that fetches secondary information related to the contact.Value allowed is accounts

isSpam

boolean

optional,
default : false

Filters Spam contacts

GET api/v1/products/{products_id}/contacts

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/products/2000000031001/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "Case",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "isAnonymous" : true,
    "phone" : "555555",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "isAnonymous" : true,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

HelpCenter

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

{
  "domains" : [ {
    "name" : "help.zoho.com",
    "type" : "PRIMARY"
  }, {
    "name" : "forums.zoho.com",
    "type" : "SECONDARY"
  } ],
  "logoLinkBackUrl" : "https://zoho.com/desk",
  "departmentIds" : [ "24073000002576907", "24073000002577809" ],
  "isMultilingualEnabled" : true,
  "logoUrl" : "https://desk.zoho.com/api/v1/helpCenter/24073000002579275/logo/240730000025738740?orgId=2389290",
  "url" : "https://help.zoho.com/portal",
  "locales" : [ "en" ],
  "isDefault" : true,
  "siteMapUpdatedTime" : "2019-05-30T21:34:01.000Z",
  "name" : "restapiautomatiion",
  "favIconUrl" : "https://desk.zoho.com/api/v1/helpCenter/24073000002579275/favIcon/240730000025783905?orgId=2389290",
  "id" : "59882000000170069",
  "helpCenterLocales" : [ {
    "name" : "ZohoCorp Portal",
    "locale" : "en",
    "type" : "DEFAULT",
    "status" : "ACCESIBLE_IN_HELPCENTER"
  } ],
  "primaryLocale" : "en_US",
  "status" : "ACTIVE"
}


List help centers

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

Query Params

Param Name
Data Type
Description
from

Integer

optional,
range : >0

Index number starting from which the helpcenters must be listed

limit

Integer

optional,
range : 1-50

Number of helpcenters to list

GET /api/v1/helpCenters

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/helpCenters?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "name" : "Zoho Cares",
    "id" : "24073000002579275",
    "departmentIds" : [ "24073000000102043" ],
    "isMultilingualEnabled" : true,
    "helpCenterLocales" : [ {
      "name" : "ZohoCorp Portal",
      "locale" : "en",
      "type" : "DEFAULT",
      "status" : "ACCESIBLE_IN_HELPCENTER"
    } ],
    "primaryLocale" : "en",
    "logoUrl" : "https://static.zohocdn.com/desk/app/images/portalLogo.de847024ebc0131731a3.png",
    "url" : "https://help.zoho.com/portal/",
    "status" : "ACTIVE"
  } ]
}

Get details of help center

This API fetches the details of a particular help center.

Credit: 1 credit/call

GET /api/v1/helpCenters/{helpcenter_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/helpCenters/24073000002579275?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "domains" : [ {
    "name" : "forums.zoho.com",
    "type" : "SECONDARY"
  }, {
    "name" : "help.zoho.com",
    "type" : "PRIMARY"
  } ],
  "logoLinkBackUrl" : "https://www.zoho.com/desk/",
  "departmentIds" : [ "24073000000102043" ],
  "logoUrl" : "https://static.zohocdn.com/desk/app/images/portalLogo.de847024ebc0131731a3.png",
  "url" : "https://help.zoho.com/portal/",
  "isDefault" : true,
  "siteMapUpdatedTime" : "2019-12-26T08:48:09.000Z",
  "name" : "Zoho Cares",
  "favIconUrl" : "https://static.zohocdn.com/desk/app/images/support-2.befdbf2e5043b988ef7e.ico",
  "id" : "24073000002579275",
  "helpCenterLocales" : [ {
    "name" : "Zoho Cares",
    "locale" : "en",
    "type" : "DEFAULT",
    "status" : "ACCESIBLE_IN_HELPCENTER"
  } ],
  "primaryLocale" : "en",
  "status" : "ACTIVE"
}

Update Helpcenter sitemaps

This API will generate sitemaps for the given Helpcenter

Credit: 1 credit/call

POST /api/v1/helpCenters/4000000190032/sitemaps

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/helpCenters/4000000190032/sitemaps?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Users

Users refer to the end-customers of the product/service who visit the Help Center to find solutions.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the user

email

list

Email address of the user

status

string

Activation status of the user. The supported values are ACTIVE and DISABLED

Example

{
  "id" : "142456352454",
  "email" : [ {
    "emailAddress" : "zylcare@zylker.com",
    "isVerified" : "true",
    "isPrimary" : "true"
  } ]
}


List help center users

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of users to be listed. The default and the maximum allowed value is 50

searchBy

String

optional

Search keyword to find a particular user. Note: The keyword must contain at least two characters

sortBy

String

optional

Key that sorts the list of users by a particular attribute: -(email or modifiedTime)

status

String

optional

Activation status of the users to list

helpCenterId

long

optional

ID of the help center from which the users must be fetched

include
see documentation

string

optional,
max chars : 100

Additional information related to the user. Value allowed is count.

GET /api/v1/users

OAuth Scope

Desk.search.READ , Desk.contacts.READ , Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&include=count
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastAccessedTime" : "2021-06-11T06:21:32.000Z",
    "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
    "emailAddress" : "carol@zylker.com",
    "name" : "Developer",
    "id" : "310975130121",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#39B54A",
        "textColor" : "#FFFFFF"
      },
      "name" : "Lock Label",
      "id" : "24073000002823026",
      "logoUrl" : null
    },
    "type" : "ENDUSER",
    "status" : "ACTIVE"
  } ],
  "count" : "1"
}

Get details of user

This API fetches the details of a particular help center user.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the user. Value allowed is contact.

helpCenterId

long

optional

ID of the help center from which the user must be fetched

GET /api/v1/users/{user_id}

OAuth Scope

Desk.contacts.READ , Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/users/310975130121?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "lastAccessedTime" : "2021-06-11T06:21:32.000Z",
  "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
  "contactId" : "3313135931139",
  "contact" : {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "name" : "Developer",
    "id" : "3313135931139"
  },
  "name" : "Developer",
  "id" : "310975130121",
  "label" : {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "name" : "Lock Label",
    "id" : "24073000002823026",
    "logoUrl" : null
  },
  "type" : "ENDUSER",
  "email" : [ {
    "emailAddress" : "zylcare@zylker.com",
    "isVerified" : "false",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}

Update details of user

This API helps update the details of a particular help center user.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
helpCenterId

long

optional

ID of the help center from which the user must be updated

Attributes

Param Name
Data Type
Description
email

list

optional

Email ID of the user

status

string

optional,
max chars : 100

Activation status of the user. Values supported are ACTIVE and DISABLED.

PATCH /api/v1/users/{user_id}

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/users/4000000190069?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "email" : [ {
    "emailAddress" : "zylcare@zylker.com",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}'

Response Example

{
  "lastAccessedTime" : "2021-06-11T06:21:32.000Z",
  "photoURL" : "https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo",
  "contactId" : "3313135931139",
  "name" : "Developer",
  "id" : "310975130121",
  "label" : {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "name" : "Lock Label",
    "id" : "24073000002823026",
    "logoUrl" : null
  },
  "type" : "ENDUSER",
  "email" : [ {
    "emailAddress" : "zylcare@zylker.com",
    "isVerified" : "false",
    "isPrimary" : "true"
  } ],
  "status" : "ACTIVE"
}

Anonymize user

This API permanently deletes all identifying information about a user from your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
anonymizedName

string

optional,
max chars : 100

Display name of the user in tickets and community topics after anonymization

POST api/v1/users/{user_id}/anonymize

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/4000000190069?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "anonymizedName" : "Guest User 001"
}'

Response Example

204

List user groups

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the groups must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of groups to list. The default value and the maximum value allowed is 50

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

sortBy

String

optional

Key that sorts the list of user groups by a particular attribute: -(addedTime)

helpCenterId

long

optional

ID of the help center from which the groups must be fetched

GET /api/v1/users/{user_id}/groups

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/users/24073000002913021/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "addedTime" : "2020-04-06T04:50:50.000Z",
    "name" : "Zoho CRM Partners",
    "id" : "24073000002957057",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : null,
    "status" : "ACTIVE"
  }, {
    "addedTime" : "2020-04-06T04:50:30.000Z",
    "name" : "Zoho Desk Partners",
    "id" : "24073000002957051",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/24073000002959001?portalId=b363e6f8e029247a38a55e49806bf1f683801f9cd92870bf7cc50d48844902f0",
    "status" : "ACTIVE"
  }, {
    "addedTime" : "2020-04-06T04:50:14.000Z",
    "name" : "Zoho One Prime Customers",
    "id" : "24073000002957045",
    "helpCenterId" : "24073000002733221",
    "logoUrl" : null,
    "status" : "ACTIVE"
  } ]
}

Add user to groups

This API adds a user to the groups specified.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
helpCenterId

long

optional

ID of the help center from which the groups must be validated

Attributes

Param Name
Data Type
Description
groups

list

required

IDs of the groups to which the user must be added

POST /api/v1/users/{user_id}/groups/associate

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/groups/associate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "groups" : [ {
    "id" : "24073000002723212"
  }, {
    "id" : "24073000002732252"
  }, {
    "id" : "24073000002957051"
  }, {
    "id" : "24073000002793019"
  } ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002957051",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002793019",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : false,
    "id" : "24073000002723212",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : false,
    "id" : "24073000002732252",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

Remove user from groups

This API removes a user from the groups specified.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
helpCenterId

long

optional

ID of the help center from which the groups must be removed

Attributes

Param Name
Data Type
Description
groupIds

list

required

IDs of the groups from which the user must be removed

POST /api/v1/users/{user_id}/groups/dissociate

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/groups/dissociate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "groupIds" : [ "24073000002957051", "24073000002932512", "24073000002953232" ]
}'

Response Example

{
  "results" : [ {
    "success" : false,
    "id" : "24073000002957051",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Minimum user should be maintained"
    }
  }, {
    "success" : false,
    "id" : "24073000002932512",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  }, {
    "success" : true,
    "id" : "24073000002953232",
    "errors" : null
  } ]
}

List labels of user

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

Query Params

Param Name
Data Type
Description
isPrimary

boolean

optional

Key that filters the primary label assigned to the user

from

int

optional,
default : 1,
range : >0

Index number, starting from which the labels must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of labels to list. The default value and the maximum value allowed is 50

sortBy

String

optional

Key that sorts the list of labels by a particular attribute: -(assignedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

helpCenterId

long

optional

ID of the help center from which the labels must be fetched

GET /api/v1/users/{user_id}/labels

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/users/24073000002913021/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "preferences" : {
      "shape" : "ROUNDED",
      "bgColor" : "#5787E0",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "Prime Customer",
    "id" : "24073000002958013",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  }, {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#39B54A",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "Zoho One",
    "id" : "24073000002958023",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  }, {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#CE6785",
      "textColor" : "#FFFFFF"
    },
    "isPrimary" : false,
    "name" : "MVP",
    "id" : "24073000002958029",
    "helpCenterId" : "24073000002886005",
    "logoUrl" : null,
    "assignedTime" : "2020-04-06T05:55:13.000Z"
  } ]
}

Assign labels to user

This API assigns the labels you specify to a particular user.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
helpCenterId

long

optional

ID of the help center from which the labels must be validated

Attributes

Param Name
Data Type
Description
labels

list

required

List containing the details of the labels to assign

POST /api/v1/users/{user_id}/labels/assign

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/labels/assign?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "labels" : [ {
    "isPrimary" : "false",
    "id" : "24073000002958013"
  }, {
    "isPrimary" : "true",
    "id" : "24073000002152013"
  }, {
    "isPrimary" : "false",
    "id" : "24073000002958023"
  } ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002958013",
    "errors" : null
  }, {
    "success" : true,
    "id" : "24073000002958023",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002152013",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

Remove labels from user

This API removes the labels you specify from a particular user.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
helpCenterId

long

optional

ID of the help center from which the labels must be removed

Attributes

Param Name
Data Type
Description
labelIds

list

required

List containing the IDs of the labels to remove

POST /api/v1/users/{user_id}/labels/remove

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/labels/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "labelIds" : [ "24073000002958023", "24073000002952323" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002958023",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002952323",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403,
      "error" : "Restricted"
    }
  } ]
}

List User badges

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the badges must be fetched. The default value is 1

limit

int

optional,
default : 50,
range : 1-50

Number of badges to list. The default value and the maximum value allowed is 50

type

string

optional,
max chars : 100

Type of badge: default or custom

sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

startTime

date

optional

Start time should be in GMT time zone

endTime

date

optional

End time should be in GMT time zone

GET /api/v1/users/([0-9]+)/badges

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/users/([0-9]+)/badges
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "name" : "Badge 1",
  "isCustom" : "false",
  "description" : "Best Contributor",
  "id" : "1",
  "iconUrl" : "https://www.zylker.com/badge1.jpg"
} ]

Add Badges to a user

This API adds specified badges to user.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
badgeIds

list

required

IDs of the badges to which the user must be associated

POST /api/v1/users/{user_id}/badges/associate

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/badges/associate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "badgeIds" : [ "24073000002823212", "24073000002832252" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "24073000002823212",
    "errors" : null
  }, {
    "success" : false,
    "id" : "24073000002832252",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403
    }
  } ]
}

Remove Badges from user

This API removes specified badges from the users.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
badgeIds

list

required

IDs of the badges from which the user must be dissociated

POST /api/v1/users/{user_id}/badges/dissociate

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/users/24073000002913021/badges/dissociate?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=24073000002733221
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "badgeIds" : [ "24073000002957051", "24073000002953232" ]
}'

Response Example

{
  "results" : [ {
    "success" : false,
    "id" : "24073000002957051",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : 403
    }
  }, {
    "success" : true,
    "id" : "24073000002953232",
    "errors" : null
  } ]
}

Labels

Labels are tags that you add to users to highlight their contribution in your help center.

Example

{ }


Create label

This API creates a label in your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the label

logoId

long

optional

ID of the logo set for the label

helpCenterId

long

required

ID of the help center in which the label must be created

preferences

JSONObject

optional

Visual preferences related to the label/logo

POST /api/v1/labels

OAuth Scope

Desk.contacts.CREATE , Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "name" : "Pro Customer",
  "helpCenterId" : "310975130119",
  "logoId" : "310975130121"
}'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "0",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

Update label

This API helps update the details of a label.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the label

logoId

long

optional

ID of the logo set for the label

preferences

JSONObject

optional

Visual preferences related to the label/logo

PATCH /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "name" : "Pro Customer",
  "logoId" : "310975130121"
}'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "892",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

Get details of label

This API fetches the details of a particular label.

Credit: 1 credit/call

GET /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "preferences" : {
    "shape" : "ROUNDED",
    "bgColor" : "#FFEE",
    "textColor" : "#FFEE"
  },
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Pro Customer",
  "count" : "320",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975130110",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
}

List labels

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the labels must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-50

Number of labels to list. The default value and the maximum value allowed is 50.

sortBy

String

optional

Key that sorts the list of labels by a particular attribute: -(createdTime or modifiedTime, or name)

searchBy

String

optional

Search 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)

helpCenterId

long

optional

ID of the help center from which the labels must be fetched

GET /api/v1/labels

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-09-19T04:58:50.000Z",
    "preferences" : {
      "shape" : "ROUNDED",
      "bgColor" : "#FFEE",
      "textColor" : "#FFEE"
    },
    "creator" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "modifier" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "name" : "Pro Customer",
    "count" : "892",
    "createdTime" : "2017-09-19T04:58:50.000Z",
    "id" : "310975130110",
    "helpCenterId" : "310975130119",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48"
  } ]
}

Delete label

This API deletes a label from your help center.

Credit: 1 credit/call

DELETE /api/v1/labels/{label_id}

OAuth Scope

Desk.contacts.DELETE , Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/labels/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Delete label by labelIds

This API deletes labels, based on the IDs specified.

Credit: 6 credits/record

Query Params

Param Name
Data Type
Description
labelIds

long

optional

IDs of the labels to delete

DELETE /api/v1/labels

OAuth Scope

Desk.contacts.DELETE , Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/labels?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&labelIds=310975130110,310975130021
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Assign label to users

This API assigns a particular label to multiple users.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users to whom the label must be assigned

POST /api/v1/labels/{label_id}/users/add

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/labels/310975130110/users/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3109751143253", "310975131231", "310975133141", "310975101849" ]
}'

Response Example

204

Remove users under a label

This API removes all users under a particular label.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users from whom the label must be removed

POST /api/v1/labels/{label_id}/users/remove

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/labels/310975130110/users/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3109751143253", "310975131231", "310975133141", "310975101849" ]
}'

Response Example

204

List users under a label

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-100

Number of users to list. The default value is 50 and the maximum value allowed is 100

sortBy

String

optional

Key that sorts the list of users by a specific attribute: -(assignedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

GET /api/v1/labels/{label_id}/users

OAuth Scope

Desk.search.READ , Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/labels/310975130110/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : null,
    "emailAddress" : "carol@zylker.com",
    "name" : "svega RM",
    "userType" : "ENDUSER",
    "assignee" : {
      "photoUrl" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
      "name" : "Chris",
      "id" : "6000000015895"
    },
    "id" : "6000000032907",
    "assignedTime" : "2019-08-09T07:47:44.000Z",
    "status" : "ACTIVE"
  } ]
}

Groups

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

{ }


Create user groups

This API creates a user group in your help center.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 100

Name of the group

description

string

optional,
max chars : 3000

A brief description of the group

logoId

long

optional

ID of the logo to associate with the group

helpCenterId

long

required

ID of the help center in which the group must be created

POST /api/v1/groups

OAuth Scope

Desk.contacts.CREATE , Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Prime Customer",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "helpCenterId" : "31097519102",
  "logoId" : "310975130121"
}'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "Prime Customer",
  "count" : "0",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "31097519102",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

Update group

This API helps update the details of a user group.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 100

Name of the group

description

string

optional,
max chars : 3000

A brief description of the group

logoId

long

optional

ID of the logo to associate with the group

PATCH /api/v1/groups/{group_Id}

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/groups/310975134902?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "MVP Customer",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "logoId" : "310975130133",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "MVP Customer",
  "count" : "892",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "31097519102",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

Get details of group

This API fetches the details of a particular user group.

Credit: 1 credit/call

GET /api/v1/groups/{group_id}

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groups/310975134902?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "creator" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "modifier" : {
    "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
    "name" : "SupportAdmin",
    "id" : "310975130121"
  },
  "name" : "MVP Customer",
  "count" : "892",
  "description" : "Prime customer will have special access to Knowledge base module and Community categories",
  "createdTime" : "2017-09-19T04:58:50.000Z",
  "id" : "310975134902",
  "helpCenterId" : "310975130119",
  "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
  "status" : "ACTIVE"
}

List groups

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the groups must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-50

Number of groups to list. The default value and the maximum value allowed is 50.

sortBy

String

optional

Key that sorts the list of groups by a particular attribute: -(createdTime, modifiedTime, name, or count)

searchBy

String

optional

Search 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).

helpCenterId

long

optional

ID of the help center from which the resource must be fetched

GET /api/v1/groups

OAuth Scope

Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groups?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&helpCenterId=310975130119
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-09-19T04:58:50.000Z",
    "creator" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "modifier" : {
      "photoURL" : "https://desk.zoho.com/portal/api/user/310975130121/photo?orgId=143315",
      "name" : "SupportAdmin",
      "id" : "310975130121"
    },
    "name" : "Pro Customer",
    "count" : "353",
    "description" : "Pro Customers paid customers of the org will avail 24x7 Support service",
    "createdTime" : "2017-09-19T04:58:50.000Z",
    "id" : "310975130110",
    "helpCenterId" : "310975130119",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/310975130133?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48",
    "status" : "ACTIVE"
  } ]
}

Delete group

This API deletes a user group from your help center.

Credit: 1 credit/call

DELETE /api/v1/groups/{group_Id}

OAuth Scope

Desk.contacts.DELETE , Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/groups/310975130110?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Add users to group

This API adds users to a particular group.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
users

list

required

IDs of the users who must be added to the group

POST /api/v1/groups/{group_id}/users/add

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/groups/310975130110/users/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "users" : [ {
    "id" : "17883000000094001"
  }, {
    "id" : "17883000000094023"
  } ]
}'

Response Example

204

Remove users from group

This API removes particular users from a group.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users who must be removed from the group

POST /api/v1/groups/{group_Id}/users/remove

OAuth Scope

Desk.contacts.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/groups/310975130110/users/remove?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "17883000000013101", "17883000000094023" ]
}'

Response Example

204

List users in a group

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

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 1,
range : >0

Index number, starting from which the users must be fetched. The default value is 1.

limit

int

optional,
default : 50,
range : 1-100

Number of users to list. The default value is 50 and the maximum value allowed is 100.

sortBy

String

optional

Key that sorts the list of users, based on a specific attribute: -(addedTime)

searchBy

String

optional

Search keyword to use for finding a particular user. The keyword must contain at least two characters.

GET /api/v1/groups/{group_Id}/users

OAuth Scope

Desk.search.READ , Desk.contacts.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groups/310975130110/users?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : null,
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/portal/api/user/24073000000095005/photo?orgId=143315",
      "name" : "ZylCare Admin",
      "id" : "24073000000095005"
    },
    "emailAddress" : "carol@zylker.com",
    "name" : "John ",
    "addedTime" : "2019-11-08T14:57:39.000Z",
    "userType" : "ENDUSER",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#6CD4DF",
        "textColor" : "#FFFFFF"
      },
      "name" : "Prime Customer",
      "id" : "24073000002132001"
    },
    "id" : "24073000001997453",
    "status" : "ACTIVE"
  } ]
}

Articles

Articles are the source of information that you create/share in your Knowledge Base on the help desk portal for your customers to help themselves. They guide customers on how to use a feature/product, provide solutions to their issues, and also cover frequently encountered questions.
Article translations: Although articles are all-inclusive and extensive, they become meaningless when the customers cannot understand them. As KB articles are customer-centric, we are providing a translation option to translate the article from a default language to a multi-lingual language.

ATTRIBUTES

Attribute Name
Data Type
Description
id

Long

ID of the article

departmentId

Long

ID of the department associated with the article

categoryId

Long

ID of the category associated with the article

title

String

Title of the article

answer

String

Content of the article

permalink

String

The permalink to access the article

authorId

Long

ID of the user who created the article

status

String

Publishing status of the article. Values allowed are
Draft

Published

Review

Unpublished

permission

String

Access permissions for the article. Values allowed are
ALL,

REGISTEREDUSERS,

AGENTS

tags

String Array

Tags associated with the article

seoTitle

String

SEO-specific title of the article

seoKeywords

String

SEO-specific keywords of the article

seoDescription

String

SEO-specific description of the article

expiryDate

String

Schedule the expiry date of the article. format : (YYYY-MM-DD HH:MM)

Example

{
  "modifiedTime" : "2017-09-13T18:44:11.000Z",
  "attachments" : [ {
    "reseourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40",
    "name" : "Attachment1.png",
    "viewUrl" : "https://desk.zoho.com/DocsDisplay?attachId=b34f0de640d72a1dc0f0b676f752dadae612657a51fd5fbe&action=view&zgId=3baf28131e9f8df2dc91a236738b3d70&entityId=b34f0de640d72a1d61ce88b268c6605542acf79f93f757e8",
    "downloadUrl" : "https://desk.zoho.com/DocsDisplay?attachId=b34f0de640d72a1dc0f0b676f752dadae612657a51fd5fbe&action=download&zgId=3baf28131e9f8df2dc91a236738b3d70&entityId=b34f0de640d72a1d61ce88b268c6605542acf79f93f757e8",
    "createdTime" : "2017-09-14T00:14:09.699Z",
    "filesize" : "113727"
  } ],
  "reviewedTime" : null,
  "departmentId" : "22372000000006907",
  "modifierId" : "7000000015932",
  "creatorId" : "7000000015932",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "title" : "Importance of a Knowledge Base",
  "latestVersionModifierId" : "4000000000060",
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "public" : true,
  "quickEdit" : {
    "modifierId" : "24073000007464062",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000007464062/photo?orgId=54325703",
      "name" : "Tony Stark",
      "id" : "24073000007464062",
      "status" : "ACTIVE",
      "zuid" : "70425988"
    }
  },
  "createdTime" : "2017-09-13T18:18:32.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005",
    "zuid" : "234543"
  },
  "id" : "22372000000119001",
  "seo" : {
    "keywords" : "Knowledge base, Helpcenter",
    "isEnabled" : true,
    "description" : "Knowledge base for your product",
    "title" : "Knowledge base"
  },
  "templateUsedUsersCount" : "2",
  "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
  "latestVersionStatus" : "Draft",
  "author" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "7000000015932",
    "zuid" : "234543"
  },
  "permission" : "ALL",
  "reviewedBy" : null,
  "authorId" : "22372000000094005",
  "tags" : [ "helpcenter", "knowledge base" ],
  "commentCount" : "0",
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "latestVersion" : "0.1",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005",
    "zuid" : "234543"
  },
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-a-knowledge-base",
  "latestPublishedVersion" : "null",
  "attachmentCount" : "1",
  "position" : "0",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "followersCount" : "0",
    "lastActivityTime" : "2017-09-13T18:44:11.000Z",
    "usageCount" : "0"
  },
  "availableLocaleTranslations" : [ {
    "latestVersionStatus" : "Published",
    "translationId" : "28841000002282003",
    "isTrashed" : false,
    "latestVersion" : "1.0",
    "isLocked" : false,
    "latestPublishedVersion" : "1.0",
    "href" : "https://desk.zoho.com/api/v1/articles/28841000002282001/translations/en?orgId=54689695",
    "authorId" : "28841000000103005",
    "locale" : "en",
    "translationState" : "UP-TO-DATE",
    "status" : "Published"
  } ],
  "permalink" : "test123-13-9-2017",
  "category" : {
    "name" : "General",
    "id" : "22372000000094159"
  },
  "categoryId" : "7000000016129",
  "latestVersionModifiedBy" : {
    "photoURL" : null,
    "name" : "will smith",
    "id" : "4000000000060",
    "status" : "ACTIVE",
    "zuid" : "234544"
  },
  "status" : "Draft"
}


List articles

This API fetches a specific number of articles from your knowledge base, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

optional,
range : >0

Index number starting from which the articles must be fetched.

limit

Integer

optional,
range : 1-50

Number of articles to fetch

sortBy

String

optional

Key that sorts the articles based on a specific attribute:
createdTime,
or
modifiedTime
or
likeCount
or
viewCount
or
feedbackCount
or
dislikeCount
or
positionArticle

permission

String

optional

Access permission for the article. Values allowed are: ALL, REGISTEREDUSERS, and AGENTS

authorId

Long

optional

ID of article owner

categoryId

Long

optional

ID of the category to which the article belongs

modifiedTimeRange

timestamp

optional

Key that filters articles modified within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

expiryTimeRange

timestamp

optional

Key that filters articles which will expire within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

status

String

optional

Publishing status of the article. Values allowed are Draft, Published, Review, Expired, Unpublished

GET /api/v1/articles

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles?from=0&limit=10&sortBy=-createdTime&status=Published&categoryId=4000000013240&permission=ALL&orgId=5686513&modifiedTimeRange=2018-07-16T04:48:08.000Z,2018-07-16T07:48:08.000Z&authorId=4000000012931
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-06-24T11:46:43.000Z",
    "departmentId" : "24073000000006907",
    "creatorId" : "4000000000059",
    "dislikeCount" : "0",
    "modifierId" : "4000000000059",
    "likeCount" : "0",
    "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
    "locale" : "en",
    "latestVersionModifierId" : "4000000000060",
    "ownerId" : "4000000000059",
    "title" : "Answering your first ticket.",
    "translationState" : "UP-TO-DATE",
    "expiryDate" : "2018-05-21T05:55:00.000Z",
    "isTrashed" : false,
    "createdTime" : "2020-06-24T11:46:43.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000000095005/photo?orgId=54325703",
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019059",
    "viewCount" : "0",
    "translationSource" : null,
    "templateUsedUsersCount" : "2",
    "owner" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "permission" : "AGENTS",
    "authorId" : "4000000000059",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "4000000017276",
    "sourceLocale" : "en",
    "templateUsageCount" : "0",
    "translationId" : "4000000017294",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "latestVersion" : "1.0",
    "isTemplate" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "feedbackCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
    "attachmentCount" : "0",
    "latestPublishedVersion" : "1.0",
    "position" : "1",
    "availableLocaleTranslations" : [ {
      "latestVersionStatus" : "Published",
      "translationId" : "24073000000095164",
      "isTrashed" : false,
      "latestVersion" : "1.0",
      "isLocked" : false,
      "latestPublishedVersion" : "1.0",
      "href" : "https://desk.zoho.com/api/v1/articles/24073000002823830/translations/en?orgId=54325703",
      "authorId" : "24073000000095005",
      "locale" : "en",
      "translationState" : "UP-TO-DATE",
      "status" : "Published"
    } ],
    "category" : {
      "name" : "General",
      "id" : "4000000017287",
      "locale" : "en"
    },
    "permalink" : "answering-your-first-ticket",
    "categoryId" : "4000000017287",
    "latestVersionModifiedBy" : {
      "photoURL" : null,
      "name" : "will smith",
      "id" : "4000000000060",
      "status" : "ACTIVE",
      "zuid" : "234544"
    },
    "status" : "Published"
  } ]
}

Get article

This API fetches an article from your knowledge base.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
version

String

optional

Version number of the article

GET /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000000133001?version=1.2&orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "departmentId" : "24073000002376045",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "likeCount" : "0",
  "latestVersionModifierId" : "4000000000060",
  "ownerId" : "4000000000059",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : false,
  "quickEdit" : {
    "modifierId" : "24073000007464062",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000007464062/photo?orgId=54325703",
      "name" : "Tony Stark",
      "id" : "24073000007464062",
      "status" : "ACTIVE",
      "zuid" : "70425988"
    }
  },
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "id" : "4000000019059",
  "translationSource" : null,
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "commentCount" : "0",
  "tags" : [ "first ticket" ],
  "sourceLocale" : "en",
  "translationId" : "4000000017294",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "followersCount" : "0",
  "position" : "6",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "2",
    "unlikeCount" : "2",
    "dislikeCount" : "2",
    "lastUsageTime" : null,
    "likeCount" : "1",
    "viewCount" : "257",
    "lastActivityTime" : "2023-02-21T13:26:07.000Z",
    "usageCount" : "0"
  },
  "permalink" : "answering-your-first-ticket",
  "latestVersionModifiedBy" : {
    "photoURL" : null,
    "name" : "will smith",
    "id" : "4000000000060",
    "status" : "ACTIVE",
    "zuid" : "234544"
  },
  "status" : "Published",
  "attachments" : [ {
    "resourceId" : "mvfyda9fcc4df229b4065a04fba88a5b81b33",
    "extension" : "jpg",
    "size" : "3028238",
    "name" : "bird_2.jpg",
    "downloadUrl" : "https://desk.zoho.com/api/v1/articles/24073000005321222/translations/en/attachments/mvfyda9fcc4df229b4065a04fba88a5b81b33/content?orgId=54325703&inline=false",
    "viewUrl" : "https://desk.zoho.com/api/v1/articles/24073000005321222/translations/en/attachments/mvfyda9fcc4df229b4065a04fba88a5b81b33/content?orgId=54325703",
    "createdTime" : "2021-11-02T05:11:21.000Z"
  } ],
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "locale" : "en",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "isEnabled" : true,
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "isFollowing" : true,
  "myVote" : null,
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "usageCount" : "0",
  "rootCategoryId" : "4000000017276",
  "templateUsageCount" : "0",
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "availableLocaleTranslations" : [ {
    "latestVersionStatus" : "Published",
    "translationId" : "24073000005321224",
    "isTrashed" : false,
    "latestVersion" : "19.0",
    "isLocked" : false,
    "latestPublishedVersion" : "19.0",
    "href" : "https://desk.zoho.com/api/v1/articles/24073000005321222/translations/en?orgId=54325703",
    "authorId" : "24073000000095005",
    "locale" : "en",
    "translationState" : "UP-TO-DATE",
    "status" : "Published"
  }, {
    "latestVersionStatus" : "Draft",
    "translationId" : "24073000005321260",
    "isTrashed" : false,
    "latestVersion" : "0.1",
    "isLocked" : false,
    "latestPublishedVersion" : null,
    "href" : "https://desk.zoho.com/api/v1/articles/24073000005321222/translations/zh?orgId=54325703",
    "authorId" : "24073000000095005",
    "locale" : "zh",
    "translationState" : "OUTDATED",
    "status" : "Draft"
  } ],
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "categoryId" : "4000000017287"
}

Create an article

This API creates an article in your helpdesk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
categoryId

Long

required

The Category

title

String

required

The title of article

answer

String

required

The answer part of article

permalink

String

optional

The permalink of article

authorId

Long

optional

The owner of the article

status

String

required

Status of the article
Draft

Published

Review

permission

String

optional

Permission of the article.Values allowed are
ALL

REGISTEREDUSERS

AGENTS

tags

String Array

optional

Tags associated with the article

seoTitle

String

optional

SEO title of the article

seoKeywords

String

optional

SEO keywords of the article

seoDescription

String

optional

SEO description of article

isSEOEnabled

boolean

optional

SEO enabled status of an article

expiryDate

String

optional

Schedule the expiry date of the article. format : (YYYY-MM-DD HH:MM)

isTemplate

boolean

optional

Is it a template

POST /api/v1/articles

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "seoDescription" : "Knowledge Base for your product",
  "permission" : "ALL",
  "title" : "Importance of a Knowledge Base",
  "authorId" : 22372000000094004,
  "seoTitle" : "Knowledge Base",
  "seoKeywords" : "Helpcenter, Knowledge Base",
  "tags" : [ "knowledge base", "helpcenter" ],
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "isSEOEnabled" : true,
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "isTemplate" : false,
  "permalink" : "knowledgebase",
  "categoryId" : 22372000000094160,
  "status" : "Draft"
}'

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "departmentId" : "24073000000006907",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "likeCount" : "0",
  "latestVersionModifierId" : null,
  "ownerId" : "4000000000059",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : false,
  "quickEdit" : {
    "modifierId" : null,
    "modifiedBy" : null
  },
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "id" : "4000000019059",
  "translationSource" : null,
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "commentCount" : "0",
  "tags" : [ "first ticket" ],
  "sourceLocale" : "en",
  "translationId" : "4000000017294",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "dislikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "position" : "28",
  "permalink" : "answering-your-first-ticket",
  "latestVersionModifiedBy" : null,
  "status" : "Published",
  "attachments" : [ ],
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "locale" : "en",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "isEnabled" : true,
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "isFollowing" : true,
  "myVote" : null,
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "usageCount" : "0",
  "rootCategoryId" : "4000000017276",
  "templateUsageCount" : "0",
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "availableLocaleTranslations" : [ {
    "latestVersionStatus" : "Published",
    "translationId" : "24073000007814015",
    "isTrashed" : false,
    "latestVersion" : "1.0",
    "isLocked" : false,
    "latestPublishedVersion" : "1.0",
    "href" : "https://desk.zoho.com/api/v1/articles/24073000007814013/translations/en?orgId=54325703",
    "authorId" : "24073000000095005",
    "locale" : "en",
    "translationState" : "UP-TO-DATE",
    "status" : "Published"
  } ],
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "categoryId" : "4000000017287"
}

Update an article

This API updates an existing article.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description

Attributes

Param Name
Data Type
Description
categoryId

Long

optional

The Category

title

String

optional

The title of Article

answer

String

optional

The answer part of the article

permalink

String

optional

The permalink of the article

authorId

Long

optional

The owner of the article

status

String

optional

Status of the article
Draft

Published

Review

Unpublished

permission

String

optional

Permission of the article.Values allowed are
ALL

REGISTEREDUSERS

AGENTS

tags

String Array

optional

Tags associated with the article

seoTitle

String

optional

SEO Title of article

seoKeywords

String

optional

SEO Keywords of the article

seoDescription

String

optional

SEO Description of the article

isSEOEnabled

boolean

optional

SEO enabled status of the article

expiryDate

String

optional

Schedule the expiry date of the article. format : (YYYY-MM-DD HH:MM)

PATCH /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/articles/22372000000133001?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "isSEOEnabled" : true,
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "seoDescription" : "Knowledge base for your product",
  "permission" : "REGISTEREDUSERS",
  "title" : "Importance of a Knowledge Base",
  "authorId" : 22372000000094004,
  "seoTitle" : "Knowledge base",
  "seoKeywords" : "Knowledge base, Helpcenter",
  "categoryId" : 22372000000094160,
  "status" : "Draft",
  "tags" : [ "helpcenter", "knowledge base" ]
}'

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "departmentId" : "24073000000006907",
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "likeCount" : "0",
  "latestVersionModifierId" : "4000000000060",
  "ownerId" : "4000000000059",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : false,
  "quickEdit" : {
    "modifierId" : null,
    "modifiedBy" : null
  },
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "id" : "4000000019059",
  "translationSource" : null,
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "commentCount" : "0",
  "tags" : [ "first ticket" ],
  "sourceLocale" : "en",
  "translationId" : "4000000017294",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "dislikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "position" : "28",
  "permalink" : "answering-your-first-ticket",
  "latestVersionModifiedBy" : {
    "photoURL" : null,
    "name" : "will smith",
    "id" : "4000000000060",
    "status" : "ACTIVE",
    "zuid" : "234544"
  },
  "status" : "Draft",
  "attachments" : [ ],
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "locale" : "en",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "isEnabled" : true,
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "isFollowing" : true,
  "myVote" : null,
  "permission" : "AGENTS",
  "authorId" : "22372000000094004",
  "usageCount" : "0",
  "rootCategoryId" : "4000000017276",
  "templateUsageCount" : "0",
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "latestVersion" : "1.0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "availableLocaleTranslations" : [ {
    "latestVersionStatus" : "Published",
    "translationId" : "24073000007814015",
    "isTrashed" : false,
    "latestVersion" : "1.0",
    "isLocked" : false,
    "latestPublishedVersion" : "1.0",
    "href" : "https://desk.zoho.com/api/v1/articles/24073000007814013/translations/en?orgId=54325703",
    "authorId" : "24073000000095005",
    "locale" : "en",
    "translationState" : "UP-TO-DATE",
    "status" : "Published"
  } ],
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "categoryId" : "22372000000094160"
}

Get article history

This API fetches the event history of an article.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

From index

limit

Integer

required,
default : 10,
range : 1-100

Number of records to fetch

events

String

optional

Actions happened on the article. We can give multiple events comma saperated. Allowed values CREATED, SEO_INFO_ADDED, TAGS_ADDED, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, TAGS_EDITED, STATUS_CHANGED, DISPALY_PERMISSION_CHANGED, PERMALINK_EDITED, OWNER_CHANGED, SECTION_CHANGED, TITLE_EDITED, SEO_INFO_EDITED, VERSION_CREATED, MOVED_TO_TRASH, RESTORED, ATTACHMENT_MODIFIED, VERSION_REVERTED, TAGS_DELETED, COMMENTS_ADDED, COMMENTS_EDITED, COMMENTS_DELETED, VERSION_UPDATED, VERSION_QUICKEDIT, VERSION_DELETED, SEO_TITLE_CHANGED, SEO_KEYWORDS_CHANGED, SEO_DESCRIPTION_CHANGED, SEO_STATUS_CHANGED

userIds

Long

optional

User who did the action

fromTime

Timestamp

optional

From time. Time should be in GMT with format

toTime

Timestamp

optional

To time. Time should be in GMT with format

GET /api/v1/articles/{article_id}/history

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000000665001/history?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "comments" : [ {
    "isTrashed" : false,
    "ticket" : {
      "ticketNumber" : "101",
      "isTrashed" : false,
      "webUrl" : "https://desk.zoho.com/agent/zylker/zylker/tickets/details/7000000088057",
      "id" : "7000000088057"
    },
    "isPublic" : true,
    "id" : "7000000086279",
    "ticketId" : "7000000088057",
    "status" : "PUBLISHED"
  }, {
    "isTrashed" : false,
    "ticket" : null,
    "isPublic" : true,
    "id" : "7000000086272",
    "ticketId" : null,
    "status" : "PUBLISHED"
  }, {
    "isTrashed" : true,
    "ticket" : {
      "ticketNumber" : "102",
      "isTrashed" : false,
      "webUrl" : "https://desk.zoho.com/agent/zylker/zylker/tickets/details/7000000088164",
      "id" : "7000000088164"
    },
    "isPublic" : true,
    "id" : "7000000086267",
    "ticketId" : "7000000088164",
    "status" : "PUBLISHED"
  } ],
  "data" : [ {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "deltedVersion" : [ "2.0", "3.0" ],
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "editedVersion" : "3.0",
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_QUICKEDIT",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "oldVersion" : "3.0",
    "locale" : "en",
    "event" : "VERSION_REVERTED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newVersion" : "4.0"
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "oldVersion" : "1.0",
    "locale" : "en",
    "event" : "VERSION_UPDATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newVersion" : "2.0"
  }, {
    "createdVersion" : "1.0",
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "VERSION_CREATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:27:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "RESTORED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:26:28.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "MOVED_TO_TRASH",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newPermalink" : "test-article888",
    "eventTime" : "2018-03-15T14:19:28.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "PERMALINK_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "oldPermalink" : "test-article"
  }, {
    "eventTime" : "2018-03-15T14:16:06.000Z",
    "deletedTags" : [ "asda", "qwer", "ert" ],
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TAGS_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newTags" : [ "asda", "qwer", "ert" ],
    "oldTags" : [ "asda", "qwer" ],
    "eventTime" : "2018-03-15T14:15:52.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TAGS_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:15:40.000Z",
    "solutionId" : "1000000012768",
    "addedTags" : [ "qwer", "asda" ],
    "locale" : "en",
    "event" : "TAGS_ADDED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-13T07:44:02.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "deletedCommentId" : "1000000014007",
    "event" : "COMMENTS_DELETED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "editedCommentId" : "1000000014001",
    "eventTime" : "2018-03-13T07:43:45.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "COMMENTS_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "addedCommentId" : "1000000014001",
    "eventTime" : "2018-03-13T07:43:36.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "COMMENTS_ADDED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "removedAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_REMOVED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldAttachements" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_MODIFIED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    },
    "newAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ]
  }, {
    "addedAttachments" : [ "af0u71a819bc9d6304a2e9e77d20a1dd7da7c", "af0u796cb3b7b55d14f0a9b6f78e0aa3ccb56" ],
    "eventTime" : "2018-03-13T18:36:04.000Z",
    "solutionId" : "1000000012768",
    "event" : "ATTACHMENT_ADDED",
    "locale" : "en",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newSectionId" : "1000000012741",
    "oldSectionId" : "1000000014013",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SECTION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldDisplayPermission" : "REGISTERED_USERS",
    "newDisplayPermission" : "AGENTS_ONLY",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "DISPALY_PERMISSION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newStatus" : "PUBLISH",
    "eventTime" : "2018-03-15T14:10:11.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "STATUS_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "newTitle" : "Test article dddddd",
    "eventTime" : "2018-03-13T07:32:35.000Z",
    "oldTitle" : "Test article",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "TITLE_EDITED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_DESCRIPTION_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_KEYWORDS_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "oldSEOTitle" : "ajsjkda",
    "newSEOTitle" : "ajsjkdaass",
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "SEO_TITLE_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-15T14:05:21.000Z",
    "oldSEOStatus" : "false",
    "solutionId" : "1000000012768",
    "newSEOStatus" : "true",
    "locale" : "en",
    "event" : "SEO_STATUS_CHANGED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  }, {
    "eventTime" : "2018-03-12T14:05:07.000Z",
    "solutionId" : "1000000012768",
    "locale" : "en",
    "event" : "CREATED",
    "user" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000094005/photo?orgId=292828",
      "name" : "Zylker",
      "id" : "22372000000094005"
    }
  } ]
}

Upload attachments

This API uploads files to your portal gallery.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
workspaceId

String

required

Workspace id to which the attachement should be uploaded

attachmentType

String

required

Attachment type. Allowed values file, blob

File Params

file

Content-Type:multipart/form-data

attachment files for articles

POST /api/v1/articleAttachments

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articleAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&workspaceId=4fv34170cbb5ea8ed43a0932efaf53545818a&attachmentType=file
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "96b17694d63cd0f03eadbe4ae534f4ba993bb0",
  "extension" : "png",
  "name" : "Screen Shot 2018-12-28 at 7.21.58 PM.png",
  "filesize" : "62",
  "url" : "https://desk.zoho.com/galleryDocuments/edbsnf8e40a0174a649fa9b698be5f73211329e2a7513daad01207c771fbf50e1b3e33f3f5c1d654f5a4c7805862493f6bb8a?inline=true"
}

Move articles to trash

This API moves articles to the Recycle Bin

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ids

list

required

Array of Entity id to be deleted

POST /api/v1/articles/moveToTrash

OAuth Scope

Desk.articles.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/moveToTrash?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "2345678987654323", "3456789087654567" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "2345678987654323",
    "errors" : null
  }, {
    "success" : "false",
    "id" : "3456789087654567",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Preview article

This API shows a preview of help articles, through which you can check the content for formatting, alignment, and grammar/spelling errors and get the look and feel of the help article even before publishing it.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
title

String

required

The title of article

answer

String

required

The answer part of article

POST /api/v1/articles/preview

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/preview?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "answer" : "<div>Demo for article preview<br /></div><div>Lorem Ipsum is simply dummy text of the printing and typesetting industry. <br /></div>",
  "title" : "Demo for article preview"
}'

Response Example

{
  "answer" : "<div>Demo for article preview<br /></div><div>Lorem Ipsum is simply dummy text of the printing and typesetting industry. <br /></div>",
  "title" : "Demo for article preview"
}

Get article count

This API returns the number of articles published in the knowledge base of your help desk portal.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
categoryId

Long

optional

Article count for given category. If categoryId is not given or null, it considered as all category i.e all department

authorId

Long

optional

Article count for the particular author

status

String

optional

Publishing status of the article to get count. Values allowed are Draft, Published, Review, Expired, Unpublished

permission

String

optional

Permissions to get the article count. Values allowed are ALL, REGISTEREDUSERS, AGENTS

GET /api/v1/articles/count

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/count?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&categoryId=30000087654324&authorId=2000087651124&status=Draft&permission=ALL
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "5"
}

Map articles to tickets

This API maps tickets with help articles to automatically suggest the same articles for similar tickets that arrive later.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

list

required

Array of Entity ids

POST /api/v1/tickets/{ticket_id}/notifyArticleUsage

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/10002398278/notifyArticleUsage?orgId=55560202
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "1000000022005", "1000000034567" ]
}'

Response Example

204

Get articles for manual sorting

This API lists the positions of help articles to enable manual sorting. Only leaf categories that have a maximum of 1000 articles can be repositioned.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

GET /api/v1/kbCategory/{category_id}/repositionArticles

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbCategory/4000000013240/repositionArticles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000281023",
    "id" : "22372000000281023",
    "title" : "Importance of a Knowledge Base",
    "authorId" : "4000000012931"
  }, {
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000209871",
    "id" : "22372000000209871",
    "title" : "Importance of a Knowledge Base",
    "authorId" : "4000000012931"
  } ]
}

Update article position

This API helps you manually sort articles in your knowledge base. Only leaf categories that have a maximum of 1000 articles can be repositioned.

Credit: 50 credits/call

Attributes

Param Name
Data Type
Description
ids

list

required

Array of Entity ids

POST /api/v1/kbCategory/{category_id}/repositionArticles

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbCategory/2000087651211/repositionArticles?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "4000000083313", "4000000082105" ]
}'

Response Example

204

Add translation

This API adds a translated version of an article.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
title

String

required

The title of the Article

answer

String

required

The answer part of the article

permalink

String

optional

The permalink of the article

status

String

required

Status of the article
Draft

Published

Review

permission

String

optional

Permission of the article.Values allowed are
ALL

REGISTEREDUSERS

AGENTS

tags

String Array

optional

Tags associated with the article

seoTitle

String

optional

SEO Title of the article

seoKeywords

String

optional

SEO Keywords of the article

seoDescription

String

optional

SEO Description of the article

isSEOEnabled

boolean

optional

SEO enabled status of the article

attachmentIds

String Array

optional

IDs of the attachments associated with the article

expiryDate

String

optional

Schedule the expiry date of the article. format : (YYYY-MM-DD HH:MM)

locale

String

required

Language code of the article translation

authorId

Long

required

ID of the user who created the article

translationState

String

optional

Key that specifies the state of the translated article:
OUTDATED

UP-TO-DATE

POST /api/v1/articles/{articleId}/translations

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/22372000000133001/translations?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isSEOEnabled" : true,
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "seoDescription" : "Knowledge Base for your product",
  "title" : "Importaance of asda Knowledge base",
  "seoTitle" : "Knowledge Base",
  "seoKeywords" : "Knowledge Base, Helpcenter",
  "locale" : "en-us",
  "authorId" : "1000000016052",
  "translationState" : "UP-TO-DATE",
  "status" : "Published",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "modifiedTime" : "2019-01-17T08:33:06.000Z",
  "departmentId" : "1000000012968",
  "dislikeCount" : "0",
  "modifierId" : "1000000016052",
  "likeCount" : "0",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "latestVersionModifierId" : null,
  "ownerId" : "24073000000095005",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : "false",
  "quickEdit" : {
    "modifierId" : null,
    "modifiedBy" : null
  },
  "isLocked" : "true",
  "createdTime" : "2019-01-17T08:33:06.000Z",
  "id" : "1000000017031",
  "translationSource" : {
    "locale" : "fr",
    "version" : "2.0"
  },
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "reviewedBy" : null,
  "currentVersion" : "1.0",
  "tags" : [ "tag1", "tag2" ],
  "commentCount" : "0",
  "sourceLocale" : "it-IT",
  "translationId" : "100000001293248",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/1000000017031",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "position" : "6",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "dislikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "permalink" : "importaance-of-asda-knowledge-base",
  "latestVersionModifiedBy" : null,
  "status" : "Published",
  "attachments" : [ ],
  "reviewedTime" : null,
  "creatorId" : "1000000016052",
  "title" : "Importaance of asda Knowledge base",
  "locale" : "en-US",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "Knowledge Base, Helpcenter",
    "isEnabled" : true,
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "summary" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your ",
  "owner" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000000095005/photo?orgId=54325703",
    "name" : "Zylker",
    "id" : "24073000000095005",
    "status" : "ACTIVE"
  },
  "isFollowing" : true,
  "myVote" : "null",
  "permission" : "REGISTEREDUSERS",
  "authorId" : "1000000016052",
  "usageCount" : "0",
  "rootCategoryId" : "24073000002378289",
  "templateUsageCount" : "0",
  "answer" : "The knowledge base is a key component of a good help center. This is where you can share the basics of using your products or services to your customers. Help articles and FAQs are great assets when it comes to answering the most fundamental questions your customers might have regarding your offerings. Help articles also ease the burden of your customer support agents by enabling self-service.",
  "latestVersion" : "1.0",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importaance-of-asda-knowledge-base",
  "attachmentCount" : "0",
  "category" : {
    "name" : "General",
    "id" : "1000000016397",
    "locale" : "ta"
  },
  "categoryId" : "1000000016397"
}

Edit translation

This API edits an already translated article.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
createVersion

Boolean

optional

Denotes if a new version is needed

Attributes

Param Name
Data Type
Description
title

String

optional

The title of the article

answer

String

optional

The answer part of the article

permalink

String

optional

The permalink of the article

status

String

optional

Status of the article
Draft

Published

Review

Unpublished

permission

String

optional

Permission of the article.Values allowed are
ALL

REGISTEREDUSERS

AGENTS

tags

String Array

optional

Tags associated with the article

seoTitle

String

optional

SEO Title of the article

seoKeywords

String

optional

SEO Keywords of the article

seoDescription

String

optional

SEO Description of the article

isSEOEnabled

boolean

optional

SEO enabled status of the article

attachmentIds

String Array

optional

IDs of the attachments associated with the article

expiryDate

String

optional

Schedule the expiry date of the article. format : (YYYY-MM-DD HH:MM)

authorId

Long

optional

ID of the user who created the article

translationState

String

optional

Key that specifies the state of the translated article:
OUTDATED

UP-TO-DATE

PATCH /api/v1/articles/{articleId}/translations/{locale}

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/articles/22372000000133001/translations/en-us?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "expiryDate" : "2019-12-01T11:29:16.000Z",
  "isSEOEnabled" : true,
  "answer" : "The knowledge component of a good help center.",
  "seoDescription" : "Knowledge Base for your product",
  "title" : "Importance of a Knowledge Base",
  "seoTitle" : "Knowledge Base",
  "seoKeywords" : "Knowledge Base, Helpcenter",
  "status" : "DRAFT",
  "tags" : [ "tag1", "tag2", "tag4" ]
}'

Response Example

{
  "modifiedTime" : "2019-01-17T08:33:06.000Z",
  "departmentId" : "1000000012968",
  "dislikeCount" : "0",
  "modifierId" : "1000000016052",
  "likeCount" : "0",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "latestVersionModifierId" : "4000000000060",
  "ownerId" : "24073000000095005",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : "false",
  "quickEdit" : {
    "modifierId" : null,
    "modifiedBy" : null
  },
  "isLocked" : "true",
  "createdTime" : "2019-01-17T08:33:06.000Z",
  "id" : "1000000017031",
  "translationSource" : {
    "locale" : "fr",
    "version" : "2.0"
  },
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "reviewedBy" : null,
  "currentVersion" : "1.0",
  "tags" : [ "tag1", "tag2", "tag4" ],
  "commentCount" : "0",
  "sourceLocale" : "it-IT",
  "translationId" : "100000001293248",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/1000000017031",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "position" : "6",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "dislikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "permalink" : "importaance-of-asda-knowledge-base",
  "latestVersionModifiedBy" : {
    "photoURL" : null,
    "name" : "will smith",
    "id" : "4000000000060",
    "status" : "ACTIVE",
    "zuid" : "234544"
  },
  "status" : "Published",
  "attachments" : [ ],
  "reviewedTime" : null,
  "creatorId" : "1000000016052",
  "title" : "Importance of a Knowledge Base",
  "locale" : "en-US",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "Knowledge Base, Helpcenter",
    "isEnabled" : true,
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "summary" : "The knowledge component of a good help center. ",
  "owner" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000000095005/photo?orgId=54325703",
    "name" : "Zylker",
    "id" : "24073000000095005",
    "status" : "ACTIVE"
  },
  "isFollowing" : true,
  "myVote" : "null",
  "permission" : "REGISTEREDUSERS",
  "authorId" : "1000000016052",
  "usageCount" : "0",
  "rootCategoryId" : "24073000002378289",
  "templateUsageCount" : "0",
  "answer" : "The knowledge component of a good help center.",
  "latestVersion" : "1.0",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "1000000016052",
    "status" : "ACTIVE"
  },
  "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importaance-of-asda-knowledge-base",
  "attachmentCount" : "0",
  "category" : {
    "name" : "General",
    "id" : "1000000016397",
    "locale" : "ta"
  },
  "categoryId" : "1000000016397"
}

Get translations of an article

This API fetches the available translations of an article.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

optional,
range : >0

Index number starting from which the translations must be fetched

limit

Integer

optional,
range : 1-50

Number of translations to fetch

sortBy

String

optional

Key that sorts the articles based on a specific attribute:
createdTime,
or
modifiedTime

status

String

optional

Publishing status of the translation. Values allowed are Draft, Published, Review, Expired, Unpublished

permission

String

optional

Access permission for the article. Values allowed are ALL, REGISTEREDUSERS, AGENTS

authorId

Long

optional

ID of translation owner

modifiedTimeRange

timestamp

optional

Key that filters translations created within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

translationState

String

optional

Key that specifies the state of the translated article:
OUTDATED

UP-TO-DATE

GET /api/v1/articles/{article_id}/translations

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/7000001424353/translations?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2019-01-17T11:11:48.000Z",
    "departmentId" : "1000000012968",
    "dislikeCount" : "0",
    "modifierId" : "1000000016052",
    "creatorId" : "1000000016052",
    "likeCount" : "1",
    "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
    "latestVersionModifierId" : "4000000000060",
    "ownerId" : "24073000000095005",
    "title" : "Importance of a Knowledge Base",
    "locale" : "it-IT",
    "translationState" : "UP-TO-DATE",
    "isTrashed" : "false",
    "isLocked" : "true",
    "createdTime" : "2019-01-16T18:24:49.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "1000000016052",
      "status" : "ACTIVE"
    },
    "id" : "1000000017031",
    "viewCount" : "0",
    "translationSource" : {
      "locale" : "fr",
      "version" : "2.0"
    },
    "templateUsedUsersCount" : "2",
    "summary" : "Auto draft test ",
    "owner" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000000095005/photo?orgId=54325703",
      "name" : "Zylker",
      "id" : "24073000000095005",
      "status" : "ACTIVE"
    },
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "1000000016052",
      "status" : "ACTIVE"
    },
    "permission" : "REGISTEREDUSERS",
    "authorId" : "1000000016052",
    "usageCount" : "0",
    "rootCategoryId" : "24073000002378289",
    "commentCount" : "0",
    "sourceLocale" : "en",
    "templateUsageCount" : "0",
    "translationId" : "100000001234968",
    "latestVersion" : "3.0",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "1000000016052",
      "status" : "ACTIVE"
    },
    "isTemplate" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/1000000017031",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/tamil-for-article-1",
    "feedbackCount" : "0",
    "latestPublishedVersion" : "3.0",
    "attachmentCount" : "0",
    "position" : "6",
    "category" : {
      "name" : "General",
      "id" : "1000000016397",
      "locale" : "en"
    },
    "permalink" : "tamil-for-article-1",
    "latestVersionModifiedBy" : {
      "photoURL" : null,
      "name" : "will smith",
      "id" : "4000000000060",
      "status" : "ACTIVE",
      "zuid" : "234544"
    },
    "categoryId" : "1000000016397",
    "status" : "Published"
  } ]
}

Get article translation

This API fetches a specific translation of an article.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
version

String

optional

Version of the article translation

GET /api/v1/articles/{article_id}/translations/{locale}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/7000001424353/translations/ta?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-06-24T11:46:43.000Z",
  "departmentId" : "24073000002376045",
  "prev" : {
    "apiUrl" : "https://desk.zoho.com/api/v1/articles/175277000002814676/translations/en",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "id" : "175277000002814676",
    "title" : "ESZ",
    "permalink" : "esz",
    "locale" : "en"
  },
  "dislikeCount" : "0",
  "modifierId" : "4000000000059",
  "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
  "likeCount" : "0",
  "latestVersionModifierId" : "4000000000060",
  "ownerId" : "4000000000059",
  "translationState" : "UP-TO-DATE",
  "isTrashed" : false,
  "quickEdit" : {
    "modifierId" : "24073000007464062",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/24073000007464062/photo?orgId=54325703",
      "name" : "Tony Stark",
      "id" : "24073000007464062",
      "status" : "ACTIVE",
      "zuid" : "70425988"
    }
  },
  "createdTime" : "2020-06-24T11:46:43.000Z",
  "plainText" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions. Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket. With these, you're good to go. Go on, save the world from bad customer service!",
  "id" : "7000001424353",
  "translationSource" : null,
  "templateUsedUsersCount" : "2",
  "latestVersionStatus" : "Published",
  "author" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE"
  },
  "reviewedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "currentVersion" : "1.0",
  "commentCount" : "0",
  "tags" : [ "first ticket" ],
  "sourceLocale" : "en",
  "translationId" : "4000000017294",
  "isTemplate" : false,
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
  "feedbackCount" : "0",
  "latestPublishedVersion" : "1.0",
  "followersCount" : "0",
  "metrics" : {
    "templateUsageCount" : "0",
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "dislikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "position" : "6",
  "permalink" : "answering-your-first-ticket",
  "latestVersionModifiedBy" : {
    "photoURL" : null,
    "name" : "will smith",
    "id" : "4000000000060",
    "status" : "ACTIVE",
    "zuid" : "234544"
  },
  "status" : "Published",
  "next" : {
    "apiUrl" : "https://desk.zoho.com/api/v1/articles/175277000002814676/translations/en",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/4000000019059/en",
    "id" : "175277000002814676",
    "title" : "ESZ",
    "permalink" : "esz",
    "locale" : "en"
  },
  "attachments" : [ ],
  "reviewedTime" : "2020-06-24T11:46:43.000Z",
  "creatorId" : "4000000000059",
  "locale" : "en",
  "title" : "Answering your first ticket.",
  "expiryDate" : null,
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE"
  },
  "viewCount" : "0",
  "seo" : {
    "keywords" : "helpcenter, knowledge base",
    "isEnabled" : true,
    "description" : "Knowledge base",
    "title" : "Helpcenter and knowledge base"
  },
  "owner" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "summary" : "Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly. The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save ...",
  "isFollowing" : true,
  "myVote" : null,
  "permission" : "AGENTS",
  "authorId" : "4000000000059",
  "usageCount" : "0",
  "rootCategoryId" : "4000000017276",
  "templateUsageCount" : "0",
  "answer" : "<p>Zoho Desk packs a bunch of features that are expressly there to help you respond to tickets smartly.<br><br>The first of these, you've already discovered: Auto-Suggest Articles. Zoho Desk pulls up relevant articles on the ticket's content—so you can save time on frequently asked questions.<br><br>Every action that you can perform with respect to a ticket has a corresponding keyboard shortcut. With these, you can optimize the time you spend on each ticket. (And the shortcut to access these shortcuts is Shift + ? ).When you need to quickly consult a colleague, you can tag them in a ticket comment without having to leave this screen. That's like a quick chat, without even leaving your place, and with the full context of the ticket.<br><br>With these, you're good to go.<br><br>Go on, save the world from bad customer service!</p>",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE"
  },
  "latestVersion" : "1.0",
  "portalUrl" : "https://desk.zoho.com/portal/zylker/en/kb/articles/answering-your-first-ticket",
  "attachmentCount" : "0",
  "category" : {
    "name" : "General",
    "id" : "4000000017287",
    "locale" : "en"
  },
  "categoryId" : "4000000017287"
}

Search Tags

This API searches for the provided string from within the translation of articles.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
tag

string

required,
max chars : 70

Key that filters articles, based on tags

from

Integer

required,
default : 1,
range : >0

Index number starting from which the articles containing the search string must be fetched.

limit

Integer

required,
default : 10,
range : 1-50

The end limit to which the articles containing search string must be fetched.

categoryId

Long

optional

The articles to be searched based on the category ID

permission

String

optional

The articles of the users to be searched based on the provided permissions. For example: If the value is REGISTEREDUSERS, the search will only include articles created by registered users. The allowed values are ALL, REGISTEREDUSERS, AGENTS

status

String

optional

The articles that need to be searched based on the status. The allowed values are Draft, Review, Expired, Published, Unpublished

locale

String

optional

The articles to be searched based on the language.

include

string

optional,
max chars : 100

The search of the article includes countInfo or availableLocaleTranslations. The allowed values are countInfo or availableLocaleTranslations . Note : countInfo - Search the most popular. articlesavailableLocaleTranslations - search from the provided language.

isTrashed

String

required,
default : FALSE

The articles that are even in the recycle bin should be searched. The allowed values are TRUE, FALSE @ALL Note: To search in both locations, you can provide values as ALL.

authorId

Long

optional

The articles to be searched based on the ID of the article owner

GET /api/v1/articleTranslations/searchByTag

OAuth Scope

Desk.search.READ , Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleTranslations/searchByTag?orgId=2389290&authorId=1000000015894&searchString=tom&include=countInfo&limit=1&permission=ALL&status=Draft&isTrashed=TRUE&locale=ja-jp&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&isTemplate=false
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "countInfo" : {
    "rootCategory" : [ {
      "count" : "2",
      "id" : "141551000000292220"
    } ],
    "category" : [ {
      "count" : "2",
      "id" : "141551000001746017"
    } ],
    "totalCount" : "2"
  },
  "data" : [ {
    "modifiedTime" : "2025-01-20T11:07:34.000Z",
    "departmentId" : "2000000026140",
    "modifierId" : "2000000000521",
    "creatorId" : "2000000000521",
    "dislikeCount" : "0",
    "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
    "likeCount" : "0",
    "title" : "dev search nineth article",
    "ownerId" : "2000000000521",
    "latestVersionModifierId" : "2000000000521",
    "locale" : "en",
    "translationState" : "UP-TO-DATE",
    "expiryDate" : "2018-05-21T05:55:00.000Z",
    "isTrashed" : false,
    "isLocked" : false,
    "createdTime" : "2025-01-20T06:52:00.000Z",
    "modifiedBy" : {
      "photoURL" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/api/v1/agents/2000000000521/photo?orgId=24594186",
      "name" : "bhuvan vignesh",
      "id" : "2000000000521",
      "status" : "ACTIVE",
      "zuid" : "24588564"
    },
    "viewCount" : "3",
    "id" : "2000000352001",
    "translationSource" : null,
    "templateUsedUsersCount" : "2",
    "summary" : "dev search nineth article",
    "owner" : {
      "photoURL" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/api/v1/agents/2000000000521/photo?orgId=24594186",
      "name" : "bhuvan vignesh",
      "id" : "2000000000521",
      "status" : "ACTIVE",
      "zuid" : "24588564"
    },
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/api/v1/agents/2000000000521/photo?orgId=24594186",
      "name" : "bhuvan vignesh",
      "id" : "2000000000521",
      "status" : "ACTIVE",
      "zuid" : "24588564"
    },
    "permission" : "AGENTS",
    "authorId" : "2000000000521",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "2000000049873",
    "sourceLocale" : "en",
    "templateUsageCount" : "0",
    "translationId" : "2000000352003",
    "latestVersion" : "1.0",
    "createdBy" : {
      "photoURL" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/api/v1/agents/2000000000521/photo?orgId=24594186",
      "name" : "bhuvan vignesh",
      "id" : "2000000000521",
      "status" : "ACTIVE",
      "zuid" : "24588564"
    },
    "isTemplate" : false,
    "webUrl" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/support/bhuvanmac1/ShowHomePage.do#Solutions/dv/2000000352001/en",
    "portalUrl" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/portal/bhuvanmac1/en/kb/articles/dev-search-nineth-article",
    "feedbackCount" : "0",
    "latestPublishedVersion" : "1.0",
    "attachmentCount" : "0",
    "position" : "53",
    "permalink" : "dev-search-nineth-article",
    "category" : {
      "name" : "first cat sub sub section 1",
      "id" : "2000000353190",
      "locale" : "en"
    },
    "categoryId" : "2000000353190",
    "latestVersionModifiedBy" : {
      "photoURL" : "https://bhuvan-20295.tsi.zohocorpin.com:8888/api/v1/agents/2000000000521/photo?orgId=24594186",
      "name" : "bhuvan vignesh",
      "id" : "2000000000521",
      "status" : "ACTIVE",
      "zuid" : "24588564"
    },
    "status" : "Published"
  } ]
}

Search translations

This API searches for the provided string from within the translation of articles.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
searchString

String

required

The text that needs to be searched.

from

Integer

required,
default : 1,
range : >0

Index number starting from which the articles containing the search string must be fetched.

limit

Integer

required,
default : 10,
range : 1-50

The end limit to which the articles containing search string must be fetched.

categoryId

Long

optional

The articles to be searched based on the category ID

authorId

Long

optional

The articles to be searched based on the ID of the article owner

permission

String

optional

The articles of the users to be searched based on the provided permissions. For example: If the value is REGISTEREDUSERS, the search will only include articles created by registered users. The allowed values are ALL, REGISTEREDUSERS, AGENTS

status

String

optional

The articles that need to be searched based on the status. The allowed values are Draft, Review, Expired, Published, Unpublished

isTrashed

String

required,
default : FALSE

The articles that are even in the recycle bin should be searched. The allowed values are TRUE, FALSE Note: To search in both locations, you can provide both values as comma-separated.

locale

String

optional

The articles to be searched based on the language.

include

string

optional,
max chars : 100

The search of the article includes countInfo or availableLocaleTranslations. The allowed values are countInfo or availableLocaleTranslations . Note : countInfo - Search the most popular. articlesavailableLocaleTranslations - search from the provided language.

tag

string

optional,
max chars : 255

The articles to be searched based on the tags.

duration

String

optional

The articles to be searched based on the time since the article is created. The allowed values are yesterday, last_30_days, last_7_days, this_week, this_month, today

GET /api/v1/articleTranslations/search

OAuth Scope

Desk.search.READ , Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleTranslations/search?orgId=2389290&authorId=1000000015894&searchString=tom&include=countInfo&limit=1&permission=ALL&status=Draft&isTrashed=FALSE,TRUE&locale=ja-jp&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&isTemplate=false
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "countInfo" : {
    "duration" : [ {
      "name" : "yesterday",
      "count" : "0"
    }, {
      "name" : "last_30_days",
      "count" : "4"
    }, {
      "name" : "last_7_days",
      "count" : "4"
    }, {
      "name" : "this_month",
      "count" : "4"
    }, {
      "name" : "this_week",
      "count" : "0"
    }, {
      "name" : "today",
      "count" : "0"
    } ],
    "tag" : [ {
      "name" : "helpcenter",
      "count" : "4"
    } ],
    "category" : [ {
      "count" : "2",
      "id" : "1232000000192482"
    }, {
      "count" : "2",
      "id" : "1232000000149536"
    } ],
    "rootCategory" : [ {
      "count" : "2",
      "id" : "141551000000292220"
    } ],
    "totalCount" : "1"
  },
  "data" : [ {
    "modifiedTime" : "2019-12-31T09:45:52.000Z",
    "expirydate" : "2018-05-21T05:55:00.000Z",
    "departmentId" : "1000000012710",
    "modifierId" : "1000000020518",
    "creatorId" : "1000000020518",
    "dislikeCount" : "10",
    "likeCount" : "120",
    "templateLastUpdatedTime" : "2018-05-21T05:55:00.000Z",
    "latestVersionModifierId" : "4000000000060",
    "title" : "Tom and jerry",
    "ownerId" : "1000000015894",
    "locale" : "ja-JP",
    "translationState" : "UP-TO-DATE",
    "isTrashed" : false,
    "isLocked" : "true",
    "createdTime" : "2019-12-31T09:45:52.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000020518/photo?orgId=292828",
      "name" : "Tara",
      "id" : "1000000020518",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "1000000286001",
    "viewCount" : "0",
    "translationSource" : {
      "locale" : "fr",
      "version" : "2.0"
    },
    "templateUsedUsersCount" : "2",
    "summary" : "The entertainment king",
    "owner" : {
      "photoURL" : null,
      "name" : "Anamika",
      "id" : "1000000015894",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "latestVersionStatus" : "Draft",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000015894/photo?orgId=292828",
      "name" : "Anamika",
      "id" : "1000000015894",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "permission" : "ALL",
    "authorId" : "1000000015894",
    "usageCount" : "0",
    "commentCount" : "0",
    "rootCategoryId" : "1000000251006",
    "sourceLocale" : "ja-JP",
    "templateUsageCount" : "0",
    "translationId" : "1000000286003",
    "latestVersion" : "0.1",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000020518/photo?orgId=292828",
      "name" : "Tara",
      "id" : "1000000020518",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "isTemplate" : false,
    "webUrl" : "https://desk.zoho.com/support/magicmouse/ShowHomePage.do#Solutions/dv/1000000286001/locale/ja-JP",
    "feedbackCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/magicmouse/ja-JP/kb/articles/tom-jerry",
    "attachmentCount" : "0",
    "latestPublishedVersion" : null,
    "category" : {
      "name" : "Cartoon",
      "id" : "1000000251006"
    },
    "permalink" : "tom-jerry",
    "latestVersionModifiedBy" : {
      "photoURL" : null,
      "name" : "will smith",
      "id" : "4000000000060",
      "status" : "ACTIVE",
      "zuid" : "234544"
    },
    "categoryId" : "1000000251006",
    "status" : "Draft"
  } ]
}

Get attachments

This API fetches the files attached to an article translation.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

optional,
range : >0

Index number starting from which the article attachments must be fetched.

limit

Integer

optional,
range : 1-30

Number of attachments to fetch

GET /api/v1/articles/{article_id}/translations/{locale}/attachments

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/9000067589998/translations/en-us/attachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "dkx4q10b53a2b6e844addaec2723cd4b07092",
  "extension" : "txt",
  "name" : "aadas1_2_3_5_54_.txt",
  "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "createdTime" : "2018-07-10T22:45:05.865Z",
  "filesize" : "62"
}

Attach files to translation

This API attaches the files selected from the gallery to an article translation.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
attachmentIds

String Array

required

IDs of the attachments associated with the article

POST /api/v1/articles/{article_id}/translations/{locale}/associateAttachments

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/9876543456789/translations/en-us/associateAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "1vq0db78bc1203a0645e0a38373b3bddf8d40" ]
}'

Response Example

{
  "data" : [ {
    "resourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40",
    "extension" : "txt",
    "name" : "aadas1_2_3_5_54_.txt",
    "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
    "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
    "createdTime" : "2018-07-10T22:45:05.865Z",
    "filesize" : "62"
  } ]
}

Upload and associate attachments

This API uploads the files to the gallery section and attaches them to an article translation

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
attachmentType

String

required

Attachment type. Allowed values file, blob

File Params

file

Content-Type:multipart/form-data

attachment files for articles

POST /api/v1/articles/{article_id}/translations/{locale}/attachments

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/9000067589998/translations/en-us/attachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5&attachmentType=file
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "resourceId" : "dkx4q10b53a2b6e844addaec2723cd4b07092",
  "extension" : "txt",
  "name" : "aadas1_2_3_5_54_.txt",
  "viewUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=view&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "downloadUrl" : "https://desk.zoho.com/support/DocsDisplay?attachId=e91351dc29e5b7394d93c8deb91b642a0b498ee34174141d&action=download&zgId=17ec4c79299ee107dc91a236738b3d70&entityId=e91351dc29e5b739421838319e770b0a42acf79f93f757e8",
  "createdTime" : "2018-07-10T22:45:05.865Z",
  "filesize" : "62"
}

Dissociate attachments from translation

This API removes the file attachments from a translation.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
attachmentIds

String Array

required

IDs of the attachments associated with the article

POST /api/v1/articles/{article_id}/translations/{locale}/dissociateAttachments

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/dissociateAttachments?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "1vq0db78bc1203a0645e0a38373b3bddf8d40" ]
}'

Response Example

204

Like translation

This API adds a like (a positive reaction) to a translation

Credit: 1 credit/call

POST /api/v1/articles/{article_id}/translations/{locale}/like

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/like?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Dislike translation

This API adds a dislike (a negative reaction) to a translation.

Credit: 1 credit/call

POST /api/v1/articles/([0-9]+)/translations/{locale}/dislike

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/876546789087/translations/en-us/dislike?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get article statistics

This API fetches the basic insights related to an article

Credit: 1 credit/call

GET /api/v1/articles/{article_id}/insights

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/876546789087/insights?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "feedbackCount" : 0,
  "lastLikedTime" : "2018-11-20T14:03:07.000Z",
  "dislikeCount" : "0",
  "lastUsageTime" : null,
  "likeCount" : "1",
  "attachmentCount" : 0,
  "viewCount" : "0",
  "lastActivityTime" : "2018-11-20T14:03:07.000Z",
  "lastDislikedTime" : null,
  "usageCount" : "0",
  "commentCount" : 0
}

Get permalinks of translation

This API fetches the primary and secondary permalinks of a translation

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

GET /api/v1/articles/{article_id}/translations/{locale}/permalinks

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "primaryPermalink" : "how-to-open-account",
  "secondaryPermalinks" : [ "how-to-open-account-1", "how-to-open-account-3" ]
}

Update permalink of translation

This API updates the permalink of a translation and adds the old permalink to the redirection list

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
permalink

String

required

The permalink of Solution

isOldPermalinkNeeded

Boolean

optional

The variable that defines if permalink needs to be added to redirect list. By default, it is true

POST /api/v1/articles/{article_id}/translations/{locale}/permalinks/add

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks/add?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isOldPermalinkNeeded" : true,
  "permalink" : "how-to-open-account"
}'

Response Example

{
  "primaryPermalink" : "how-to-open-account",
  "secondaryPermalinks" : [ "how-to-open-account-1", "how-to-open-account-3", "how-to-open-account-2" ]
}

Remove redirection permalink from translation

This API removes the redirection permalink from the redirection list of a translation

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
permalink

String

required

The permalink of Solution

POST /api/v1/articles/{article_id}/translations/{locale}/permalinks/removeSecondaryPermalink

OAuth Scope

Desk.articles.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/permalinks/removeSecondaryPermalink?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "permalink" : "how-to-open-account-2"
}'

Response Example

204

Trash an article translation

This API moves an article translation to trash.

Credit: 1 credit/call

POST /api/v1/articles/{article_id}/translations/{locale}/moveToTrash

OAuth Scope

Desk.articles.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/1000000028029/translations/en-us/moveToTrash?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Download article translation attachment

This API downloads the attachment associated with article translation.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
inline

boolean

optional

Display content inline

GET /api/v1/articles/{articleId}/translations/{locale}/attachments/{attachmentId}/content

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/6000000072015/translations/ja-jp/attachments/b96b17694d63cd0f03eadbe4/content?orgId=2389290&authtoken=50c9bb96b17694d63cd0f03eadbe4ae5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Article Feedback

Article feedback refers to the text comments posted by users if they did not find a help article useful. This feedback can be used to improve the help article(s).

Example

{
  "ticket" : {
    "ticketNumber" : "163",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
    "id" : "22372000001389007",
    "deletedTime" : "2018-10-07T10:27:20.000Z",
    "deletedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
      "name" : "Zylker",
      "id" : "22372000000761001",
      "status" : "ACTIVE",
      "zuid" : "15223452"
    }
  },
  "contactId" : "22372000001386025",
  "contact" : {
    "photoURL" : null,
    "name" : "John",
    "id" : "22372000001386025"
  },
  "createdTime" : "2018-10-07T15:55:24.000Z",
  "id" : "22372000001386045",
  "resolution" : {
    "modifiedTime" : "2020-12-03T05:08:21.000Z",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "feedbackId" : "227800000075038",
    "createdTime" : "2020-12-03T05:08:21.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "id" : "22372340000106009",
    "resolution" : "Content has been modified in user basis",
    "contentType" : "PLAIN_TEXT"
  },
  "ticketId" : "22372000001389007",
  "content" : "Please add pricing details in tabular columns",
  "article" : {
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
    "id" : "22372000001370011",
    "locale" : "en",
    "title" : "Pricing details"
  },
  "status" : "RESOLVED"
}


List feedback comments on article translation

This API lists a particular number of comments received on a translation of an article, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Int

optional,
range : >0

Index number, starting from which the comments must be fetched. Default value is 1.

limit

Int

optional,
range : 1-50

Number of comments to list. Default value is 10.

sortBy

String

optional

Key that sorts the comments based on a specific attribute: createdTime. To sort the comments in descending order, append a '-' before the value

createdTimeRange

timestamp

optional

Key that filters comments created within a specific date and time range. Enter the dates in the ISO date format of 'yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ'

include

string

optional,
max chars : 100

Additional information related to the comments. Values allowed are: ticket, contact and resolution.

GET /api/v1/articles/{article_id}/translations/{locale}/feedbacks

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/22372000001370011/translations/en-us/feedbacks?from=1&limit=10&sortBy=-createdTime&include=ticket,contact,resolution
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "163",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
      "id" : "22372000001389007",
      "deletedTime" : "2018-10-07T10:27:20.000Z",
      "deletedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
        "name" : "Zylker",
        "id" : "22372000000761001",
        "status" : "ACTIVE",
        "zuid" : "15223452"
      }
    },
    "contactId" : "22372000001386025",
    "contact" : {
      "photoURL" : null,
      "name" : "John",
      "id" : "22372000001386025"
    },
    "createdTime" : "2018-10-07T15:55:24.000Z",
    "id" : "22372000001386045",
    "resolution" : {
      "modifiedTime" : "2020-12-03T05:08:21.000Z",
      "createdBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "feedbackId" : "227800000075038",
      "createdTime" : "2020-12-03T05:08:21.000Z",
      "modifiedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "id" : "22372340000106009",
      "resolution" : "Content has been modified in user basis",
      "contentType" : "PLAIN_TEXT"
    },
    "ticketId" : "22372000001389007",
    "content" : "Please add pricing details in tabular columns",
    "article" : {
      "author" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
      "id" : "22372000001370011",
      "locale" : "en",
      "title" : "Pricing details"
    },
    "status" : "RESOLVED"
  } ]
}

Get details of feedback comment

This API fetches the details of a particular feedback comment.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the comment. Values allowed are: ticket, contact and resolution.

GET /api/v1/articleFeedbacks/{feedback_id}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045?&include=ticket,contact,resolution
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "ticket" : {
    "ticketNumber" : "163",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
    "id" : "22372000001389007",
    "deletedTime" : "2018-10-07T10:27:20.000Z",
    "deletedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
      "name" : "Zylker",
      "id" : "22372000000761001",
      "status" : "ACTIVE",
      "zuid" : "15223452"
    }
  },
  "contactId" : "22372000001386025",
  "contact" : {
    "photoURL" : null,
    "name" : "John",
    "id" : "22372000001386025"
  },
  "createdTime" : "2018-10-07T15:55:24.000Z",
  "id" : "22372000001386045",
  "resolution" : {
    "modifiedTime" : "2020-12-03T05:08:21.000Z",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "feedbackId" : "227800000075038",
    "createdTime" : "2020-12-03T05:08:21.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "id" : "22372340000106009",
    "resolution" : "Content has been modified in user basis",
    "contentType" : "PLAIN_TEXT"
  },
  "ticketId" : "22372000001389007",
  "content" : "Please add pricing details in tabular columns",
  "article" : {
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
    "id" : "22372000001370011",
    "locale" : "en",
    "title" : "Pricing details"
  },
  "status" : "RESOLVED"
}

List feedback comments

This API lists a particular number of comments received on an article, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Int

optional,
range : >0

Index number, starting from which the comments must be fetched. Default value is 1.

limit

Int

optional,
range : 1-50

Number of comments to list. Default value is 10.

sortBy

String

optional

Key that sorts the comments based on a specific attribute: createdTime. To sort the comments in descending order, append a '-' before the value.

include

string

optional,
max chars : 100

Additional information related to the comments. Values allowed are: ticket, contact and resolution.

departmentIds

String

optional

Filter article feedback comments based on department ids

rootCategoryIds

String

optional

Filter article feedback comments based on rootCategoryIds

timeRange

String

optional

Key that filters comments created within a specific date and time range. Enter the time limit in the formats of
LAST_24_HRS,

LAST_7_DAYS,

LAST_30_DAYS,

LAST_365_DAYS
and
yyyy-MM-ddThh:mm:ss.SSSZ,yyyy-MM-ddThh:mm:ss.SSSZ
. Default value : LAST_7_DAYS.

locale

String

optional

Locale of an article translation in which feedback comments to be fetched

GET /api/v1/articleFeedbacks

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleFeedbacks?from=1&limit=10&sortBy=-createdTime&rootCategoryIds=2237200000137333&include=ticket,contact,resolution&timeRange=LAST_365_DAYS&locale=en
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "163",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
      "id" : "22372000001389007",
      "deletedTime" : "2018-10-07T10:27:20.000Z",
      "deletedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
        "name" : "Zylker",
        "id" : "22372000000761001",
        "status" : "ACTIVE",
        "zuid" : "15223452"
      }
    },
    "contactId" : "22372000001386025",
    "contact" : {
      "photoURL" : null,
      "name" : "John",
      "id" : "22372000001386025"
    },
    "createdTime" : "2018-10-07T15:55:24.000Z",
    "id" : "22372000001386045",
    "resolution" : {
      "modifiedTime" : "2020-12-03T05:08:21.000Z",
      "createdBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "feedbackId" : "227800000075038",
      "createdTime" : "2020-12-03T05:08:21.000Z",
      "modifiedBy" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "id" : "22372340000106009",
      "resolution" : "Content has been modified in user basis",
      "contentType" : "PLAIN_TEXT"
    },
    "ticketId" : "22372000001389007",
    "content" : "Please add pricing details in tabular columns",
    "article" : {
      "author" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
        "name" : "Charlie",
        "id" : "22372000000000063",
        "status" : "ACTIVE",
        "zuid" : "15224552"
      },
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
      "id" : "22372000001370011",
      "locale" : "en",
      "title" : "Pricing details"
    },
    "status" : "RESOLVED"
  } ]
}

Delete feedback comment

This API deletes a particular feedback comment from an article.

Credit: 1 credit/call

DELETE /api/v1/articleFeedbacks/{feedback_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Convert feedback comment into ticket

This API adds a feedback comment as a ticket in your help desk portal and assigns it to the author of the article.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
POST /api/v1/articleFeedbacks/{feedback_id}/addAsTicket

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articleFeedbacks/22372000001386045/addAsTicket
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "ticket" : {
    "ticketNumber" : "163",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/b34f0de640d72a1d8d1a6f7ca800abb8f3148ec5bcd90913",
    "id" : "22372000001389007",
    "deletedTime" : "2018-10-07T10:27:20.000Z",
    "deletedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agent/22372000000761001/photo",
      "name" : "Zylker",
      "id" : "22372000000761001",
      "status" : "ACTIVE",
      "zuid" : "15223452"
    }
  },
  "contactId" : "22372000001386025",
  "createdTime" : "2018-10-07T15:55:24.000Z",
  "id" : "22372000001386045",
  "ticketId" : "22372000001389007",
  "content" : "Please add pricing details in tabular columns",
  "article" : {
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/22372000000000063/photo?orgId=15224553",
      "name" : "Charlie",
      "id" : "22372000000000063",
      "status" : "ACTIVE",
      "zuid" : "15224552"
    },
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000001370011",
    "id" : "22372000001370011",
    "locale" : "en",
    "title" : "Pricing details"
  },
  "status" : "RESOLVED"
}

KBCategory

Categories are the top-level folders in the knowledge base, linked to a department. Using categories, you can organize help articles in your knowledge base. You can create categories, based on the products/services you offer or the nature of the issues your customers report.

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the category

parentCategoryId

long

ID of the parent category

helpcenterId

long

ID of the help center to which the knowledge base belongs

articleViewType

String

View to apply while listing help articles. Values allowed are: LISTVIEW and OVERVIEW.

isVisibleInHC

boolean

Key that specifies whether the category must be visible in the help center or not

isReview

boolean

Key that specifies whether review must be enabled for the category or not

reviewOwners

list

IDs of users who must review the category

associatedDepartments

list

List of departments to associate with the category

description

string

A brief description of the category

logo

long

Logo for the category

featuredCategory

boolean

Key that specifies whether the category must be featured in the help center or not

visibility

String

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, and NONE.

level

int

Navigation depth of the category

departmentId 

deprecated

long

ID of the department to associate with the category

childOrder

list

Order of sub-categories within the category

id

long

Unique ID of the category

articlesCount

int

Number of help articles under the category

workspaceId

long

ID of the Zoho Workdrive folder (Gallery) associated with the category

order

int

Position of the category in the overall order of categories of the same level

child

list

List of sub-categories

groupIds

list

List of group IDs

articlePermission

String

Visibility setting of articles, based on the visibility setting of the category

primaryDepartmentId

long

ID of the department to which the category belongs

moderationType

String

Type of moderation applied to the category. Values allowed are: NONE, ALL_ACTION, FIRST_ACTION

Example

{
  "modifiedTime" : "2020-06-24T11:46:42.000Z",
  "articleViewType" : "LISTVIEW",
  "visibility" : "NONE",
  "canCurrentUserModerate" : true,
  "groups" : [ ],
  "logoUrl" : null,
  "associatedDepartmentIds" : [ "4000000013244" ],
  "encryptedWorkspaceId" : "2d6dd8bff74bb212fa6a72a9d8ab5102f704587dd12c18d23a1747934db6b9266a742c45a7dc4c04c7b8abebb10f37508611a7fb7471f1de79d8fa5b104f3350",
  "helpcenterId" : "4000000016818",
  "isReviewEnabled" : false,
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-06-24T11:46:42.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Hill",
    "description" : null,
    "createdTime" : "2020-06-24T11:46:42.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Hill",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "4000000019051",
    "permalink" : "Hill",
    "locale" : "en",
    "categoryId" : "4000000017276"
  } ],
  "moderationType" : "ALL_ACTION",
  "name" : "Hill",
  "createdTime" : "2020-06-24T11:46:42.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Hill",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "primaryDepartmentId" : "5000000063894",
  "id" : "4000000017276",
  "followersCount" : "0",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "1",
  "workspaceId" : "a7iyye68bf585aebb477a936526f1ce7980b0"
}


Create root category

This API creates a root category (i.e., parent category) in your knowledge base.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the category

description

String

required

A brief description of the category

status

String

required,
default : HIDE_IN_HELPCENTER

Activation status of the category

visibility

String

required,
default : NONE

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, NONE, and PRIVATE_IP.

groupIds

list

optional

List of group IDs

articleViewType

String

required

View to apply while listing help articles. Values allowed are: LISTVIEW and OVERVIEW.

isReviewEnabled

boolean

required

Key that specifies whether the category must be reviewed or not

logoId

long

required

ID of the logo to set for the category

associatedDepartmentIds

list

optional

IDs of the departments associated with the category

primaryDepartmentId

long

optional

ID of the department to which the category belongs

helpcenterId

long

optional

ID of the help center to which the category belongs

moderationType

String

optional

Type of moderation applied to the category. Values allowed are: NONE, ALL_ACTION, FIRST_ACTION

POST /api/v1/kbRootCategories

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories?include=publishedArticleCount
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isReviewEnabled" : false,
  "articleViewType" : "LISTVIEW",
  "visibility" : "ALL_USERS",
  "moderationType" : "ALL_ACTION",
  "translations" : [ {
    "name" : "Zoho Desk",
    "description" : "A helpdesk software",
    "permalink" : "zoho-desk",
    "locale" : "en"
  } ],
  "name" : "Zoho Desk",
  "primaryDepartmentId" : "5000000063894",
  "logoId" : "25",
  "feedbackTicketConversionPreference" : {
    "departmentId" : "5000000063895",
    "assigneeId" : "5000000000059",
    "status" : "ENABLED"
  },
  "status" : "SHOW_IN_HELPCENTER",
  "associatedDepartmentIds" : [ "5000000063895" ]
}'

Response Example

{
  "modifiedTime" : "2020-01-02T15:26:51.000Z",
  "helpcenterId" : "5000000015871",
  "isReviewEnabled" : true,
  "isTrashed" : false,
  "translations" : [ {
    "modifiedTime" : "2020-01-02T15:24:42.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Zoho Desk",
    "description" : "A helpdesk software",
    "createdTime" : "2020-01-02T15:24:42.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000336004",
    "permalink" : "zoho-desk",
    "locale" : "en",
    "categoryId" : "5000000319037"
  } ],
  "moderationType" : "ALL_ACTION",
  "createdTime" : "2019-12-30T12:10:30.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "primaryDepartmentId" : "5000000063894",
  "id" : "5000000319037",
  "order" : "3",
  "workspaceId" : "asa432da353sda",
  "isFollowing" : true,
  "visibility" : "ALL_USERS",
  "articleViewType" : "LISTVIEW",
  "canCurrentUserModerate" : true,
  "groups" : [ ],
  "publishedArticleCount" : "23",
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "feedbackTicketConversionPreference" : {
    "departmentId" : "5000000063895",
    "assignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
      "name" : "Charlie Marlie",
      "id" : "5000000000059",
      "status" : "ACTIVE",
      "zuid" : "15224545"
    },
    "status" : "ENABLED"
  },
  "associatedDepartmentIds" : [ "5000000063895" ],
  "encryptedWorkspaceId" : "uhahs234dha2342342424da2342342342",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "name" : "Zoho Desk",
  "status" : "SHOW_IN_HELPCENTER"
}

Upload logo image

This API is used to upload an image to be used as logo

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

POST /api/v1/kbCategoryLogo

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbCategoryLogo
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "id" : "2029254000000178001"
}

Create a section

This API creates a section in your helpdesk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Section Name

parentCategoryId

Long

required

Parent id (either section or rootCategoryId) below which we need to create a section

description

String

optional

A short description of the section

logoId

long

optional

Logo for each category

status

String

optional,
default : HIDE_IN_HELPCENTER

Status of the section

visibility

String

optional,
default : NONE

Visibility of the section. Values allowed are
AGENTS
,
GROUP_USERS
,
ALL_USERS
,
NONE
,
PRIVATE_IP

groupIds

list

optional

group ids list

articlePermission

String

optional

To update the article permission based on category visibility

translations

list

required

Translation list of the category

POST /api/v1/kbSections

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbSections
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "articlePermission" : "ALL",
  "translations" : [ {
    "name" : "For Agents",
    "description" : "Section 1 description",
    "locale" : "en-us",
    "permalink" : "for-agents"
  } ],
  "name" : "For Agents",
  "description" : "Section 1 description",
  "parentCategoryId" : 5000000340014,
  "logoId" : "10",
  "status" : "SHOW_IN_HELPCENTER"
}'

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "isFollowing" : true,
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Update a section

This API updates a section in your helpdesk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Section Name

description

String

optional

A short description of the section

logoId

long

optional

Logo for each category

status

String

optional,
default : HIDE_IN_HELPCENTER

Status of the section

visibility

String

optional,
default : NONE

Visibility of the section. Values allowed are
AGENTS
,
GROUP_USERS
,
ALL_USERS
,
PRIVATE_IP
,
NONE

groupIds

list

optional

group ids list

articlePermission

String

optional

To update the article permission based on category visibility

PATCH /api/v1/kbSections/{sectionId}

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/kbSections/5000000340014
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "articlePermission" : "REGISTEREDUSERS",
  "translations" : [ {
    "name" : "section name updated",
    "locale" : "pl-pl"
  } ],
  "status" : "HIDE_IN_HELPCENTER"
}'

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "isFollowing" : true,
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Get a section

This API fetches a section in your helpdesk

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

String

optional

Include params are
publicArticlesCount
,
allArticlesCount
,
followersCount

GET /api/v1/kbSections/{sectionId}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbSections/5000000340014
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-01-07T01:15:14.000Z",
  "isFollowing" : true,
  "visibility" : "ALL_USERS",
  "description" : "Section 1 description",
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "rootCategoryId" : "5000000066427",
  "isTrashed" : false,
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "translations" : [ {
    "modifiedTime" : "2020-01-07T01:15:14.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "For Agents",
    "description" : "Section 1 description",
    "createdTime" : "2020-01-07T01:15:14.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000341019",
    "permalink" : "for-agents",
    "locale" : "en",
    "categoryId" : "5000000341017"
  } ],
  "name" : "For Agents",
  "createdTime" : "2020-01-07T01:15:14.000Z",
  "parentCategoryId" : "5000000340014",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "followersCount" : "0",
  "id" : "5000000341017",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "2"
}

Get root category

This API fetches the details of a root category.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

String

optional

Additional information related to the category. Values allowed are:
publicArticlesCount
,
allArticlesCount
,
followersCount
,
canCurrentUserReview
,
portalUrl

GET /api/v1/kbRootCategories/{rootCategoryId}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000340014
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-01-02T15:26:51.000Z",
  "helpcenterId" : "5000000015871",
  "isReviewEnabled" : true,
  "isTrashed" : false,
  "translations" : [ {
    "modifiedTime" : "2020-01-02T15:24:42.000Z",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Root category name",
    "description" : "description of root",
    "createdTime" : "2020-01-02T15:24:42.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "id" : "5000000336004",
    "permalink" : "root-category-name",
    "locale" : "en",
    "categoryId" : "5000000319037"
  } ],
  "moderationType" : "ALL_ACTION",
  "createdTime" : "2019-12-30T12:10:30.000Z",
  "modifiedBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "primaryDepartmentId" : "5000000063894",
  "id" : "5000000319037",
  "order" : "3",
  "workspaceId" : "asadasda",
  "isFollowing" : true,
  "visibility" : "ALL_USERS",
  "articleViewType" : "LISTVIEW",
  "canCurrentUserModerate" : true,
  "groups" : [ ],
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "feedbackTicketConversionPreference" : {
    "departmentId" : "5000000063895",
    "assignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
      "name" : "Charlie Marlie",
      "id" : "5000000000059",
      "status" : "ACTIVE",
      "zuid" : "15224545"
    },
    "status" : "ENABLED"
  },
  "associatedDepartmentIds" : [ "5000000063895" ],
  "encryptedWorkspaceId" : "uhahsdhada",
  "createdBy" : {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867",
    "status" : "ACTIVE",
    "zuid" : "343224"
  },
  "name" : "Root category name",
  "followersCount" : "0",
  "status" : "SHOW_IN_HELPCENTER"
}

Get a category tree

This API fetches the full tree of a root category in your helpdesk

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
locale

String

optional

Locale of the translated name

sortBy

String

optional

Sort order of the categories. Allowed values : name, order

includeTrash

Boolean

optional

Presence flag of the category

include

String

optional

Include params are
publicArticlesCount
,
allArticlesCount
,
publishedArticleCount
,
publishedArticleTemplateCount
,
portalUrl
,
followersCount

GET /api/v1/kbRootCategories/{rootCategoryId}/categoryTree

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000340014/categoryTree&sortBy=order&includeTrash=true&locale=en&include=publicArticlesCount,allArticlesCount,publishedArticleCount,publishedArticleTemplateCount
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "publishedArticleTemplateCount" : "4",
  "isFollowing" : true,
  "canCurrentUserModerate" : true,
  "visibility" : "ALL_USERS",
  "allArticlesCount" : "0",
  "description" : "test",
  "locale" : "en",
  "publishedArticleCount" : "23",
  "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
  "publicArticlesCount" : "0",
  "isTrashed" : false,
  "children" : [ {
    "publishedArticleTemplateCount" : "4",
    "isFollowing" : true,
    "visibility" : "ALL_USERS",
    "allArticlesCount" : "0",
    "description" : "Desk",
    "locale" : "en",
    "publishedArticleCount" : "23",
    "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
    "rootCategoryId" : "5000000066427",
    "publicArticlesCount" : "0",
    "isTrashed" : false,
    "children" : [ {
      "publishedArticleTemplateCount" : "4",
      "isFollowing" : true,
      "visibility" : "ALL_USERS",
      "allArticlesCount" : "0",
      "description" : "Section 2",
      "locale" : "en",
      "publishedArticleCount" : "23",
      "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
      "rootCategoryId" : "5000000066427",
      "publicArticlesCount" : "0",
      "isTrashed" : false,
      "children" : [ ],
      "translations" : [ {
        "name" : "section 2 en",
        "description" : null,
        "id" : "5000000341003",
        "permalink" : "section-2-en",
        "locale" : "en"
      } ],
      "name" : "Section 2",
      "parentCategoryId" : "5000000340014",
      "followersCount" : "0",
      "id" : "5000000341001",
      "status" : "SHOW_IN_HELPCENTER",
      "order" : "1"
    } ],
    "translations" : [ {
      "name" : "For Agents",
      "description" : null,
      "id" : "5000000340016",
      "permalink" : "for-agents",
      "locale" : "en"
    } ],
    "name" : "Desk",
    "parentCategoryId" : "5000000066427",
    "followersCount" : "0",
    "id" : "5000000340014",
    "status" : "SHOW_IN_HELPCENTER",
    "order" : "5"
  } ],
  "moderationType" : "ALL_ACTION",
  "translations" : [ {
    "name" : "Desk",
    "description" : "Helpdesk-software",
    "id" : "5000000265103",
    "permalink" : "desk",
    "locale" : "en"
  } ],
  "name" : "test",
  "followersCount" : "0",
  "id" : "5000000066427",
  "status" : "SHOW_IN_HELPCENTER",
  "order" : "1"
}

List root categories

This API lists a particular number of root categories, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
locale

String

optional

Language of the category

sortBy

String

optional

Key that sorts the categories, based on a specific attribute: name or order

from

Int

required,
default : 1,
range : >0

Index number, starting from which the categories must be fetched

limit

Int

required,
default : 50,
range : 1-700

Number of categories to list

searchValue

String

optional

Keyword for searching for a particular category

status

String

optional

Activation status of the category. Values allowed are: SHOW_IN_HELPCENTER, HIDE_IN_HELPCENTER, and DISABLED.

isTrashed

boolean

optional

Key that denotes whether the category is deleted or not

isReviewEnabled

boolean

optional

Key that specifies whether the category must be reviewed or not

visibility

String

optional

Visibility setting of the category. Values allowed are: AGENTS, GROUP_USERS, ALL_USERS, and NONE.

departmentId

String

optional

ID of the department associated with the category

helpcenterId

String

optional

ID of the help center to which the category belongs

include

String

optional

Additional information related to the category. Values allowed are:
publicArticlesCount
,
allArticlesCount
,
publishedArticleCount
,
allArticleTemplateCount
,
sectionsCount
,
followersCount

GET /api/v1/kbRootCategories

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories&include=publicArticlesCount,allArticlesCount,sectionsCount,allArticleTemplateCount,
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-01-05T13:18:07.000Z",
    "allArticlesCount" : "11",
    "helpcenterId" : "5000000015871",
    "isReviewEnabled" : false,
    "isTrashed" : false,
    "translations" : [ {
      "modifiedTime" : "2019-10-10T06:18:39.000Z",
      "createdBy" : {
        "photoURL" : null,
        "name" : "Zylker",
        "id" : "5000000015867",
        "status" : "ACTIVE",
        "zuid" : "343224"
      },
      "name" : "Zoho Desk",
      "description" : "A helpdesk software",
      "createdTime" : "2019-06-24T07:03:39.000Z",
      "modifiedBy" : {
        "photoURL" : null,
        "name" : "Zylker",
        "id" : "5000000015867",
        "status" : "ACTIVE",
        "zuid" : "343224"
      },
      "id" : "5000000265103",
      "permalink" : "zoho-desk",
      "locale" : "en",
      "categoryId" : "5000000066427"
    } ],
    "moderationType" : "ALL_ACTION",
    "createdTime" : "2019-06-24T07:03:39.000Z",
    "modifiedBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "primaryDepartmentId" : "5000000063894",
    "id" : "5000000066427",
    "order" : "1",
    "workspaceId" : "ponaz00368c36c9274809bf96849b392f8d67",
    "visibility" : "ALL_USERS",
    "articleViewType" : "LISTVIEW",
    "canCurrentUserModerate" : true,
    "groups" : [ ],
    "allArticleTemplateCount" : "2",
    "sectionsCount" : "7",
    "logoUrl" : "https://desk.zoho.com/support/App/build/fonts/certificate.svg",
    "feedbackTicketConversionPreference" : {
      "departmentId" : "5000000063895",
      "assignee" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/5000000000059/photo?orgId=15114553",
        "name" : "Charlie Marlie",
        "id" : "5000000000059",
        "status" : "ACTIVE",
        "zuid" : "15224545"
      },
      "status" : "ENABLED"
    },
    "associatedDepartmentIds" : [ "5000000063895" ],
    "publicArticlesCount" : "3",
    "encryptedWorkspaceId" : "04bd200bc14c4cac0c0026a0342c1f21263012407fa56109a37788e786a96ec0383c1eeb08849f9be78a6f7b8b8f31033dde60d41ad95443c6570636db1a9b20",
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "5000000015867",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "name" : "Zoho Desk",
    "followersCount" : "0",
    "status" : "SHOW_IN_HELPCENTER"
  } ]
}

Get review owners

This API fetches review owners of a root category in your helpdesk

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
sortBy

String

optional

Sort order of the owners. Allowed values : firstName, lastName

from

Int

required,
default : 1,
range : >0

Offset value

limit

Int

required,
default : 50,
range : 1-100

Number of objects

searchValue

String

optional

Search string

GET /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoURL" : null,
    "name" : "Zylker",
    "id" : "5000000015867"
  } ]
}

Add review owner

This API adds review owners of a root category in your helpdesk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
reviewOwnerIds

list

required

review owner ids list

POST /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners/add

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners/add
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reviewOwnerIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Remove review owner

This API removes review owners of a root category in your helpdesk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
reviewOwnerIds

list

required

review owner ids list

POST /api/v1/kbRootCategories/{rootCategoryId}/reviewOwners/remove

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/reviewOwners/remove
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reviewOwnerIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Add moderators

This API adds moderators to a root category in your helpdesk.

Note:
Moderators act as designated agents within the primary department with access to the Moderation Panel. They are responsible for reviewing and managing comments awaiting approval or flagged as spam.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
moderatorIds

list

required

IDs of the moderators you want to assign to the root category.

POST /api/v1/kbRootCategories/{rootCategoryId}/moderators/add

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/moderators/add
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "moderatorIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Remove moderators

This API removes moderators from a root category in your helpdesk.

Note:
Moderators act as designated agents within the primary department with access to the Moderation Panel. They are responsible for reviewing and managing comments awaiting approval or flagged as spam.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
moderatorIds

list

required

IDs of the moderators you want to remove from the root category.

POST /api/v1/kbRootCategories/{rootCategoryId}/moderators/remove

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/moderators/remove
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "moderatorIds" : [ "5000000015867" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "5000000015867",
    "errors" : null
  } ]
}

Add a permalink to a root catgeory

This API adds a permalink to a root category translation

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
permalink

String

required

The permalink of Solution

isOldPermalinkNeeded

Boolean

optional

The variable that defines if permalink needs to be added to redirect list. By default, it is true

POST /api/v1/kbRootCategories/{rootCategoryId}/translations/{locale}/permalinks/add

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/translations/en/add
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isOldPermalinkNeeded" : true,
  "permalink" : "new-permalink"
}'

Response Example

{
  "data" : [ {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : true,
    "createdTime" : "2020-05-01T14:16:43.000Z",
    "permalink" : "autobot"
  }, {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : false,
    "createdTime" : "2020-05-01T14:12:29.000Z",
    "permalink" : "transformers"
  }, {
    "createdBy" : {
      "photoURL" : null,
      "name" : "Zylker",
      "id" : "6000000016514",
      "status" : "ACTIVE",
      "zuid" : "343224"
    },
    "isPrimary" : false,
    "createdTime" : "2020-05-01T14:12:24.000Z",
    "permalink" : "flash"
  } ]
}

Remove a permalink of a root category

This API removes a permalink of a root category translation

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
permalink

String

required

The permalink of Solution

POST /api/v1/kbRootCategories/{rootCategoryId}/translations/{locale}/permalinks/remove

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/kbRootCategories/5000000066427/translations/en/remove
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "permalink" : "permalink-2"
}'

Response Example

{
  "primaryPermalink" : "new-permalink",
  "secondaryPermalinks" : [ "permalink-3" ]
}

Contracts

Contracts help you organize your desk commitments, enabling you to deliver more professional and dedicated customer service. By defining contracts, you can determine the level of service to offer and set the contract period for an account or a product.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the contract

associatedSLAId 

deprecated

long

ID of the SLA associated with the contract

associatedSupportPlanId

long

ID of the Associated Support Plan

accountId 

deprecated

long

ID of the account associated with the contract

departmentId

long

ID of the department to which the contract belongs

productId 

deprecated

long

ID of the product associated with the contract

contractNumber

string

Serial number of the contract

notificationAgentIds

list

List of agents to be notified

notifyBefore

int

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

notifyOn

date

The date when the contract expiry notification must be sent

startDate

date

Date from which the contract is valid

endDate

date

Date until which the contract is valid

ownerId

long

ID of the contract owner

createdBy

string

User who created the contract

modifiedBy

string

User who modified the contract

createdTime

timestamp

Time of creating the contract

modifiedTime

timestamp

Time of modifying the contract

contractName

string

Name of the contract

description

string

A short description of the contract

customFields 

deprecated

list

User-defined fields associated with the contract

cf

list

User-defined fields associated with the contract

sla

list

SLA fields associated with the contract

account

list

Account fields associated with the contract

product

list

Product fields associated with the contract

Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-01-15T11:13:04.000Z",
  "product" : {
    "id" : "500000001290",
    "productName" : "Desk"
  },
  "cf" : {
    "cf_mycustomfield1" : "hello"
  },
  "contractStatus" : "ACTIVE",
  "productId" : "5000000009328",
  "endDate" : "2019-01-10",
  "departmentId" : "5000000007235",
  "notifyBefore" : "5",
  "contractNumber" : "101",
  "description" : null,
  "sla" : {
    "name" : "Gold SLAs",
    "id" : "10000000062047"
  },
  "ownerId" : "5000000009148",
  "notificationAgentIds" : [ "5000000009148" ],
  "accountId" : "5000000009326",
  "createdBy" : "5000000009148",
  "notifyOn" : "2019-01-05",
  "createdTime" : "2018-01-10T11:29:41.000Z",
  "contractName" : "Ticket Resolution Contract for 5 Star Crisps",
  "modifiedBy" : "5000000009148",
  "id" : "5000000009331",
  "supportPlan" : {
    "supportType" : "UNLIMITED_SUPPORT",
    "name" : "SupportPlan with Gold SLAs",
    "id" : "5000000007671",
    "status" : "ACTIVE"
  },
  "startDate" : "2018-01-10",
  "account" : {
    "website" : "https://www.zoho.com",
    "accountName" : "Zoho",
    "id" : "500000008909"
  }
}


Get a contract

This API fetches a single contract from your helpdesk.

Credit: 1 credit/call

GET api/v1/contracts/{{contract_id}}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contracts/5000000009331
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-01-15T11:13:04.000Z",
  "product" : {
    "id" : "500000001290",
    "productName" : "Desk"
  },
  "cf" : {
    "cf_mycustomfield1" : "hello"
  },
  "contractStatus" : "ACTIVE",
  "productId" : "5000000009328",
  "endDate" : "2019-01-10",
  "departmentId" : "5000000007235",
  "notifyBefore" : "5",
  "contractNumber" : "101",
  "description" : null,
  "sla" : {
    "name" : "Gold SLAs",
    "id" : "10000000062047"
  },
  "ownerId" : "5000000009148",
  "notificationAgentIds" : [ "5000000009148" ],
  "accountId" : "5000000009326",
  "createdBy" : "5000000009148",
  "notifyOn" : "2019-01-05",
  "createdTime" : "2018-01-10T11:29:41.000Z",
  "contractName" : "Ticket Resolution Contract for 5 Star Crisps",
  "modifiedBy" : "5000000009148",
  "id" : "5000000009331",
  "supportPlan" : {
    "supportType" : "UNLIMITED_SUPPORT",
    "name" : "SupportPlan with Gold SLAs",
    "id" : "5000000007671",
    "status" : "ACTIVE"
  },
  "startDate" : "2018-01-10",
  "account" : {
    "website" : "https://www.zoho.com",
    "accountName" : "Zoho",
    "id" : "500000008909"
  }
}

List all contracts

To get a list of contracts

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

The starting index point to fetch the contracts

limit

integer

optional,
range : 1-100

The total number of contracts to be fetched

viewId

integer

optional

ID of the view to apply while fetching the resources

departmentIds

long

optional

IDs of the departments from which the contract must be fetched. Supports a maximum of 10 department ids, each separated by a comma.

accountId
see documentation

long

optional

ID of the account associated with the contract

ownerIds

long

optional

IDs of the owners from which the contract must be fetched. Supports a maximum of 10 owner IDs, each separated by a comma.

contractName

string

optional,
max chars : 80

Fetches the contracts that matches the Starting Name of Contract with provided string

sortBy

string

optional,
max chars : 100

Parameter that sorts contracts by one of these attributes: 
accountName,
 
contractName,
 
contractEndDate,

contractStartDate,
 
createdTime, or
 
modifiedTime.
The default order of sorting is ascending. To sort in descending order, prefix a - with the parameter.

include
see documentation

string

optional,
max chars : 100

Allowed Value is: accounts

GET api/v1/contracts

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contracts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "FUTURE",
    "productId" : null,
    "endDate" : "2018-11-10",
    "departmentId" : "10000000010762",
    "contractName" : "C2",
    "id" : "10000000270023",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Gold SLAs",
      "id" : "5000000007671",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-10-10"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-10",
    "departmentId" : "10000000010762",
    "contractName" : "New",
    "id" : "10000000270045",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Premium SLAs",
      "id" : "5000000007675",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-09-09"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272001",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2018-12-11",
    "departmentId" : "10000000010762",
    "contractName" : "THIRD",
    "id" : "10000000272013",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Gold SLAs",
      "id" : "5000000007671",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272037",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2019-03-11",
    "departmentId" : "10000000010762",
    "contractName" : "Fourth ACC",
    "id" : "10000000272049",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Silver SLAs",
      "id" : "5000000007673",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272071",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-12",
    "departmentId" : "10000000010762",
    "contractName" : "old",
    "id" : "10000000272083",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Gold SLAs",
      "id" : "5000000007671",
      "status" : "ACTIVE"
    },
    "startDate" : "2017-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2018-09-30",
    "departmentId" : "10000000010762",
    "contractName" : "FUTURE 1",
    "id" : "10000000273003",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Silver SLAs",
      "id" : "5000000007673",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-09-15"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "FUTURE",
    "productId" : null,
    "endDate" : "2018-12-11",
    "departmentId" : "10000000010762",
    "contractName" : "FUTURE 3",
    "id" : "10000000273025",
    "ownerId" : "10000000012902",
    "supportPlan" : {
      "supportType" : "UNLIMITED_SUPPORT",
      "name" : "SupportPlan with Gold SLAs",
      "id" : "5000000007671",
      "status" : "ACTIVE"
    },
    "startDate" : "2018-11-11"
  } ]
}

Create a contract

This API creates a contract in your helpdesk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
associatedSLAId 
deprecated

long

optional

ID of the SLA associated with the contract

associatedSupportPlanId

long

optional

ID of the Associated Support Plan

accountId 
deprecated

long

required

ID of the account associated with the contract

departmentId

long

required

ID of the department to which the contract belongs

productId 
deprecated

long

optional

ID of the product associated with the contract

contractNumber

string

optional,
max chars : 50

Serial number of the contract

notificationAgentIds

list

optional

List of agents to be notified

notifyBefore

int

optional

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

startDate

date

required

Date from which the contract is valid

endDate

date

optional

Date until which the contract is valid

ownerId

long

required

ID of the contract owner

contractName

string

required,
max chars : 80

Name of the contract

description

string

optional,
max chars : 65535

A short description of the contract

customFields 
deprecated

list

optional

User-defined fields associated with the contract

cf

list

optional

User-defined fields associated with the contract

sla

list

optional

SLA fields associated with the contract

account

list

optional

Account fields associated with the contract

product

list

optional

Product fields associated with the contract

POST /api/v1/contracts

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contracts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "cf" : {
    "cf_mycustomfield1" : "Some Value"
  },
  "productId" : null,
  "endDate" : "2019-07-23",
  "departmentId" : "10000000013228",
  "notifyBefore" : "3",
  "description" : "My Description",
  "contractNumber" : 9495,
  "associatedSupportPlanId" : "5000000007671",
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "contractName" : "MyContractName",
  "startDate" : "2018-07-23"
}'

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-07-24T07:31:57.075Z",
  "product" : {
    "id" : "500000001290",
    "productName" : "Desk"
  },
  "cf" : {
    "cf_mycustomfield1" : "Some Value"
  },
  "contractStatus" : "ACTIVE",
  "productId" : null,
  "endDate" : "2019-07-23",
  "departmentId" : "10000000013228",
  "notifyBefore" : "3",
  "contractNumber" : "9495",
  "description" : "My Description",
  "sla" : {
    "name" : "Gold SLAs",
    "id" : "10000000062047"
  },
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "createdBy" : "10000000012816",
  "notifyOn" : "2019-07-20",
  "createdTime" : "2018-07-24T07:31:57.075Z",
  "contractName" : "MyContractName",
  "modifiedBy" : "10000000012816",
  "id" : "10000000082016",
  "supportPlan" : {
    "supportType" : "UNLIMITED_SUPPORT",
    "name" : "SupportPlan with Gold SLAs",
    "id" : "5000000007671",
    "status" : "ACTIVE"
  },
  "startDate" : "2018-07-23",
  "account" : {
    "website" : "https://www.zoho.com",
    "accountName" : "Zoho",
    "id" : "500000008909"
  }
}

Update a contract

This API updates the details of an existing contract.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
associatedSLAId 
deprecated

long

optional

ID of the SLA associated with the contract

associatedSupportPlanId

long

optional

ID of the Associated Support Plan

accountId 
deprecated

long

optional

ID of the account associated with the contract

departmentId

long

optional

ID of the department to which the contract belongs

productId 
deprecated

long

optional

ID of the product associated with the contract

contractNumber

string

optional,
max chars : 50

Serial number of the contract

notificationAgentIds

list

optional

List of agents to be notified

notifyBefore

int

optional

Number of days before endDate when notifications about contract expiry must be sent to the agents concerned

startDate

date

optional

Date from which the contract is valid

endDate

date

optional

Date until which the contract is valid

ownerId

long

optional

ID of the contract owner

contractName

string

optional,
max chars : 80

Name of the contract

description

string

optional,
max chars : 65535

A short description of the contract

customFields 
deprecated

list

optional

User-defined fields associated with the contract

cf

list

optional

User-defined fields associated with the contract

sla

list

optional

SLA fields associated with the contract

account

list

optional

Account fields associated with the contract

product

list

optional

Product fields associated with the contract

PATCH /api/v1/contracts/{contract_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/contracts/10000000078091
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "cf" : {
    "cf_mycustomfield1" : "Some Update Value"
  },
  "productId" : null,
  "endDate" : "2019-09-15",
  "departmentId" : "10000000013228",
  "notifyBefore" : "5",
  "description" : "My Description Updated",
  "contractNumber" : 9496,
  "associatedSupportPlanId" : "5000000007671",
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "contractName" : "My Updated Contract Name",
  "startDate" : "2018-08-14"
}'

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-07-24T07:33:11.728Z",
  "product" : {
    "id" : "500000001290",
    "productName" : "Desk"
  },
  "cf" : {
    "cf_mycustomfield1" : "Some Update Value"
  },
  "contractStatus" : "ACTIVE",
  "productId" : null,
  "endDate" : "2019-09-15",
  "departmentId" : "10000000013228",
  "notifyBefore" : "5",
  "contractNumber" : "9496",
  "description" : "My Description Updated",
  "sla" : {
    "name" : "Gold SLAs",
    "id" : "5000000007671"
  },
  "ownerId" : "10000000012816",
  "notificationAgentIds" : [ "10000000012816" ],
  "accountId" : "10000000012985",
  "createdBy" : "10000000012816",
  "notifyOn" : "2019-09-10",
  "createdTime" : "2018-07-24T07:31:57.000Z",
  "contractName" : "My Updated Contract Name",
  "modifiedBy" : "10000000012816",
  "id" : "10000000082016",
  "supportPlan" : {
    "supportType" : "UNLIMITED_SUPPORT",
    "name" : "SupportPlan with Gold SLAs",
    "id" : "5000000007671",
    "status" : "ACTIVE"
  },
  "startDate" : "2018-08-14",
  "account" : {
    "website" : "https://www.zoho.com",
    "accountName" : "Zoho",
    "id" : "500000008909"
  }
}

Delete contracts

This API moves contracts to the Recycle Bin of your help desk portal

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
contractIds

list

required

IDs of the contracts that you want to delete

POST api/v1/contracts/moveToTrash

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contracts/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contractIds" : [ "10000000014816", "1000000001243", "10000000018818" ]
}'

Response Example

204

Update many contracts

This API updates multiple contracts at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

required

Key that denotes if the field is a user-defined field or not

POST /api/v1/contracts/updateMany

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contracts/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "contractNumber",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "123"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Timetracking

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.

ATTRIBUTES

Attribute Name
Data Type
Description
isTimeTracking

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.

depId

long

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

Key that returns if the time tracked is billable or not.

billingType

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

fixedCost

Double

Cost fixed for either billing category - by ticket or by agent.

agents

list

List of agents in the department

profiles

list

List of user profiles defined in the department

timerAction

String

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

list

Activity preference(s)

ticketPreference

list

Ticket preference(s)

Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "timerAction" : "ADD",
  "isBillable" : true,
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}


Create TimeTrackSettings

This API adds a TimeTracking configuration to your helpdesk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isTimeTracking

boolean

required

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.

depId

long

required

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

optional

Key that returns if the time tracked is billable or not.

billingType

String

optional

Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

fixedCost

Double

optional

Cost fixed for either billing category - by ticket or by agent.

agents

list

optional

List of agents in the department

profiles

list

optional

List of user profiles defined in the department

timerAction

String

optional

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

list

optional

Activity preference(s)

ticketPreference

list

optional

Ticket preference(s)

POST /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/timeTrackSettings
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}'

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : false,
    "isAutoPause" : true,
    "isAutoTimer" : true,
    "isHideTimeTracking" : false
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : true,
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : true,
    "canAutoTrackCalls" : true
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : true,
  "isBillable" : true,
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

Update TimeTrackSettings

This API updates an existing TimeTracking configuration.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isTimeTracking

boolean

optional

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.

depId

long

optional

ID of the department in which time tracking must be enabled or disabled.

isBillable

boolean

optional

Key that returns if the time tracked is billable or not.

billingType

String

optional

Type of billing configured. Values supported are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT and SPECIFIC_COST_PER_PROFILE

fixedCost

Double

optional

Cost fixed for either billing category - by ticket or by agent.

agents

list

optional

List of agents in the department

profiles

list

optional

List of user profiles defined in the department

timerAction

String

optional

Action that the active timers in the department must perform. Values supported are ADD and DISCARD

activityPreference

list

optional

Activity preference(s)

ticketPreference

list

optional

Ticket preference(s)

PUT /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/timeTrackSettings
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "timerAction" : "ADD",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}'

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

Get TimeTrack Settings

This API fetches the details of the TimeTrack Settings configured in your helpdesk.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
depId

long

required

ID of the department

GET /api/v1/timeTrackSettings

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/timeTrackSettings
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "ticketPreference" : {
    "autoTrackAction" : {
      "fieldUpdate" : true,
      "onChatComplete" : true,
      "onRemoteAssist" : true,
      "commentActions" : true,
      "approvalActions" : true,
      "sendReply" : true,
      "manualDraft" : true,
      "resolutionActions" : true,
      "attachmentActions" : true
    },
    "isReviewTime" : "false",
    "isAutoPause" : "true",
    "isAutoTimer" : "true",
    "isHideTimeTracking" : "false"
  },
  "billingType" : "SPECIFIC_COST_PER_AGENT",
  "activityPreference" : {
    "isTasksEnabled" : "true",
    "trackMode" : "CONSECUTIVE",
    "isEventsEnabled" : "true",
    "canAutoTrackCalls" : "true"
  },
  "fixedCost" : "1000",
  "profiles" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ],
  "depId" : "1892000000006907",
  "isTimeTracking" : "true",
  "isBillable" : "true",
  "agents" : [ {
    "cost" : "100",
    "id" : "1"
  }, {
    "cost" : "200",
    "id" : "2"
  } ]
}

List history details of billing TimeTrack Settings

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

Query Params

Param Name
Data Type
Description
depId

long

required

ID of the department from which the history must be fetched.

from

int

optional

Index number, starting from which the events must be fetched.

limit

int

optional,
range : 1-50

Number of events to be fetched.

include

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/timeTrackHistory

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/timeTrackSettings/history?depId=15000000044059&include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : [ {
      "photoURL" : "'https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20'",
      "name" : "meenakshi"
    } ],
    "modifiedTime" : "2018-02-19T12:53:49.000Z",
    "agentId" : "15000000009148",
    "name" : "AGENT_DELETED",
    "modifiedBy" : "15000000009148"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166891&nps=404&exp=600'",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-19T12:53:49.000Z",
    "agentId" : "15000000009321",
    "cost" : "100",
    "name" : "AGENT_ADDED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    }
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-19T12:45:17.000Z",
    "agentId" : "15000000009148",
    "cost" : "100",
    "name" : "AGENT_ADDED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    }
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "SPECIFIC_COST_PER_AGENT",
    "modifiedTime" : "2018-02-19T12:45:17.000Z",
    "name" : "BILLING_TYPE_CHANGED",
    "modifiedBy" : "15000000009148",
    "oldValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-09T09:09:10.000Z",
    "name" : "BILLING_PREFERENCE_ENABLED",
    "modifiedBy" : "15000000009148"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : null,
    "modifiedTime" : "2018-02-09T09:08:57.000Z",
    "name" : "FIXED_COST_ENTERED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedTime" : "2018-02-09T09:08:57.000Z",
    "name" : "BILLING_TYPE_SELECTED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "modifiedTime" : "2018-02-09T07:50:01.000Z",
    "name" : "BILLING_PREFERENCE_DISABLED",
    "modifiedBy" : "15000000009148",
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "1300",
    "modifiedTime" : "2018-02-09T05:13:00.000Z",
    "name" : "FIXED_COST_ENTERED",
    "modifiedBy" : "15000000009148",
    "oldValue" : null,
    "modifiedAgent" : null
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=5166343&nps=404&exp=20",
      "name" : "meenakshi"
    },
    "newValue" : "FIXED_COST_FOR_AGENTS",
    "modifiedTime" : "2018-02-09T05:13:00.000Z",
    "name" : "BILLING_TYPE_CHANGED",
    "modifiedBy" : "15000000009148",
    "oldValue" : "FIXED_COST_FOR_TICKETS",
    "modifiedAgent" : null
  } ]
}

Views

A view is a customized display of help desk data that helps users organize and prioritize information based on specific criteria, enabling them to interact with data that aligns with their needs.

List Views

This API lists the different views configured for a specific module or for all modules in your help desk portal.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module
see documentation

string

required,
max chars : 100

Module Name (for which the view configured and need to be fetched)

departmentId
see documentation

long

optional

Allowed values are : Valid Department Id.

GET /api/v1/views

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/views?module=tickets&departmentId=981212321312321
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "isCustomView" : false,
    "name" : "All Tasks",
    "id" : "4000000007834"
  }, {
    "isCustomView" : false,
    "name" : "My Tasks",
    "id" : "4000000007836"
  }, {
    "isCustomView" : false,
    "name" : "My Open Tasks",
    "id" : "4000000007838"
  }, {
    "isCustomView" : false,
    "name" : "Completed Tasks",
    "id" : "4000000007840"
  }, {
    "isCustomView" : false,
    "name" : "Open Tasks",
    "id" : "4000000007842"
  }, {
    "isCustomView" : false,
    "name" : "Overdue Tasks",
    "id" : "4000000007844"
  }, {
    "isCustomView" : false,
    "name" : "Todays Tasks",
    "id" : "4000000007846"
  }, {
    "isCustomView" : false,
    "name" : "Tomorrows Tasks",
    "id" : "4000000007848"
  }, {
    "isCustomView" : false,
    "name" : "Today+Overdue Tasks",
    "id" : "4000000007850"
  }, {
    "isCustomView" : false,
    "name" : "Next7days+Overdue Tasks",
    "id" : "4000000007852"
  } ]
}

Add Star View

This API stars a view, enabling quick access to the view.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

POST /api/v1/views/{view_id}/star

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/views/4000000007824/star?departmentId=981212321312321
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Remove Star View

This API unstars a view, disabling quick access to the view.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Allowed values are : Valid Department Id.

POST /api/v1/starredViews/{view_id}/unstar

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/starredViews/4000000007824/unstar?departmentId=981212321312321
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List Starred Views

This API lists the starred views in a module. Number of resources in the starred view is displayed only for the Tickets module.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module
see documentation

string

required,
max chars : 100

Module associated with the view. Values allowed are:tickets, tasks, contacts, accounts, activities, calls, events or contracts.

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

GET /api/v1/starredViews

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/starredViews?module=tickets&departmentId=4000000007123
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "starredViews" : [ {
    "isCustomView" : false,
    "name" : "All Tickets",
    "count" : "40",
    "id" : "4000000007834"
  }, {
    "isCustomView" : false,
    "name" : "Open Tickets",
    "count" : "22",
    "id" : "4000000007844"
  } ],
  "module" : "tickets"
}

Starred Views Reorder

This API helps reorder the starred views in a module.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
module
see documentation

string

required,
max chars : 100

Module associated with the view. Values allowed are: tickets, tasks, contacts, accounts, contracts, activities, calls or events.

departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

Attributes

Param Name
Data Type
Description
starredViewIds

list

required

IDs of the starred views.

PUT /api/v1/starredViews/order

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/starredViews/order?departmentId=981212321312321&module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "starredViewIds" : [ "4000000007808", "4000000007810", "4000000007818", "4000000007820", "4000000007828", "4000000007830", "4000000007848", "4000000007850" ]
}'

Response Example

204

Get Last Accessed View

This API fetches the view last accessed by the user in the module and department specified in the request.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

module

String

required

Module associated with the view. Values allowed are:tickets, tasks, contacts, accounts, activities, calls, events or custom module.

GET /api/v1/lastAccessedView

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/lastAccessedView?departmentId=4000000007069&module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : {
    "preference" : {
      "records" : "20",
      "sortField" : {
        "name" : "createdTime",
        "order" : "ascending"
      },
      "receivedIn" : "allDays"
    },
    "name" : "My Records",
    "id" : "4000000008143"
  }
}

Update Last Accessed View

This API updates the view last accessed by the user in the module and department specified in the request.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID of the department in which the view(s) is (are) configured.

PUT /api/v1/lastAccessedView/([0-9]+)

OAuth Scope

Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/lastAccessedView/4000000008143?departmentId=4000000007069
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Search across modules

This API returns information from all modules or a specific module, based on the value of the module query param.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
searchStr

String

optional

Keyword or phrase to search

module

String

optional

Module to search in: tickets, accounts, contacts or tasks. The default response includes all modules.

departmentId

long

optional

ID of the department from which the resource must be fetched

from

int

optional,
default : 0,
range : 0-4999

Index number, starting from which the resources must be searched

limit

int

optional,
default : 10,
range : 1-5000

Number of resources to return in the search result

sortBy

String

optional

Sort by a specific attribute: relevance or modifiedTime

GET /api/v1/search?searchStr={searchStr}&departmentId={departmentId}&from={from}&limit={limit}&sortBy={sortField}

OAuth Scope

Desk.search.READ , Desk.tickets.READ , Desk.contacts.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/search?searchStr=zylker&from=0&limit=10&sortBy=modifiedTime
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "subject" : "Zylker ticket",
    "departmentId" : "4000000007043",
    "dueDate" : null,
    "channel" : "Phone",
    "onholdTime" : null,
    "sharedDepartments" : [ ],
    "closedTime" : null,
    "number" : "104",
    "contact" : {
      "phone" : null,
      "mobile" : "9876543210",
      "name" : "Stephen",
      "id" : "4000000013012",
      "type" : null,
      "email" : null,
      "account" : {
        "website" : null,
        "name" : "Zylker Accounts",
        "id" : "4000000008850"
      }
    },
    "createdTime" : "2016-06-27T07:22:52.000Z",
    "id" : "4000000016009",
    "department" : {
      "name" : "Testing",
      "id" : "4000000007043"
    },
    "email" : null,
    "customerResponseTime" : "2016-06-27T07:22:52.117Z",
    "cf" : {
      "cf_featureRequest" : false,
      "cf_region" : "Asia"
    },
    "productId" : "4000000013043",
    "contactId" : "4000000013012",
    "module" : "tickets",
    "threadCount" : "0",
    "team" : {
      "name" : "TestingTeam",
      "id" : "4000000007235",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/4000000007235/logo?orgId=11278831"
    },
    "priority" : null,
    "assigneeId" : "4000000008692",
    "commentCount" : "0",
    "phone" : null,
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "4000000008692",
      "zuid" : "10657727"
    },
    "status" : "Open"
  }, {
    "cf" : {
      "cf_followUpDate" : "2016-07-07T19:30:00.000Z",
      "cf_severity" : "High"
    },
    "ticket" : null,
    "subject" : "Wifi adapter not working in zylker",
    "completedTime" : null,
    "module" : "tasks",
    "dueDate" : "2016-06-27T19:30:00.000Z",
    "description" : null,
    "ownerId" : "4000000008692",
    "priority" : "High",
    "isCommented" : false,
    "createdBy" : "4000000008692",
    "contact" : null,
    "createdTime" : "2016-06-27T06:39:48.000Z",
    "id" : "4000000013065",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "category" : null,
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "ticketId" : null,
    "status" : "Not Started"
  }, {
    "website" : null,
    "phone" : null,
    "accountName" : "Zylker India",
    "customFields" : {
      "city" : "Delhi",
      "state" : "India"
    },
    "module" : "accounts",
    "id" : "4000000013027",
    "email" : null
  }, {
    "lastName" : "Stephen",
    "accountId" : "4000000008850",
    "firstName" : "Henry",
    "photoURL" : null,
    "phone" : null,
    "customFields" : {
      "customerSince" : "2011",
      "editionUsed" : "Professional"
    },
    "module" : "contacts",
    "fullName" : "Henry Stephen",
    "id" : "4000000013012",
    "ownerId" : "4000000008692",
    "email" : null,
    "account" : {
      "website" : null,
      "name" : "Zylker India",
      "id" : "4000000008850"
    }
  } ],
  "count" : {
    "tickets" : 1,
    "accounts" : 1,
    "tasks" : 1,
    "contacts" : 1
  }
}

Search Tickets

This API searches for tickets in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the entity must be fetched. If the ID is not passed, then searches in all permitted departments
exact match

id

long

optional

ID of the ticket
exact match

ticketNumber

String

optional

The ticket's serial number
exact match

subject

String

optional

Subject of the ticket
wildcard search

description

String

optional

Description of the ticket
wildcard search

status

String

optional

Status of the ticket inclusive of custom status. example: 1. status=open,in progress 2. status=${open}
exact match

priority

String

optional

Priority of the ticket
exact match

email

String

optional

The corresponding email address associated with the ticket. example: 1. email=jack* 2.email=${notempty} 3.email=${empty}
wildcard search

empty check

not empty check

phone

String

optional

The phone number provided in the ticket
wildcard search

empty check

not empty check

channel

String

optional

The channel through which the ticket was received
exact match

empty check

not empty check

category

String

optional

The category of the ticket
wildcard search

empty check

not empty check

assigneeId

long

optional

ID of the agent who is assigned to resolve the ticket
exact match

contactId

long

optional

ID of the contact who raised the ticket
exact match

accountId

long

optional

ID of the account associated with the ticket
exact match

productId

long

optional

ID of the product associated with the ticket
exact match

contactName

String

optional

The name of the contact who raised the ticket
wildcard search

accountName

String

optional

Name of the account associated with the ticket
wildcard search

empty check

not empty check

productName

String

optional

Name of the product associated with the ticket
wildcard search

empty check

not empty check

tag

String

optional

The tag associated with the ticket
wildcard search

empty check

not empty check

_all

String

optional

Key that includes all the columns in the tickets module for search
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customerResponseTimeRange

timestamp

optional

Key that filters tickets in which customer responses were recorded 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,
customerResponseTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z2017-11-05T13:15:30.000Z,2018-09-05T13:15:30.000Z

createdTimeRange

timestamp

optional

Key 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

modifiedTimeRange

timestamp

optional

Key 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

dueDateRange

timestamp

optional

Key that filters tickets due 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,
dueDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

customerResponseTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/tickets/search?departmentId={departmentId}&from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/search?from=0&limit=1&subject=analysis*&email=%24%7Bnotempty%7D%20&customField1=teamId%3A1892000000057006
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-06-21T13:16:14.000Z",
    "ticketNumber" : "101",
    "subCategory" : "Sub General",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "isRead" : false,
    "channel" : "FORUMS",
    "onholdTime" : null,
    "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "resolution" : null,
    "sharedDepartments" : [ {
      "name" : "Sample Department Name",
      "id" : "1892000000006909",
      "type" : "READ_WRITE"
    }, {
      "name" : "Sample Department Name",
      "id" : "1892000000006911",
      "type" : "READ_ONLY"
    } ],
    "closedTime" : null,
    "isOverDue" : false,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "9876543456",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "modifiedBy" : "52338000000043001",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "product" : null,
    "cf" : {
      "cf_permanentaddress" : null,
      "cf_dateofpurchase" : null,
      "cf_phone" : null,
      "cf_numberofitems" : null,
      "cf_url" : null,
      "cf_secondaryemail" : null,
      "cf_severitypercentage" : "0.0",
      "cf_modelname" : "F3 2017"
    },
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "lastThread" : {
      "channel" : "FEEDBACK",
      "isDraft" : false,
      "isForward" : false,
      "direction" : "in"
    },
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "High",
    "classification" : null,
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : "1 888 900 9646",
    "createdBy" : "52338000000043001",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "isEscalated" : false,
    "isSpam" : false,
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "emailId" : "jack@zylker.com",
      "id" : "1892000000056007",
      "zuid" : "640954748"
    },
    "category" : "general",
    "status" : "Open"
  } ],
  "count" : 1
}

Search Accounts

This API searches for accounts in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

id

long

optional

ID of the account
exact match

accountName

String

optional

Name of the account
wildcard search

_all

String

optional

Find throughout the account
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search
e.g customField1=cf_activeAccount:true
empty check
e.g customField1=cf_activeAccount:${empty}
not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check
e.g customField2=cf_activeAccount:${notempty}

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters accounts 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

modifiedTimeRange

timestamp

optional

Key that filters accounts 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

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

accountName
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/accounts/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/search?limit=1&accountName=Zylker&email=%24%7Bnotempty%7D%20&customField1=cf_contactcount%3A1
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Twin",
      "lastName" : "john",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/52338000000691001/photo?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "3263000000057001",
      "zuid" : "10657727"
    },
    "country" : "USA",
    "modifiedTime" : "2015-03-02T14:49:18.000Z",
    "website" : "www.zylker.com",
    "code" : "3211",
    "cf" : {
      "cf_contactcount" : "1"
    },
    "accountName" : "Zylker",
    "city" : null,
    "description" : null,
    "industry" : "Automation",
    "ownerId" : "3263000000057001",
    "phone" : "6218129190",
    "street" : null,
    "annualrevenue" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2015-02-16T16:57:44.000Z",
    "state" : null,
    "id" : "3263000000074571",
    "fax" : "+1 444 8656 8732",
    "email" : "support@zylker.com"
  } ],
  "count" : 1
}

Search Contacts

This API searches for contacts in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

id

long

optional

ID of the contact
exact match

fullName

String

optional

Full name of the contact
wildcard search

firstName

String

optional

First name of the contact
wildcard search

empty check

not empty check

lastName

String

optional

Last name of the contact
wildcard search

email

String

optional

Email ID of the contact
wildcard search

empty check

not empty check

phone

String

optional

Phone number of the contact
wildcard search

empty check

not empty check

mobile

String

optional

Mobile number of the contact
wildcard search

empty check

not empty check

accountName

String

optional

Name of the account associated with the Contact
wildcard search

empty check

not empty check

_all

String

optional

Find throughout the contact
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search
e.g customField1=cf_mappedWithAccount:true
empty check
e.g customField1=cf_mappedWithAccount:${empty}
not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check
e.g customField2=cf_mappedWithAccount:${notempty}

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters contacts 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

modifiedTimeRange

timestamp

optional

Key that filters contacts 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

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

lastName,

firstName
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/contacts/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/search?limit=1&lastName=Lawrence&email=%24%7Bnotempty%7D%20&customField1=cf_permanentaddress%3AMenlo Park
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "Lawrence",
    "modifiedTime" : "2016-05-04T09:57:17.000Z",
    "country" : null,
    "secondaryEmail" : null,
    "city" : null,
    "description" : null,
    "ownerId" : "1892000000042001",
    "type" : null,
    "title" : null,
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
    "twitter" : null,
    "street" : null,
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "isEndUser" : "false",
    "zohoCRMContact" : {
      "id" : "5000000014010",
      "type" : "contacts_leads"
    },
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "state" : null,
    "id" : "1892000000042032",
    "email" : "lawrence@zylker.com",
    "zip" : null,
    "owner" : {
      "firstName" : "Twin",
      "lastName" : "john",
      "photoURL" : null,
      "emailId" : "lawrence@zylker.com",
      "id" : "1892000000042001",
      "zuid" : "14345345"
    },
    "cf" : {
      "cf_permanentaddress" : "Menlo Park, California",
      "cf_lastcontactedon" : null
    },
    "facebook" : null,
    "mobile" : null,
    "accountId" : "1892000000975382",
    "firstName" : "Jennifer",
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "account" : {
      "website" : null,
      "accountName" : "Zylker",
      "id" : "1892000000975382"
    }
  } ],
  "count" : 1
}

Search Articles

This API searches for help articles in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the entity must be fetched. if not passed then searches in permitted departments
exact match

id

long

optional

ID of the articles
exact match

title

String

optional

title of the help article
wildcard search

categoryName

String

optional

Name of the Category
wildcard search

categoryId

long

optional

ID of the Category

tag

String

optional

Tag in the articles
wildcard search

empty check

not empty check

_all

String

optional

Key that includes all article details for the search
wildcard search

createdTimeRange

timestamp

optional

Key that filters articles 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

modifiedTimeRange

timestamp

optional

Key that filters articles 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

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/articles/search

OAuth Scope

Desk.search.READ , Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/search?limit=1&title=Knowledge
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-07-16T06:48:08.000Z",
    "creatorId" : "4000000012931",
    "modifierId" : "4000000012931",
    "dislikeCount" : "1",
    "likeCount" : "2",
    "title" : "Importance of a Knowledge Base",
    "expiryDate" : "2018-05-21T05:55:00.000Z",
    "createdTime" : "2018-07-16T06:48:08.000Z",
    "viewCount" : "3",
    "id" : "22372000000281023",
    "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
    "latestVersionStatus" : "Published",
    "author" : {
      "photoURL" : null,
      "name" : "HIll",
      "id" : "5000000015935"
    },
    "permission" : "AGENTS",
    "authorId" : "4000000012931",
    "usageCount" : "3",
    "latestVersion" : "1.0",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Solutions/dv/22372000000281023",
    "portalUrl" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-knowledge-base",
    "feedbackCount" : "1",
    "latestPublishedVersion" : "1.0",
    "permalink" : "importance-of-a-knowledge-base",
    "category" : {
      "name" : "General",
      "id" : "5000000017008"
    },
    "categoryId" : "4000000013240",
    "status" : "Published"
  } ],
  "count" : 379
}

Search Tasks

This API searches for tasks in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

id

long

optional

ID of the task
exact match

subject

String

optional

subject of the task in the help desk
wildcard search

ticketNumber

String

optional

ticket Number of the ticket that associated with the task
exact match

status

String

optional

status of the task
exact match

priority

String

optional

Priority of the task
exact match

assigneeId

long

optional

ID of the agent assigned to resolve the task
exact match

_all

String

optional

Find throughout the task
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters tasks 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

modifiedTimeRange

timestamp

optional

Key that filters tasks 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

dueDateRange

timestamp

optional

Key that filters tasks due 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,
dueDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/tasks/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/search?limit=1&priority=High,Low&status=%24%7Bnotempty%7D%20&customField1=cf_permanentaddress%3AMenlo Park
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-09-13T12:14:41.000Z",
    "cf" : {
      "cf_permanentaddress" : "Menlo Park, California"
    },
    "ticket" : null,
    "subject" : "Bug Fix #121",
    "completedTime" : null,
    "departmentId" : "3000000007043",
    "dueDate" : "2016-09-19T12:27:26.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "3000000054002",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2016-08-14T08:27:26.000Z",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "id" : "3000000054004",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ],
  "count" : 1
}

Search Calls

This API searches for the calls in your help desk portal.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the call must be fetched. If a valid ID is not passed, the search is performed in all departments permitted.
exact match

id

long

optional

ID of the call
exact match

subject

String

optional

subject of the call
wildcard search

ticketNumber

String

optional

Ticket number of the ticket associated with the call
exact match

status

String

optional

Status of the call
exact match

priority

String

optional

Priority of the call
exact match

assigneeId

long

optional

ID of the agent assigned to handle the call
exact match

_all

String

optional

Key that includes all call details for the search
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters calls recorded in the help desk in a particular period.
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

modifiedTimeRange

timestamp

optional

Key that filters calls whose details were modified in a particular period.
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

startDateRange

timestamp

optional

Key that filters calls that were made in a particular period.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;

For example,
startDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/calls/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.calls.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/calls/search?limit=1&priority=High,Low&status=%24%7Bnotempty%7D%20&customField1=cf_permanentaddress%3AMenlo Park
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-26T17:32:11.000Z",
    "cf" : {
      "cf_permanentaddress" : "Menlo Park, California"
    },
    "ticket" : {
      "ticketNumber" : "101",
      "contact" : {
        "firstName" : null,
        "lastName" : "Lawrence",
        "phoneNumber" : "+14246721666",
        "id" : "3000000008749"
      },
      "id" : "3000000008753"
    },
    "subject" : "New Call",
    "completedTime" : "2016-07-26T17:32:11.000Z",
    "departmentId" : "3000000007043",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : null,
    "priority" : "Normal",
    "duration" : "300",
    "createdTime" : "2016-07-26T17:32:11.000Z",
    "startTime" : "2016-07-25T16:52:11.000Z",
    "id" : "3000000018001",
    "assignee" : {
      "firstName" : "",
      "lastName" : "raja",
      "photoURL" : null,
      "emailId" : "carol@zylker.com",
      "id" : "36385000000120033",
      "zuid" : "55499215"
    },
    "ticketId" : "3000000008753",
    "direction" : "inbound",
    "status" : "completed"
  } ],
  "count" : 1
}

Search Events

This API searches for the events in your help desk portal.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the event must be fetched. If a valid ID is not passed, the search is performed in all departments permitted.
exact match

id

long

optional

ID of the event
exact match

subject

String

optional

Subject of the event
wildcard search

ticketNumber

String

optional

Ticket number of the ticket associated with the event
exact match

status

String

optional

Status of the event
exact match

priority

String

optional

Priority of the event
exact match

assigneeId

long

optional

ID of the agent assigned to handle the event
exact match

_all

String

optional

Key that includes all event details for the search
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters events recorded in the help desk in a particular period.
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

modifiedTimeRange

timestamp

optional

Key that filters events whose details were modified in a particular period.
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

startDateRange

timestamp

optional

Key that filters events that occurred in a particular period.
Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ;

For example,
startDateRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/events/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.events.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/events/search?limit=1&priority=High,Low&status=%24%7Bnotempty%7D%20&customField1=cf_permanentaddress%3AMenlo Park
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-26T17:32:11.000Z",
    "ticket" : {
      "ticketNumber" : "101",
      "contact" : {
        "firstName" : null,
        "lastName" : "Lawrence",
        "id" : "3000000008749"
      },
      "id" : "3000000008753"
    },
    "customFields" : { },
    "subject" : "New Event",
    "completedTime" : "2016-07-26T17:32:11.000Z",
    "departmentId" : "3000000007043",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : null,
    "priority" : "Normal",
    "duration" : "30",
    "createdTime" : "2016-07-26T16:32:11.000Z",
    "startTime" : "2016-07-26T17:02:11.000Z",
    "id" : "3000000018001",
    "assignee" : {
      "firstName" : "",
      "lastName" : "raja",
      "photoURL" : null,
      "emailId" : "carol@zylker.com",
      "id" : "36385000000120033",
      "zuid" : "55499215"
    },
    "category" : "Meeting",
    "ticketId" : "3000000008753",
    "status" : "completed"
  } ],
  "count" : 1
}

Search Products

This API searches for the products in your help desk portal.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

id

long

optional

ID of the Product
exact match

productName

String

optional

Name of the Product
wildcard search

productCode

String

optional

Code of the product
wildcard search

empty check

not empty check

contactId

long

optional

ID of the contact associated with the product
exact match

accountId

long

optional

ID of the account associated with the product
exact match

_all

String

optional

Search throughout the product
wildcard search

customField1
see documentation

String

optional

To search for the values in a field, use the below format.
customfield1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField2

String

optional

To search for the values in a field, use the below format.
customfield2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField3

String

optional

To search for the values in a field, use the below format.
customfield3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField4

String

optional

To search for the values in a field, use the below format.
customfield4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField5

String

optional

To search for the values in a field, use the below format.
customfield5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField6

String

optional

To search for the values in a field, use the below format.
customfield6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField7

String

optional

To search for the values in a field, use the below format.
customfield7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField8

String

optional

To search for the values in a field, use the below format.
customfield8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField9

String

optional

To search for the values in a field, use the below format.
customfield9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

customField10

String

optional

To search for the values in a field, use the below format.
customfield10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Key that filters products 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

modifiedTimeRange

timestamp

optional

Key that filters products 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

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime,

productName
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/products/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.products.READ , Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/products/search?limit=1&productName=Search2&productCode=%24%7Bnotempty%7D%20&customField1=cf_productTagName%3Asecondary
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-11-02T10:31:35.000Z",
    "productCode" : "Search2",
    "cf" : {
      "cf_productTagName" : "secondary engine"
    },
    "createdBy" : "5000000009116",
    "description" : null,
    "createdTime" : "2017-11-02T10:31:35.000Z",
    "modifiedBy" : "5000000009116",
    "departmentIds" : [ "5000000007235" ],
    "id" : "5000000009882",
    "productName" : "Search2"
  } ],
  "count" : 1
}

Search Activities

This API searches for the activities in your help desk portal.
You can provide comma-separated values, which will perform the search on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call, 1 credit (with unique ID)

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

departmentId

long

optional

ID of the department from which the activity must be fetched. If you do not pass a value for this parameter, the search is performed in all permitted departments.
exact match

id

long

optional

ID of the activity
exact match

subject

String

optional

Subject of the activity
wildcard search

ticketNumber

String

optional

Serial number of the ticket associated with the activity
exact match

status

String

optional

Completion status of the activity
exact match

priority

String

optional

Priority of the activity
exact match

assigneeId

long

optional

ID of the agent assigned to handle the activity
exact match

_all

String

optional

Key that searches across all fields in all activities
wildcard search

createdTimeRange

timestamp

optional

Key that filters activities 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.

modifiedTimeRange

timestamp

optional

Key that filters activities 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.

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/activities/search?from={from}&limit={limit}&sortField={sortField}&customField1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , Desk.calls.READ , Desk.tasks.READ , Desk.events.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/activities/search?limit=1&priority=High,Low
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-09-13T12:14:41.000Z",
    "ticket" : null,
    "customFields" : { },
    "subject" : "Bug Fix #121",
    "completedTime" : null,
    "module" : "task",
    "departmentId" : "3000000007043",
    "dueDate" : "2016-09-19T12:27:26.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "3000000054002",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2016-08-14T08:27:26.000Z",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "id" : "3000000054004",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ],
  "count" : 1
}

Search Records

This API searches for records in your help desk.
You can provide multiple values separated by commas, and the search will be performed on the field using any of the provided values.

Learn more about search and how it works.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
from
see documentation

int

optional,
range : 0-4999

The starting index for fetching results.
default : 0

starts from 0

limit
see documentation

int

optional,
range : 1-100

Specifies the number of tickets to be fetched.
default : 10

_all

String

optional

To match throughout the all the fields
wildcard search

field1
see documentation

String

optional

To search for the values in a field, use the below format.
field1=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field2

String

optional

To search for the values in a field, use the below format.
field2=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field3

String

optional

To search for the values in a field, use the below format.
field3=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field4

String

optional

To search for the values in a field, use the below format.
field4=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field5

String

optional

To search for the values in a field, use the below format.
field5=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field6

String

optional

To search for the values in a field, use the below format.
field6=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field7

String

optional

To search for the values in a field, use the below format.
field7=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field8

String

optional

To search for the values in a field, use the below format.
field8=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field9

String

optional

To search for the values in a field, use the below format.
field9=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

field10

String

optional

To search for the values in a field, use the below format.
field10=Field ApiName:search value
This will compare the specified search values with the field's value and retrieve the matching results.
wildcard search

empty check

not empty check

createdTimeRange

timestamp

optional

Retrieves the records of the custom module based on the specified created time. The time range can be provided in ISO format
yyyy-MM-ddThh:mm:ss.SSSZ
separated by a comma.
For example,
createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

modifiedTimeRange

timestamp

optional

Retrieves the records of the custom module based on the specified modified time. The time range can be provided in ISO format
yyyy-MM-ddThh:mm:ss.SSSZ
separated by a comma.
For example,
modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z

sortBy

String

optional

SortBy can be:
relevance,

modifiedTime,

createdTime
To specify sorting order, use as given below:
For descending order: sortBy=-modifiedTime

For ascending order: sortBy=modifiedTime

GET /api/v1/{moduleApiName}/search?from={from}&limit={limit}&sortField={sortField}&field1={apiName:value}

OAuth Scope

Desk.search.READ , Desk.custommodule.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/cm_doctors/search?field1=cf_doctor_description%3Achange&from=0&limit=10
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "layout" : {
    "id" : "1000003000004",
    "layoutName" : "Standard - Department1"
  },
  "owner" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329"
  },
  "modifiedTime" : "2024-04-22T14:09:41.000Z",
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description change"
  },
  "createdBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329"
  },
  "name" : "Doctor 1",
  "createdTime" : "2024-04-22T13:55:53.000Z",
  "modifiedBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329"
  },
  "isPresence" : true,
  "id" : "1000003019049",
  "department" : {
    "name" : "Department1",
    "id" : "1000000025632"
  }
}

Ticket TimeEntry

Ticket time entry refers to the time taken by an agent to resolve a ticket.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

customFields 

deprecated

list

User-defined fields related to the time entry.

cf

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

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

invoiceId

long

ID of the invoice related to the time entry

Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "0",
  "parent" : {
    "ticketNumber" : "1004",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : { },
  "executedTime" : null,
  "departmentId" : "4000000008694",
  "fixedCost" : null,
  "minutesSpent" : "0",
  "creatorId" : "4000000008688",
  "agentCostPerHour" : null,
  "description" : "Time Entry description",
  "hoursSpent" : "2",
  "ownerId" : "4000000008688",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-05-30T09:58:08.149Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000033010",
  "requestChargeType" : "Product Consultation",
  "additionalCost" : null,
  "totalCost" : null
}


Get Ticket Time Entry

This API fetches a time entry recorded for a ticket.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000033010?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "parent" : {
    "ticketNumber" : "1004",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "secondsSpent" : "21",
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "departmentId" : "4000000008694",
  "fixedCost" : null,
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Ticket Time Entries

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

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key 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.

modifiedTimeRange

timestamp

optional

Key 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.

GET /api/v1/tickets/{ticket_id}/timeEntry

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry?from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1004",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1004",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time2"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "departmentId" : "4000000008694",
    "fixedCost" : null,
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "ticketNumber" : "1004",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time3"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add Ticket Time Entry

This API adds a time entry in your help desk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

required

Time when work related to the time entry was started.

hoursSpent

integer

optional,
range : 0-999

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

customFields 
deprecated

list

optional

User-defined fields related to the time entry.

cf

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

POST /api/v1/tickets/{ticket_id}/timeEntry

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "secondsSpent" : "21",
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "minutesSpent" : "23",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "invoiceId" : "4000000008688123",
  "ownerId" : "4000000008692",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1004",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update Ticket Time Entry

This API updates an existing ticket time entry

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

optional

Time when work related to the time entry was started.

hoursSpent

integer

optional,
range : 0-999

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

customFields 
deprecated

list

optional

User-defined fields related to the time entry.

cf

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

PATCH /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "description" : "Time Entry description",
  "requestChargeType" : "Customer Service"
}'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1004",
    "associatedTicketId" : "4000000031007",
    "subject" : "Task subject",
    "id" : "4000000031008",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete Ticket Time Entry

This API deletes a time entry recorded for a ticket

Credit: 1 credit/call

DELETE /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get summation of Ticket Time Entries

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

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/tickets/{ticket_id}/timeEntrySummation

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntrySummation?billStatus=billed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Get Ticket Time Entries by Billing Type

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

Query Params

Param Name
Data Type
Description
billingType

String

required

Allowed values are FIXED_COST_FOR_TICKETS FIXED_COST_FOR_AGENTS SPECIFIC_COST_PER_AGENT SPECIFIC_COST_PER_PROFILE

include
see documentation

string

optional,
max chars : 100

Allowed value is : owner

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

GET /api/v1/tickets/{ticket_id}/timeEntryByBillingType

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntryByBillingType?billingType=FIXED_COST_FOR_TICKETS&include=owner&from=0&limit=10
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "0",
    "parent" : {
      "ticketNumber" : "1004",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : { },
    "executedTime" : null,
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "0",
    "agentCostPerHour" : null,
    "description" : null,
    "hoursSpent" : "0",
    "ownerId" : "15000000009148",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "createdBy" : "15000000009148",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2018-01-10T18:45:17.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "15000000031007",
    "requestChargeType" : "Customer Service",
    "additionalCost" : null,
    "totalCost" : "0.0"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "0",
    "parent" : {
      "ticketNumber" : "1004",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "cf" : { },
    "executedTime" : "2017-12-20T18:09:20.000Z",
    "departmentId" : "4000000008694",
    "fixedCost" : null,
    "minutesSpent" : "0",
    "agentCostPerHour" : null,
    "description" : "Dummy#2",
    "hoursSpent" : "1",
    "ownerId" : "15000000009148",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "createdBy" : "15000000009148",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2018-01-10T15:20:47.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "15000000029314",
    "requestChargeType" : "Upgrade Request",
    "additionalCost" : null,
    "totalCost" : "0.0"
  } ]
}

Ticket Approvals

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.

ATTRIBUTES

Attribute Name
Data Type
Description
approverIds

list

IDs of users to whom the approval must be submitted

subject

string

Subject of the approval

status

string

Status of the approval

description

String

Description of the approval

requestedTime

timestamp

Time when the approval was requested

processedTime

timestamp

Time when the approval was processed

id

long

ID of the approval

requester

object

Details of user who requested for the approval

approver

object

Details of user who processed the approval

Example

{
  "approver" : {
    "firstName" : "",
    "lastName" : "Saranraj",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000013292/photo",
    "id" : "5000000013292",
    "email" : null
  },
  "requester" : {
    "firstName" : "",
    "lastName" : "Smith",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : null
  },
  "requestedTime" : "2018-06-18T14:22:21.871Z",
  "subject" : "saran test approval",
  "description" : "",
  "id" : "5000000026001",
  "status" : "Pending",
  "processedTime" : null
}


List approvals

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number starting from which the approvals must be fetched

limit

integer

optional,
range : 1-100

Number of approvals to fetch

status

string

optional,
max chars : 100

Key that filters the approvals by status

GET /api/v1/tickets/{ticket_id}/approvals

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "approver" : {
      "firstName" : "",
      "lastName" : "raj",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
      "id" : "4000000015001",
      "email" : "carol@zylker.com"
    },
    "requester" : {
      "firstName" : "",
      "lastName" : "saran",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
      "id" : "4000000012629",
      "email" : "carol@zylker.com"
    },
    "requestedTime" : "2016-06-21T13:16:14.000Z",
    "subject" : "Testing",
    "description" : "testing",
    "id" : "1892000001054081",
    "status" : "Approved",
    "processedTime" : "2018-02-07T10:12:35.000Z"
  } ]
}

Get approval

This API fetches the details of an approval.

Credit: 1 credit/call

GET /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals/1892000001054081
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "approver" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
    "id" : "4000000015001",
    "email" : null
  },
  "requester" : {
    "firstName" : "aravind",
    "lastName" : "a",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
    "id" : "4000000012629",
    "email" : null
  },
  "requestedTime" : "2016-06-21T13:16:14.000Z",
  "subject" : "Testing",
  "processedTime " : "2018-02-07T10:12:35.000Z",
  "description" : "testing",
  "id" : "1892000001054081",
  "status" : "Rejected"
}

Create approval

This API creates an approval in your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
approverIds

list

required

IDs of users to whom the approval must be submitted

subject

string

required,
max chars : 1000

Subject of the approval

status

string

optional,
max chars : 100

Status of the approval

description

String

optional

Description of the approval

POST /api/v1/tickets/{ticket_id}/approvals

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "approverIds" : [ "1892000000042001" ],
  "subject" : "New approval",
  "description" : "new app desc"
}'

Response Example

{
  "approvals" : [ {
    "approver" : {
      "firstName" : "saran",
      "lastName" : "raj",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
      "id" : "4000000015001",
      "email" : null
    },
    "requester" : {
      "firstName" : "aravind",
      "lastName" : "a",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
      "id" : "4000000012629",
      "email" : null
    },
    "requestedTime" : "2016-06-21T13:16:14.000Z",
    "subject" : "Testing",
    "description" : "testing",
    "id" : "1892000001054081",
    "status" : "PENDING",
    "processedTime" : null
  } ]
}

Update approval

This API updates the details of an existing ticket approval.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
approverIds

list

optional

IDs of users to whom the approval must be submitted

subject

string

optional,
max chars : 1000

Subject of the approval

status

string

optional,
max chars : 100

Status of the approval

description

String

optional

Description of the approval

PATCH /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/approvals/1892000001054081
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "status" : "Approved/Rejected"
}'

Response Example

{
  "approver" : {
    "firstName" : "saran",
    "lastName" : "raj",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000015001/photo",
    "id" : "4000000015001",
    "email" : null
  },
  "requester" : {
    "firstName" : "aravind",
    "lastName" : "a",
    "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
    "id" : "4000000012629",
    "email" : null
  },
  "requesterId" : "1892000000042001",
  "requestedTime" : "2016-06-21T13:16:14.000Z",
  "approverId" : "1892000000042001",
  "subject" : "Testing",
  "description" : "testing",
  "id" : "1892000001054081",
  "status" : "Approved",
  "processedTime" : "2018-02-07T10:12:35.000Z"
}

Task TimeEntry

Tasks Time Entry refers to the time taken by an agent to complete a task.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

customFields 

deprecated

list

User-defined fields related to the time entry.

cf

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

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

invoiceId

long

ID of the invoice related to the time entry

Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "0",
  "parent" : {
    "ticketNumber" : "1003",
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : { },
  "executedTime" : null,
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "0",
  "creatorId" : "4000000008688",
  "agentCostPerHour" : null,
  "description" : "Time Entry description",
  "hoursSpent" : "2",
  "ownerId" : "4000000008688",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-05-30T09:58:08.149Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033010",
  "requestChargeType" : "Product Consultation",
  "additionalCost" : null,
  "totalCost" : null
}


Get a Task Time Entry

This API fetches a time entry recorded for a task.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000033010?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1003",
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "departmentId" : "4000000008694",
  "fixedCost" : null,
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Task Time Entries

This API lists the time entries associated with a task.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key 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.

modifiedTimeRange

timestamp

optional

Key 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.

GET /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry?from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1003",
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1003",
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time2"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "ticketNumber" : "1003",
      "associatedTicketId" : "4000000030017",
      "subject" : "Tasks subject",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "cf" : {
      "cf_timeentryname" : "time3"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add a Task Time Entry

This API creates a time entry in your help desk

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

required

Time when work related to the time entry was started.

hoursSpent

integer

optional,
range : 0-999

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

customFields 
deprecated

list

optional

User-defined fields related to the time entry.

cf

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

POST /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.activities.CREATE , Desk.activities.tasks.CREATE , Desk.tasks.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "secondsSpent" : "21",
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "minutesSpent" : "23",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1003",
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time2"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update a Task Time Entry

This API updates details of an existing time entry.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
requestChargeType

string

optional,
max chars : 120

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

optional

ID of the user associated with the time entry

executedTime

timestamp

optional

Time when work related to the time entry was started.

hoursSpent

integer

optional,
range : 0-999

Number of hours in the time entry.

minutesSpent

integer

optional

Number of minutes in the time entry.

secondsSpent

integer

optional

Number of seconds in the time entry.

agentCostPerHour

double

optional

Per hour cost of an agent.

additionalCost

double

optional

Additional cost incurred

fixedCost

double

optional

Fixed cost

description

string

optional,
max chars : 65535

Description of the time entry

customFields 
deprecated

list

optional

User-defined fields related to the time entry.

cf

JSONObject

optional

User-defined fields related to the time entry.

mode

String

optional

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

optional

Billing Preference

invoiceId

long

optional

ID of the invoice related to the time entry

PATCH /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "description" : "Time Entry description",
  "requestChargeType" : "Customer Service"
}'

Response Example

{
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1003",
    "associatedTicketId" : "4000000030017",
    "subject" : "Tasks subject",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete a Task Time Entry

This API deletes a time entry recorded for a task.

Credit: 1 credit/call

DELETE /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get summation of Task Time Entries

This API fetches the sum of time entries associated with a task.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/tasks/{task_id}/timeEntrySummation

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntrySummation?billStatus=billed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Agent TimeEntry

Agent time entry refers to the time taken by an agent to resolve a ticket or perform a task.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

customFields 

deprecated

list

User-defined fields related to the time entry.

cf

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

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

invoiceId

long

ID of the invoice related to the time entry

Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "0",
  "parent" : {
    "ticketNumber" : "1001",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : { },
  "executedTime" : null,
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "0",
  "creatorId" : "4000000008688",
  "agentCostPerHour" : null,
  "description" : "Time Entry description",
  "hoursSpent" : "2",
  "ownerId" : "4000000008688",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-05-30T09:58:08.149Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033010",
  "requestChargeType" : "Product Consultation",
  "additionalCost" : null,
  "totalCost" : null
}


Get an Agent Time Entry

This API fetches a time entry related to an agent.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/agents/{agent_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntry/4000000033010?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "21",
  "parent" : {
    "ticketNumber" : "1001",
    "associatedTicketId" : "4000000031007",
    "subject" : "Task subject",
    "id" : "4000000031010",
    "type" : "TASKS"
  },
  "cf" : {
    "cf_timeentryname" : "time1"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Agent Time Entries

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

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner.

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key 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.

modifiedTimeRange

timestamp

optional

Key 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.

GET /api/v1/agents/{agent_id}/timeEntry

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031007",
      "subject" : "Task subject",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Agent Time Entries

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

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/agents/{agent_id}/timeEntrySummation

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Contact TimeEntry

Contact time entry refers to the time taken to resolve a ticket or perform a task related to a particular contact.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

customFields 

deprecated

list

User-defined fields related to the time entry.

cf

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

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

invoiceId

long

ID of the invoice related to the time entry

Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "0",
  "parent" : {
    "ticketNumber" : "1001",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : { },
  "executedTime" : null,
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "0",
  "agentCostPerHour" : null,
  "description" : "Time Entry description",
  "hoursSpent" : "2",
  "ownerId" : "4000000008688",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-05-30T09:58:08.149Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033010",
  "requestChargeType" : "Product Consultation",
  "additionalCost" : null,
  "totalCost" : null
}


List Contact Time Entries

This API lists time entries recorded for a ticket or task related to a contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched.

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key 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.

modifiedTimeRange

timestamp

optional

Key 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.

GET /api/v1/contacts/{contact_id}/timeEntry

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "22",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031014",
      "subject" : "Tasks subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Contact Time Entries

This API fetches summation of time entries for a contact from your help desk

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/contacts/{contact_id}/timeEntrySummation

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Account TimeEntry

Account time entry refers to the time taken to resolve a ticket or perform a task related to a particular account.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the time entry

ticketId

long

ID of the ticket

requestChargeType

string

Type of request in the ticket. Values supported are Customer Service, Upgrade Request, Product Consultation, and Support and Maintenance.

ownerId

long

ID of the user associated with the time entry

parent

object

Module to which the time entry is associated.

executedTime

timestamp

Time when work related to the time entry was started.

hoursSpent

integer

Number of hours in the time entry.

minutesSpent

integer

Number of minutes in the time entry.

secondsSpent

integer

Number of seconds in the time entry.

agentCostPerHour

double

Per hour cost of an agent.

additionalCost

double

Additional cost incurred

totalCost

double

Total cost incurred

fixedCost

double

Fixed cost

description

string

Description of the time entry

customFields 

deprecated

list

User-defined fields related to the time entry.

cf

JSONObject

User-defined fields related to the time entry.

createdTime

timestamp

Time of creating the ticket time entry

modifiedTime

timestamp

Time of modifying the ticket time entry

createdBy

string

User who created the time entry.

modifiedBy

string

User who modified the time entry.

mode

String

Mode configured in time tracking. Supported values are Manual and Auto

isBillable

boolean

Billing Preference

billingType

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

invoiceId

long

ID of the invoice related to the time entry

Example

{
  "owner" : {
    "firstName" : "Eswer",
    "lastName" : "KM",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Eswer KM",
    "id" : "4000000008688129"
  },
  "secondsSpent" : "0",
  "parent" : {
    "ticketNumber" : "1001",
    "subject" : "Ticket subject",
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "cf" : { },
  "executedTime" : null,
  "fixedCost" : null,
  "departmentId" : "4000000008694",
  "minutesSpent" : "0",
  "creatorId" : "4000000008688",
  "agentCostPerHour" : null,
  "description" : "Time Entry description",
  "hoursSpent" : "2",
  "ownerId" : "4000000008688",
  "isBillable" : true,
  "mode" : "MANUAL",
  "isTrashed" : "false",
  "billingType" : "FIXED_COST_FOR_TICKETS",
  "createdTime" : "2016-05-30T09:58:08.149Z",
  "invoiceId" : "40000000086881212",
  "id" : "4000000033010",
  "requestChargeType" : "Product Consultation",
  "additionalCost" : null,
  "totalCost" : null
}


List Account Time Entries

This API lists time entries recorded for a ticket or task related to an account.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

optional

ID of the department

from

integer

optional

Index number, starting from which the time entries must be fetched

limit

integer

optional,
range : 1-100

Number of time entries to fetch

orderBy

String

optional

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC@

include
see documentation

string

optional,
max chars : 100

Secondary information related to the time entry. Value supported is owner

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

createdTimeRange

timestamp

optional

Key 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.

modifiedTimeRange

timestamp

optional

Key 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.

GET /api/v1/accounts/{account_id}/timeEntry

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000031007/timeEntry?module=ticket&from=0&limit=10&include=owner&billStatus=billed&createdTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z&modifiedTimeRange=2016-06-16T06:00:00.000Z,2016-06-16T20:00:00.000Z
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "fixedCost" : "10.17",
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688129"
    },
    "secondsSpent" : "21",
    "parent" : {
      "ticketNumber" : "1001",
      "associatedTicketId" : "4000000031014",
      "subject" : "Task subject",
      "id" : "4000000031007",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "firstName" : "Eswer",
      "lastName" : "KM",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Eswer KM",
      "id" : "4000000008688128"
    },
    "secondsSpent" : "22",
    "parent" : {
      "ticketNumber" : "1001",
      "subject" : "Ticket subject",
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "fixedCost" : null,
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "isBillable" : true,
    "mode" : "MANUAL",
    "isTrashed" : "false",
    "billingType" : "FIXED_COST_FOR_TICKETS",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Get summation of Account Time Entries

This API fetches summation of time entries for an account from your help desk

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

string

optional,
max chars : 100

Module Preference. It can be either tickets tasks

departmentId

long

optional

ID of the department

billStatus

String

optional

Key that filters time entries, based on their billing status: nonBillable , billable or billed

GET /api/v1/accounts/{account_id}/timeEntrySummation

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000031007/timeEntrySummation?module=ticket&billStatus=billed
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

Ticket Timer

Ticket timer is a feature that records the time an agent spends on resolving a ticket.

ATTRIBUTES

Attribute Name
Data Type
Description
hours

integer

No. of hours spent

minutes

integer

No. of minutes spent

seconds

integer

No. of seconds spent

state

integer

State of the timer. States can be RUNNING, PAUSED, INIT

Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}


Get Ticket Timer

This API fetches the time elapsed in the ticket timer, along with the current state

Credit: 1 credit/call

GET /api/v1/tickets/{ticket_id}/timer

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/tickets/13000000021183/timer
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}

Performs Ticket Timer actions

This API performs timer-related actions, such as START, STOP, PAUSE and RESUME 

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
action

String

required

Action of the timer.Supported actions are START, STOP, PAUSE and RESUME

POST /api/v1/tickets/{ticket_id}/timer

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST http://desk.zoho.com/api/v1/tickets/13000000021183/timer?action=START
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 0,
  "minutes" : 0,
  "state" : "RUNNING"
}

Task Timer

Task timer is the feature that records the time an agent spends on completing a task.

ATTRIBUTES

Attribute Name
Data Type
Description
hours

integer

No. of hours spent

minutes

integer

No. of minutes spent

seconds

integer

No. of seconds spent

state

integer

State of the timer. States can be RUNNING, PAUSED, INIT

Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}


Get Task Timer

This API fetches the time elapsed in the task timer, along with the current state

Credit: 1 credit/call

GET /api/v1/tasks/{task_id}/timer

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/tasks/13000000021183/timer
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 26,
  "minutes" : 5,
  "state" : "RUNNING"
}

Performs Task Timer actions

This API performs timer-related actions, such as START, STOP, PAUSE and RESUME

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
action

String

required

Action of the timer.Supported actions are START, STOP, PAUSE and RESUME

POST /api/v1/tasks/{task_id}/timer

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X POST http://desk.zoho.com/api/v1/tasks/13000000075019/timer?action=START
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "hours" : 0,
  "seconds" : 0,
  "minutes" : 0,
  "state" : "RUNNING"
}

Active Timer

Active timer will fetch currently active [either running (or) paused] timer(s) details

Example

{
  "timer" : {
    "hours" : 93,
    "seconds" : 9,
    "minutes" : 6,
    "state" : "Init | Running | Paused"
  },
  "task" : {
    "subject" : "New Testing Task",
    "dueDate" : "2017-08-22 16:16:16",
    "depId" : "7000000016007",
    "id" : "7000000020001",
    "depName" : "AutomationCheck2",
    "status" : "In Progress"
  },
  "ticket" : {
    "ticketNumber" : "101",
    "subject" : "Sample",
    "dueDate" : "2017-08-22 16:16:16",
    "depId" : "7000000016005",
    "id" : "7000000009092",
    "depName" : "AutomationCheck2",
    "status" : "Open"
  },
  "entity" : "Tasks"
}


Get Active Timer for an Agent

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

required

Department to which the ticket belongs

limit

Integer

optional,
range : 1-50

limit

from

Integer

optional

from

GET /api/v1/myActiveTimers

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/myActiveTimers?departmentId=7000000022910?from=0&limit=10
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "timer" : {
      "hours" : 3,
      "seconds" : 30,
      "minutes" : 6,
      "state" : "RUNNING"
    },
    "task" : {
      "subject" : "Bug Fix #120",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016001",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016005",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Tasks"
  }, {
    "call" : {
      "subject" : "Firt Call",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016002",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "timer" : {
      "hours" : 3,
      "seconds" : 37,
      "minutes" : 7,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016005",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Calls"
  }, {
    "timer" : {
      "hours" : 3,
      "seconds" : 59,
      "minutes" : 7,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "depId" : "7000000016007",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "event" : {
      "subject" : "First Event",
      "dueDate" : "2018-07-21 16:16:16.0",
      "depId" : "7000000016005",
      "id" : "7000000016003",
      "depName" : "activitycheck",
      "status" : "In Progress"
    },
    "entity" : "Events"
  }, {
    "timer" : {
      "hours" : 3,
      "seconds" : 4,
      "minutes" : 8,
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : 101,
      "subject" : "Here's your first ticket.",
      "dueDate" : "2018-05-10 14:49:45.0",
      "id" : "7000000013018",
      "depName" : "activitycheck",
      "status" : "Open"
    },
    "entity" : "Tickets"
  } ]
}

List active timers

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department from which the timers must be fetched

module

string

optional,
max chars : 100

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.

startTime

long

optional

Point 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.)

limit

Integer

optional,
range : 1-50

Number of timers to list

sortBy

string

optional,
max chars : 100

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).

owners

long

optional

Key that filters timers by Owner. Values allowed are any valid Owner ID or multiple Owner IDs separated by commas.

GET /api/v1/allActiveTimers

OAuth Scope

Desk.tickets.READ , Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/allActiveTimers?departmentId=75485000000569047?startTime=0&limit=20&sortBy=-startTime&module=Tickets,Tasks,Events,Calls&owners=75485000000418459,75485000000182033
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/75485000000418459/photo?orgId=60708463",
      "name" : "McKinson George",
      "id" : "75485000000418459"
    },
    "timer" : {
      "hours" : "137",
      "seconds" : "38",
      "minutes" : "17",
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : "401",
      "subject" : "Ticket for timer by another agent",
      "dueDate" : null,
      "depId" : "75485000000569047",
      "id" : "75485000001513021",
      "depName" : "TestDept",
      "status" : "Open"
    },
    "startTime" : "1626290803841",
    "entity" : "Tickets"
  }, {
    "owner" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463",
      "name" : "Carol Lucas",
      "id" : "75485000000182033"
    },
    "timer" : {
      "hours" : "192",
      "seconds" : "23",
      "minutes" : "38",
      "state" : "RUNNING"
    },
    "ticket" : {
      "ticketNumber" : "673",
      "subject" : "Ticket for timer",
      "dueDate" : null,
      "depId" : "75485000000569047",
      "id" : "75485000002473027",
      "depName" : "TestDept",
      "status" : "Open"
    },
    "startTime" : "1626150959474",
    "entity" : "Tickets"
  }, {
    "owner" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463",
      "name" : "Carol Lucas",
      "id" : "75485000000182033"
    },
    "timer" : {
      "hours" : "216",
      "seconds" : "10",
      "minutes" : "47",
      "state" : "RUNNING"
    },
    "task" : {
      "subject" : "Task with ticket for timer",
      "dueDate" : "2021-07-14T06:30:00.000Z",
      "depId" : "75485000000569047",
      "id" : "75485000002466025",
      "depName" : "TestDept",
      "status" : "Not Started"
    },
    "ticket" : {
      "ticketNumber" : "672",
      "subject" : "checking active timer",
      "dueDate" : "2021-07-14T06:30:00.000Z",
      "depId" : "75485000000569047",
      "id" : "75485000002459023",
      "depName" : "TestDept",
      "status" : "Open"
    },
    "startTime" : "1626064031778",
    "entity" : "Tasks"
  }, {
    "owner" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463",
      "name" : "Carol Lucas",
      "id" : "75485000000182033"
    },
    "timer" : {
      "hours" : "226",
      "seconds" : "21",
      "minutes" : "21",
      "state" : "RUNNING"
    },
    "startTime" : "1626029581045",
    "event" : {
      "subject" : "Event without ticket ",
      "dueDate" : null,
      "depId" : "75485000000569047",
      "id" : "75485000002463059",
      "depName" : "TestDept",
      "status" : "Not Started"
    },
    "entity" : "Events"
  }, {
    "owner" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463",
      "name" : "Carol Lucas",
      "id" : "75485000000182033"
    },
    "timer" : {
      "hours" : "274",
      "seconds" : "42",
      "minutes" : "26",
      "state" : "RUNNING"
    },
    "task" : {
      "subject" : "Task without ticket",
      "dueDate" : null,
      "depId" : "75485000000569047",
      "id" : "75485000000572019",
      "depName" : "TestDept",
      "status" : "Not Started"
    },
    "startTime" : "1625856459759",
    "entity" : "Tasks"
  } ]
}

List ticket timers

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the timers must be fetched

limit

integer

optional,
range : 1-100

Number of timers to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the timers. Value supported is owner.

GET /api/v1/tickets/{ticket_id}/activeTimer

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/tickets/13000000021183/activeTimer?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Sam",
      "lastName" : "Jones",
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Sam Jones",
      "id" : "7000000020001"
    },
    "timer" : {
      "hours" : 93,
      "seconds" : 9,
      "minutes" : 6,
      "state" : "Running"
    },
    "userId" : "7000000020001"
  }, {
    "owner" : {
      "firstName" : "Robert",
      "lastName" : "Downey",
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Robert Downey",
      "id" : "7000000030001"
    },
    "timer" : {
      "hours" : 19,
      "seconds" : 24,
      "minutes" : 9,
      "state" : "Paused"
    },
    "userId" : "7000000030001"
  } ]
}

List task timers

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the timers must be fetched

limit

integer

optional,
range : 1-100

Number of timers to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the timers. Value supported is owner.

GET /api/v1/tasks/{task_id}/activeTimer

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET http://desk.zoho.com/api/v1/tasks/13000000021183/activeTimer?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "firstName" : "Sam",
      "lastName" : "Jones",
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Sam Jones",
      "id" : "7000000020001"
    },
    "timer" : {
      "hours" : 93,
      "seconds" : 9,
      "minutes" : 6,
      "state" : "Running"
    },
    "userId" : "7000000020001"
  }, {
    "owner" : {
      "firstName" : "Robert",
      "lastName" : "Downey",
      "photoURL" : "https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20",
      "name" : "Robert Downey",
      "id" : "7000000030001"
    },
    "timer" : {
      "hours" : 19,
      "seconds" : 24,
      "minutes" : 9,
      "state" : "Paused"
    },
    "userId" : "7000000030001"
  } ]
}

Ticket Tags

Ticket tags refer to the keywords added to tickets to ensure quick grouping, filtering, and reference.

Search tags

This API searches for tags added in your help desk portal.

Credit: 3 credits/call

Query Params

Param Name
Data Type
Description
from

int

optional

Index number, starting from which the tags must be fetched

limit

int

optional,
range : 1-100

Number of tags to fetch

departmentId
see documentation

long

required

ID of the department from which the tags must be fetched.

searchVal

String

optional

Search keyword related to the tag.

GET api/v1/tags/search

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tags/search
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "sample",
    "tagType" : "SYSTEM",
    "id" : 123234324
  } ]
}

List ticket tags

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department from which the tags must be fetched

sortBy

string

optional,
max chars : 100

Key that sorts tags by a specific attribute: createdTime or count. The default sorting order is descending.

from

int

optional

Index number, starting from which the tags must be fetched

limit

int

optional,
range : 1-100

Number of tags to fetch

GET api/v1/ticketTags

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketTags
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketCount" : "10",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  }, {
    "ticketCount" : "0",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  } ]
}

List tickets by tag

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

Query Params

Param Name
Data Type
Description
from

int

optional

Index number, starting from which tickets must be fetched.

limit

int

optional,
range : 1-100

Number of tickets to list

assignee

string

optional,
max chars : 100

User assigned to resolve the ticket. Values allowed are Unassigned or a valid assigneeId. You can pass multiple assigneeIds as comma-separated values.

channel

string

optional,
max chars : 100

Channel through which the tickets were received. You can pass multiple values by separating them with commas.

status

string

optional,
max chars : 100

Resolution status of the tickets. You can pass multiple values by separating them with commas.

receivedInDays

integer

optional

Number of days since the tickets were received. Values allowed are 15, 30 , 90.

priority

string

optional,
max chars : 100

Priority of the tickets. You can pass multiple values by separating them with commas.

sortBy

string

optional,
max chars : 100

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.

include
see documentation

string

optional,
max chars : 100

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.

GET api/v1/tags/{tag_id}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tags/1892000001010007/tickets?include=assignee,contacts,departments,team,isRead
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : true,
    "language" : "English",
    "closedTime" : null,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8838109870",
      "id" : "1892000000042032",
      "isSpam" : false,
      "type" : "paid",
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "accountId" : "189200000005345",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@zylker.com"
    },
    "isSpam" : false,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Facebook",
    "isRead" : true,
    "closedTime" : null,
    "contact" : {
      "lastName" : "Richard",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "mobile" : "8838109870",
      "id" : "1892000000093203",
      "isSpam" : false,
      "type" : "paid",
      "email" : "richard@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/8920000000069071/logo?orgId=11278831"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@zylker.com"
    },
    "isSpam" : false,
    "status" : "Open"
  } ]
}

Associate Tag

This API adds a single tag or multiple tags to a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
tags

list

required

Names of the tags

POST /api/v1/tickets/{ticket_id}/associateTag

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/associateTag
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "tags" : [ "sample", "ticket", "tag" ]
}'

Response Example

{
  "data" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "ticket",
    "tagType" : "MANUAL",
    "id" : 1232343244
  }, {
    "name" : "tag",
    "tagType" : "SYSTEM",
    "id" : 12323432434
  } ]
}

Dissociate Tag

This API removes a single tag or multiple tags from a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
tags

list

required

Names of the tags

POST /api/v1/tickets/{ticket_id}/dissociateTag

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/dissociateTag
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "tags" : [ "sample", "ticket", "tag" ]
}'

Response Example

200

List tags in a ticket

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

GET api/v1/tickets/{ticket_id}/tags

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/tags
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "tags" : [ {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  }, {
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : 123234324
  } ]
}

List recent tags

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department from which the tags must be fetched

GET api/v1/recentTicketTags

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/recentTicketTags
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketCount" : "10",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  }, {
    "ticketCount" : "0",
    "name" : "sample",
    "tagType" : "MANUAL",
    "id" : "12312312312"
  } ]
}

Update recent tags

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

POST /api/v1/recentTicketTags/{tag_id}

OAuth Scope

Desk.tickets.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/recentTicketTags/42312412421
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Replace the specified tags

This API replaces a tag to the specified tag. tag_id is a mandatory parameter in the API request.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
id

long

optional

Tag ID of the Replacing Tag

PATCH /api/v1/tags/{tag_id}/replace

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tags/12312312312/replace
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "id" : "12312312312"
}'

Response Example

204

Customer Feedback

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.

List all customer feedback

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

Query Params

Param Name
Data Type
Description
department

String

required

Mandatory 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

agentId

Long

optional

Filter that returns the customer-happiness list for a particular agent

contactId

Long

optional

Filter that returns the customer-happiness list for a particular contact

accountId

Long

optional

Filter that returns the customer-happiness list for a particular account

ticketId

Long

optional

Filter that returns the customer-happiness list for a particular ticket

startTime

Long

optional

Start time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

endTime

Long

optional

Start time till which the customer-happiness list should show. End time should be in GMT time zone and in milliseconds

from

int

optional

The starting index from which the list should be displayed based on the time of receiving customer feedback

limit

int

optional,
range : 1-50

Number of ratings to be displayed in the list

rating

string

optional,
max chars : 100

Segregate the list based on the type of rating. Allowed values are good, ok, or bad

duration

string

optional,
max chars : 100

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

startDate

timestamp

optional

start date time

endDate

timestamp

optional

end date time

sortBy

string

optional,
max chars : 100

Sorted by ratedtime

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, tickets, agents. You can include both by separating them with a comma in the query param.

GET api/v1/customerHappiness

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/customerHappiness?authtoken=ae075d0de8621f986c07c1fe256e4243&orgId=1234567&department=3000000023770
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "agentId" : "5000000015959",
    "agent" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000015959/photo",
      "id" : "5000000015959",
      "email" : "jack@zylker.com"
    },
    "ticket" : {
      "ticketNumber" : "118",
      "subject" : "GPS not working",
      "id" : "5000000074060"
    },
    "contactId" : "5000000017055",
    "departmentId" : "5000000056329",
    "rating" : "GOOD",
    "threadId" : "5000000090001",
    "feedback" : "Great Work!!!",
    "accountId" : "5000000017043",
    "ratedTime" : "2021-12-02T14:36:20.291Z",
    "customerRatedTime" : "2021-12-02T09:06:20.291Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Nirmal Kumar",
      "id" : "5000000017055"
    },
    "id" : "5000000090012",
    "ticketId" : "5000000074060"
  }, {
    "agentId" : "5000000015959",
    "agent" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000015959/photo",
      "id" : "5000000015959",
      "email" : "jack@zylker.com"
    },
    "ticket" : {
      "ticketNumber" : "117",
      "subject" : "Apps take time to load",
      "id" : "5000000056151"
    },
    "contactId" : "5000000026602",
    "departmentId" : "5000000042101",
    "rating" : "BAD",
    "threadId" : "5000000092045",
    "feedback" : "The solution provided doesn't seem to work.",
    "accountId" : "-1",
    "ratedTime" : "2018-09-26T10:47:35.936Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Phillip Collins",
      "id" : "5000000026602"
    },
    "id" : "5000000092056",
    "ticketId" : "5000000056151"
  }, {
    "agentId" : "5000000015959",
    "ticket" : {
      "ticketNumber" : "114",
      "subject" : "zPhone battery needs to be fixed",
      "id" : "5000000055051"
    },
    "contactId" : "5000000017055",
    "departmentId" : "5000000012860",
    "rating" : "OKAY",
    "threadId" : "5000000092069",
    "feedback" : "The battery performance is better but I expect a little more.",
    "accountId" : "5000000017043",
    "ratedTime" : "2018-09-26T10:49:16.202Z",
    "timezoneOffset" : "GMT +5:30",
    "contact" : {
      "name" : "Sam Rossner",
      "id" : "5000000017055"
    },
    "id" : "5000000092084",
    "ticketId" : "5000000055051"
  } ]
}

Get customer feedback count

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

Query Params

Param Name
Data Type
Description
department

String

required

Mandatory 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

agentId

Long

optional

Filter that returns the customer-ratings count for a particular agent

contactId

Long

optional

Filter that returns the customer-ratings count for a particular contact

accountId

Long

optional

Filter that returns the customer-ratings count for a particular account

ticketId

Long

optional

Filter that returns the customer-ratings count for a particular ticket

startTime

Long

optional

Start time from which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

endTime

Long

optional

Start time till which the customer-happiness list should show. Start time should be in GMT time zone and in milliseconds

duration

string

optional,
max chars : 100

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

startDate

timestamp

optional

start date time

endDate

timestamp

optional

end date time

from

Integer

optional

The from index

limit

Integer

optional,
range : 1-50

Number of rating to be displayed

GET api/v1/customerHappiness/count

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/customerHappiness/count?authtoken=ae075d0de8621f986c07c1fe256e4243&orgId=1234567&department=30000002344
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "30000002344" : {
    "bad" : 3,
    "ok" : 2,
    "good" : 5
  }
}

Get the customer feedback content

This API retrieves the content of specific customer feedback.

Credit: 1 credit/call

GET api/v1/customerHappiness/{thread_id}/content

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/customerHappiness/5000000085253/content
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "content" : "I appreciate the help and thanks for the quick response."
}

Ticket Templates

Ticket templates are provisions that automatically populate predefined values in ticket fields, thereby helping users save time and effort while adding new tickets.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the ticket template

ticketTemplateName

string

Name of the ticket template

showInCustomerPortal

boolean

Key that specifies if the template must be displayed in the help center or not

layoutId

long

ID of the ticket layout from which the template is derived

ticketTemplateValues

list

Values to auto-populate in the different fields in the template

Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : null,
    "contactId" : null,
    "subject" : null,
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "category" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}


Create ticket template

This API helps create a ticket template in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ticketTemplateName

string

required,
max chars : 200

Name of the ticket template

showInCustomerPortal

boolean

optional

Key that specifies if the template must be displayed in the help center or not

ticketTemplateValues

list

required

Values to auto-populate in the different fields in the template

POST api/v1/ticketTemplates

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/ticketTemplates
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "ticketTemplateValues" : {
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "phone" : "9876545645",
    "departmentId" : "4000000007073",
    "email" : "jacks@zylker.com"
  },
  "layoutId" : "4000000020012"
}'

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : null,
    "contactId" : null,
    "subject" : null,
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "category" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

Get ticket template

This API fetches the details of a particular ticket template.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

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.

GET api/v1/ticketTemplates/{ticketTemplates_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketTemplates/4000000020001?include=departments,assignee,contacts,team,products
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temp1",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "product" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : null,
    "contactId" : null,
    "subject" : null,
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "contact" : null,
    "assignee" : null,
    "department" : {
      "name" : "testing department",
      "id" : "4000000007073"
    },
    "category" : null,
    "account" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

List ticket templates

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the templates must be fetched

departmentId
see documentation

long

optional

ID of the department from which templates must be fetched

layoutId

long

optional

ID of the layout from which templated must be fetched for the given department ID

limit

integer

required,
default : 10,
range : 1-100

Number of templates to list. The default value is 10 and the maximum value supported is 100

showInCustomerPortal

boolean

optional

Visibility of the templates in the help center

templateName 
deprecated

String

optional

Name of the template

searchStr

String

optional

String to search for ticket templates by ticket template name

GET api/v1/ticketTemplates

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketTemplates
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "showInCustomerPortal" : true,
    "ticketTemplateName" : "Template1",
    "id" : "4000000020001",
    "layoutId" : "4000000020121"
  }, {
    "showInCustomerPortal" : false,
    "ticketTemplateName" : "Template2",
    "id" : "4000000020063",
    "layoutId" : "4000000020431"
  } ]
}

Update ticket template

This API helps update the details of a particular ticket template.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ticketTemplateName

string

optional,
max chars : 200

Name of the ticket template

showInCustomerPortal

boolean

optional

Key that specifies if the template must be displayed in the help center or not

ticketTemplateValues

list

optional

Values to auto-populate in the different fields in the template

PATCH api/v1/ticketTemplates/{ticketTemplates_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/ticketTemplates/4000000020001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "showInCustomerPortal" : false,
  "ticketTemplateName" : "temptest",
  "ticketTemplateValues" : {
    "cf" : {
      "cf_severity_percentage" : "60"
    },
    "productId" : "4000000009012",
    "subject" : "UrgentProblem",
    "departmentId" : "4000000007073",
    "email" : "jacks@zylker.com"
  }
}'

Response Example

{
  "showInCustomerPortal" : true,
  "ticketTemplateName" : "temptest",
  "id" : "4000000020001",
  "layoutId" : "4000000020012",
  "ticketTemplateValues" : {
    "subCategory" : null,
    "cf" : {
      "cf_severity_percentage" : "0.0"
    },
    "productId" : "4000000009012",
    "contactId" : null,
    "subject" : "UrgentProblem",
    "departmentId" : "4000000007073",
    "dueDate" : null,
    "channel" : null,
    "description" : null,
    "secondaryContacts" : [ "4000000009076", "4000000009062" ],
    "priority" : null,
    "classification" : null,
    "assigneeId" : null,
    "accountId" : null,
    "phone" : "9876545645",
    "category" : null,
    "email" : "jacks@zylker.com",
    "status" : null
  }
}

Delete ticket template

This API deletes a ticket template from your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ids

list

required

Array of Entity id to be deleted

POST api/v1/ticketTemplates/deleteMany

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/ticketTemplates/deleteMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "4000000083313", "4000000082105" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "2000000021011",
    "errors" : null
  }, {
    "success" : false,
    "id" : "4000000082105",
    "errors" : {
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Tickets Comments

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

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.

isPublic

boolean

Specifies the comment is public or private.

Note: This key's value can only be set when adding a comment.

commenterId

long

ID of the user who added the comment.

commentedTime

timestamp

Time at which the comment was added.

modifiedTime

timestamp

Time at which the comment was last modified.

commenter

object

Details of the user who added the comment.

attachmentIds

list

List of file attachments included in the comment.

Note: For more details on attachments, refer to the Uploads section.

contentType

string

Specifies the type of the content whether html or plainText. The default value is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "carol@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create ticket comment

This API allows you to add a comment to a ticket. To mention an agent or team, use the below format:

  • To mention an agent: zsu[@user:{zuid}]zsu
  • To mention a team: zsu[@team:{teamId}_{teamName}]zsu

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

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.

isPublic

boolean

optional

Specifies the comment is public or private.

Note: This key's value can only be set when adding a comment.

attachmentIds

list

optional

List of file attachments included in the comment.

Note: For more details on attachments, refer to the Uploads section.

contentType

string

optional,
max chars : 100

Specifies the type of the content whether html or plainText. The default value is html.

POST api/v1/tickets/{ticket_id}/comments

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isPublic" : "true",
  "attachmentIds" : [ "4000000008892" ],
  "contentType" : "html",
  "content" : "zsu[@user:11550965]zsu Please fix this ASAP"
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008892",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008892/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.193Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "contentType" : "html",
  "content" : "zsu[@user:11550965]zsu Please fix this ASAP",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update ticket comment

This API allows you to update a comment to a ticket. To mention an agent or team, use the below format:

  • To mention an agent: zsu[@user:{zuid}]zsu
  • To mention a team: zsu[@team:{teamId}_{teamName}]zsu

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

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.

isPublic

boolean

optional

Specifies the comment is public or private.

Note: This key's value can only be set when adding a comment.

attachmentIds

list

optional

List of file attachments included in the comment.

Note: For more details on attachments, refer to the Uploads section.

contentType

string

optional,
max chars : 100

Specifies the type of the content whether html or plainText. The default value is html.

PATCH api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "4000000008994" ],
  "content" : "Edited comment."
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.163Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Fixed the issue.",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete ticket comment

This API deletes a comment.

Credit: 1 credit/call

DELETE api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get ticket comment

This API fetches a ticket comment from your help desk portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary 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.

GET api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.000Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "plainText" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "id" : "4000000529001",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "<div>Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing</div>",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "carol@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all ticket comments

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

Number of comments to fetch

sortBy

string

optional,
max chars : 100

Sort by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary 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.

GET api/v1/tickets/{ticket_id}/comments

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-01-24T14:12:45.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_edited.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:06:58.000Z",
    "isPublic" : true,
    "plainText" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "id" : "4000000529001",
    "contentType" : "html",
    "content" : "<div>Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing</div>",
    "commenterId" : "4000000008692",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "carol@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T14:14:37.000Z",
    "isPublic" : false,
    "plainText" : "zsu[@user:55616589]zsu Please fix this ASAP",
    "id" : "4000000529007",
    "contentType" : "html",
    "content" : "<div>zsu[@user:55616589]zsu Please fix this ASAP</div>",
    "commenterId" : "4000000008692",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "0",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "carol@zylker.com",
      "zuid" : "55616589"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Get a ticket comment history

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the comment activities must be fetched

include
see documentation

String

optional

Secondary 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.

limit

integer

required,
default : 50,
range : 1-100

Number of comment activities to fetch

GET api/v1/tickets/{ticket_id}/comments/{comment_id}/history

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/history
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "attachments" : [ "sample.png", "sam.txt" ],
    "commentedTime" : "2013-11-04T11:21:07.912Z",
    "isPublic" : false,
    "commenterId" : 13231241244,
    "content" : "hello comment",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "CEO",
      "type" : "AGENT",
      "email" : "hagdsag@zylker.com"
    }
  }, {
    "attachments" : [ "sample.png", "sam.txt" ],
    "commentedTime" : "2013-11-04T11:21:07.912Z",
    "isPublic" : true,
    "commenterId" : 13231241244,
    "content" : "hello comment",
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "hagdsag@zylker.com"
    }
  } ]
}

Contacts Comments

Contact comments refer to comments recorded on contacts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create a contact comment

This API adds a comment to a contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/contacts/{contact_id}/comments

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000530041/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First contact comment"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:34:56.358Z",
  "id" : "4000000530043",
  "contentType" : "html",
  "content" : "First contact comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a contact comment

This API updates an existing contact comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530045
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "second contact comment edit"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:35:23.000Z",
  "id" : "4000000530045",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second contact comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a contact comment

This API deletes an existing contact comment.

Credit: 1 credit/call

DELETE api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530037
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get a contact comment

This API fetches a contact comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contacts/{contact_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000530041/comments/4000000530043?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:34:56.000Z",
  "id" : "4000000530043",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all contact comments

This API lists a particular number of comments recorded on a contact, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contacts/{contact_id}/comments

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000530041/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:35:23.000Z",
    "id" : "4000000530045",
    "contentType" : "plainText",
    "content" : "second contact comment",
    "commenterId" : "4000000008692",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:34:56.000Z",
    "id" : "4000000530043",
    "contentType" : "html",
    "content" : "First contact comment",
    "commenterId" : "4000000008692",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "CEO",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Accounts Comments

Account comments refer to comments made on accounts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create an account comment

This API adds a comment to an account.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/accounts/{account_id}/comments

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First account comment"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:45:21.167Z",
  "id" : "4000000530047",
  "contentType" : "html",
  "content" : "First account comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update an account comment

This API updates an existing account comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "second account comment edit"
}'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T19:45:21.000Z",
  "id" : "4000000530047",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second account comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete an account comment

This API deletes an existing account comment.

Credit: 1 credit/call

DELETE api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get an account comment

This API fetches an account comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/accounts/{account_id}/comments/{comment_id}

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/comments/4000000530047?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-01-24T19:46:24.000Z",
  "commentedTime" : "2017-01-24T19:45:21.000Z",
  "id" : "4000000530047",
  "contentType" : "plainText",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "4000000008692",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all account comments

This API lists a particular number of comments recorded on an account, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched.

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/accounts/{account_id}/comments

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:45:55.000Z",
    "id" : "4000000530049",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    }, {
      "offSet" : "59",
      "departmentId" : "3113800000634345",
      "length" : "26",
      "id" : "3113800000143134",
      "type" : "TICKET"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T19:46:24.000Z",
    "commentedTime" : "2017-01-24T19:45:21.000Z",
    "id" : "4000000530047",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    }, {
      "offSet" : "59",
      "departmentId" : "3113800000634345",
      "entityNumber" : "1342",
      "length" : "26",
      "name" : "",
      "id" : "3113800000143134",
      "type" : "TICKET"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Tasks Comments

Task comments refer to comments recorded on tasks assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create a task comment

This API adds a comment to a task.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/tasks/{task_id}/comments

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tasks/4000000530001/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First Task comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Task comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a task comment

This API updates an existing task comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "Edit Task comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Task comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a task comment

This API deletes an existing task comment.

Credit: 1 credit/call

DELETE api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get a task comment

This API fetches a task comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tasks/{task_id}/comments/{comment_id}

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000530001/comments/4000000530005?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Task Comment......",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all task comments

This API lists a particular number of comments recorded on a task, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/tasks/{task_id}/comments

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000530001/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Second Task Comment......",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/tasks/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Task comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Articles Comments

Article comments refer to comments recorded on help articles in the knowledge base. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu. To retrieve or set enduser mentions, use this code format: zsu[@enduser:{zuid}]zsu. To retrieve or set group mentions use this code format: zsu[@group:{groupid}]zsu. To retrieve or set hashtags, use this code format: zsh[#{HEADER_DATA}]zsh.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

isPublic

boolean

Used to check whether the added comment is a Public Comment or a Private Comment

ticketId

long

ID of the Ticket is shown once the comment is converted as Ticket. By default null

ticket

object

Details of the ticket is shown once the comment is converted as Ticket

mentions

object

Mentions Can be of Two Types UserMentions and GroupMention

Example

{
  "modifiedTime" : "2022-05-09T13:10:29.000Z",
  "attachments" : [ {
    "previewurl" : "https://desk.zoho.com/api/v1/articles/46582000006958052/translations/en/attachments/nmhny14ce774984eb4b15891e1cbe274e612c/content?orgId=57044830",
    "size" : "35594",
    "name" : "Zoho desk introduction.jpg",
    "id" : "4658200041001",
    "href" : "https://downloadserver.zoho.com/webdownload?x-service=desk&event-id=b45a36decdceb443ccb4d3445f29c9966de7dee89041ea315318c4f358836a09e07add42e10810f8961c3f92bf853"
  } ],
  "tickets" : {
    "ticketNumber" : "115",
    "isTrashed" : "false",
    "webUrl" : "https://desk.zoho.com/agent/zohocorp/desk/tickets/details/5000000114001",
    "id" : "5000000114001"
  },
  "hashtags" : [ {
    "offset" : "47",
    "length" : "33",
    "headerValue" : "Introduction",
    "headerId" : "Sample_header"
  } ],
  "commentedTime" : "2022-05-09T05:09:00.000Z",
  "commenterName" : "Jack",
  "content" : "<div>Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>",
  "commenterId" : "4658200004039",
  "commenter" : {
    "firstName" : "",
    "lastName" : "Jack",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200004039/photo?orgId=292828",
    "webUrl" : "https://desk.zoho.com/support/arunice/ShowHomePage.do#setup/users-control/agents/1000000000351",
    "roleName" : "CEO",
    "name" : "Jack",
    "id" : "4658200004039",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#5C6368",
        "textColor" : "#FFFFFF"
      },
      "name" : "MVP",
      "id" : "5000000081007",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
    },
    "type" : "AGENT",
    "email" : "Jack@gmail.com",
    "kbRole" : "REVIEWER"
  },
  "mentions" : {
    "groups" : [ {
      "offSet" : "260",
      "name" : "MVP",
      "length" : "28",
      "id" : "5000000113025",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/4658200004039?portalId=292828341431fq"
    } ],
    "users" : [ {
      "firstName" : "",
      "lastName" : "Cristiano",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200044017/photo?orgId=292828",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
      "length" : "28",
      "name" : "Cristiano",
      "id" : "4658200044017",
      "label" : {
        "preferences" : {
          "shape" : "ROUNDED",
          "bgColor" : "#CE6785",
          "textColor" : "#FFFFFF"
        },
        "name" : "Prime user",
        "id" : "5000000081001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n8"
      },
      "type" : "AGENT",
      "email" : "Cristiano@gmail.com",
      "zuid" : "695624",
      "kbRole" : "REVIEWER"
    } ]
  },
  "isPublic" : false,
  "id" : "4658200041003",
  "contentType" : "html",
  "ticketId" : "5000000114001"
}


Create a translation comment

This API adds a comment to an article translation.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

required,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: AGENT : zsu[@user:{zuid}]zsu, Enduser : zsu[@enduser:{zuid}]zsu, Group : zsu[@group:{groupid}]zsu, HashTag : zsh[#{HEADER_DATA}]zsh.

isPublic

boolean

required

Visibility of the comment, which can be set only at the time of commenting.

contentType

string

required,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/articles/{article_id}/translations/{locale}/comments

OAuth Scope

Desk.articles.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isPublic" : "false",
  "attachmentIds" : [ "4658200041001" ],
  "contentType" : "html",
  "content" : "<div>Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>"
}'

Response Example

{
  "modifiedTime" : "2022-05-09T13:10:29.000Z",
  "attachments" : [ {
    "previewurl" : "https://desk.zoho.com/api/v1/articles/46582000006958052/translations/en/attachments/nmhny14ce774984eb4b15891e1cbe274e612c/content?orgId=57044830",
    "size" : "35594",
    "name" : "Zoho desk introduction.jpg",
    "id" : "4658200041001",
    "href" : "https://downloadserver.zoho.com/webdownload?x-service=desk&event-id=b45a36decdceb443ccb4d3445f29c9966de7dee89041ea315318c4f358836a09e07add42e10810f8961c3f92bf853"
  } ],
  "tickets" : {
    "ticketNumber" : "115",
    "isTrashed" : "false",
    "webUrl" : "https://desk.zoho.com/agent/zohocorp/desk/tickets/details/5000000114001",
    "id" : "5000000114001"
  },
  "hashtags" : [ {
    "offset" : "47",
    "length" : "33",
    "headerValue" : "Introduction",
    "headerId" : "Sample_header"
  } ],
  "commentedTime" : "2022-05-09T05:09:00.000Z",
  "commenterName" : "Jack",
  "content" : "<div>Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>",
  "commenterId" : "4658200004039",
  "commenter" : {
    "firstName" : "",
    "lastName" : "Jack",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200004039/photo?orgId=292828",
    "webUrl" : "https://desk.zoho.com/support/arunice/ShowHomePage.do#setup/users-control/agents/1000000000351",
    "roleName" : "CEO",
    "name" : "Jack",
    "id" : "4658200004039",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#5C6368",
        "textColor" : "#FFFFFF"
      },
      "name" : "MVP",
      "id" : "5000000081007",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
    },
    "type" : "AGENT",
    "email" : "Jack@gmail.com",
    "kbRole" : "REVIEWER"
  },
  "mentions" : {
    "groups" : [ {
      "offSet" : "260",
      "name" : "MVP",
      "length" : "28",
      "id" : "5000000113025",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/4658200004039?portalId=292828341431fq"
    } ],
    "users" : [ {
      "firstName" : "",
      "lastName" : "Cristiano",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200044017/photo?orgId=292828",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
      "length" : "28",
      "name" : "Cristiano",
      "id" : "4658200044017",
      "label" : {
        "preferences" : {
          "shape" : "ROUNDED",
          "bgColor" : "#CE6785",
          "textColor" : "#FFFFFF"
        },
        "name" : "Prime user",
        "id" : "5000000081001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n8"
      },
      "type" : "AGENT",
      "email" : "Cristiano@gmail.com",
      "zuid" : "695624",
      "kbRole" : "REVIEWER"
    } ]
  },
  "isPublic" : false,
  "id" : "4658200041003",
  "contentType" : "html",
  "ticketId" : "5000000114001",
  "status" : "PUBLISHED"
}

Update a translation comment

This API updates an existing article translation comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: AGENT : zsu[@user:{zuid}]zsu, Enduser : zsu[@enduser:{zuid}]zsu, Group : zsu[@group:{groupid}]zsu, HashTag : zsh[#{HEADER_DATA}]zsh.

isPublic

boolean

optional

Visibility of the comment, which can be set only at the time of commenting.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4658200041003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isPublic" : true,
  "attachmentIds" : [ "4658200041001" ],
  "contentType" : "html",
  "content" : "<div>Changed Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>"
}'

Response Example

{
  "modifiedTime" : "2022-05-09T13:10:29.000Z",
  "attachments" : [ {
    "previewurl" : "https://desk.zoho.com/api/v1/articles/46582000006958052/translations/en/attachments/nmhny14ce774984eb4b15891e1cbe274e612c/content?orgId=57044830",
    "size" : "35594",
    "name" : "Zoho desk introduction.jpg",
    "id" : "4658200041001",
    "href" : "https://downloadserver.zoho.com/webdownload?x-service=desk&event-id=b45a36decdceb443ccb4d3445f29c9966de7dee89041ea315318c4f358836a09e07add42e10810f8961c3f92bf853"
  } ],
  "tickets" : {
    "ticketNumber" : "115",
    "isTrashed" : "false",
    "webUrl" : "https://desk.zoho.com/agent/zohocorp/desk/tickets/details/5000000114001",
    "id" : "5000000114001"
  },
  "hashtags" : [ {
    "offset" : "47",
    "length" : "33",
    "headerValue" : "Introduction",
    "headerId" : "Sample_header"
  } ],
  "commentedTime" : "2022-05-09T05:09:00.000Z",
  "commenterName" : "Jack",
  "content" : "<div>Changed Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>",
  "commenterId" : "4658200004039",
  "commenter" : {
    "firstName" : "",
    "lastName" : "Jack",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200004039/photo?orgId=292828",
    "webUrl" : "https://desk.zoho.com/support/arunice/ShowHomePage.do#setup/users-control/agents/1000000000351",
    "roleName" : "CEO",
    "name" : "Jack",
    "id" : "4658200004039",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#5C6368",
        "textColor" : "#FFFFFF"
      },
      "name" : "MVP",
      "id" : "5000000081007",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
    },
    "type" : "AGENT",
    "email" : "Jack@gmail.com",
    "kbRole" : "REVIEWER"
  },
  "mentions" : {
    "groups" : [ {
      "offSet" : "260",
      "name" : "MVP",
      "length" : "28",
      "id" : "5000000113025",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/4658200004039?portalId=292828341431fq"
    } ],
    "users" : [ {
      "firstName" : "",
      "lastName" : "Cristiano",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200044017/photo?orgId=292828",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
      "length" : "28",
      "name" : "Cristiano",
      "id" : "4658200044017",
      "label" : {
        "preferences" : {
          "shape" : "ROUNDED",
          "bgColor" : "#CE6785",
          "textColor" : "#FFFFFF"
        },
        "name" : "Prime user",
        "id" : "5000000081001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n8"
      },
      "type" : "AGENT",
      "email" : "Cristiano@gmail.com",
      "zuid" : "695624",
      "kbRole" : "REVIEWER"
    } ]
  },
  "isPublic" : true,
  "id" : "4658200041003",
  "contentType" : "html",
  "ticketId" : "5000000114001",
  "status" : "PUBLISHED"
}

Delete a translation comment

This API deletes an existing article translation comment.

Credit: 1 credit/call

DELETE api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4658200041003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get a article translation comment

This API fetches an article translation comment from the portal.

Credit: 1 credit/call

GET api/v1/articles/{article_id}/translations/{locale}/comments/{comment_id}

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments/4658200041003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2022-05-09T13:10:29.000Z",
  "attachments" : [ {
    "previewurl" : "https://desk.zoho.com/api/v1/articles/46582000006958052/translations/en/attachments/nmhny14ce774984eb4b15891e1cbe274e612c/content?orgId=57044830",
    "size" : "35594",
    "name" : "Zoho desk introduction.jpg",
    "id" : "4658200041001",
    "href" : "https://downloadserver.zoho.com/webdownload?x-service=desk&event-id=b45a36decdceb443ccb4d3445f29c9966de7dee89041ea315318c4f358836a09e07add42e10810f8961c3f92bf853"
  } ],
  "tickets" : {
    "ticketNumber" : "115",
    "isTrashed" : "false",
    "webUrl" : "https://desk.zoho.com/agent/zohocorp/desk/tickets/details/5000000114001",
    "id" : "5000000114001"
  },
  "hashtags" : [ {
    "offset" : "47",
    "length" : "33",
    "headerValue" : "Introduction",
    "headerId" : "Sample_header"
  } ],
  "commentedTime" : "2022-05-09T05:09:00.000Z",
  "commenterName" : "Jack",
  "content" : "<div>Changed Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>",
  "commenterId" : "4658200004039",
  "commenter" : {
    "firstName" : "",
    "lastName" : "Jack",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200004039/photo?orgId=292828",
    "webUrl" : "https://desk.zoho.com/support/arunice/ShowHomePage.do#setup/users-control/agents/1000000000351",
    "roleName" : "CEO",
    "name" : "Jack",
    "id" : "4658200004039",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#5C6368",
        "textColor" : "#FFFFFF"
      },
      "name" : "MVP",
      "id" : "5000000081007",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
    },
    "type" : "AGENT",
    "email" : "Jack@gmail.com",
    "kbRole" : "REVIEWER"
  },
  "mentions" : {
    "groups" : [ {
      "offSet" : "260",
      "name" : "MVP",
      "length" : "28",
      "id" : "5000000113025",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/4658200004039?portalId=292828341431fq"
    } ],
    "users" : [ {
      "firstName" : "",
      "lastName" : "Cristiano",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200044017/photo?orgId=292828",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
      "length" : "28",
      "name" : "Cristiano",
      "id" : "4658200044017",
      "label" : {
        "preferences" : {
          "shape" : "ROUNDED",
          "bgColor" : "#CE6785",
          "textColor" : "#FFFFFF"
        },
        "name" : "Prime user",
        "id" : "5000000081001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n8"
      },
      "type" : "AGENT",
      "email" : "Cristiano@gmail.com",
      "zuid" : "695624",
      "kbRole" : "REVIEWER"
    } ]
  },
  "isPublic" : true,
  "id" : "4658200041003",
  "contentType" : "html",
  "ticketId" : "5000000114001",
  "status" : "PUBLISHED"
}

List all translation comments

This API lists a particular number of comments recorded on an article translation, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

required,
default : 1,
range : >0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 5,
range : 1-10

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. -commentedTime denotes descending order of sorting.

include

string

optional,
max chars : 100

Allowed values ticket

GET api/v1/articles/{article_id}/translations/{locale}/comments

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articles/4000000530033/translations/en-us/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2022-05-09T13:10:29.000Z",
    "attachments" : [ {
      "previewurl" : "https://desk.zoho.com/api/v1/articles/46582000006958052/translations/en/attachments/nmhny14ce774984eb4b15891e1cbe274e612c/content?orgId=57044830",
      "size" : "35594",
      "name" : "Zoho desk introduction.jpg",
      "id" : "4658200041001",
      "href" : "https://downloadserver.zoho.com/webdownload?x-service=desk&event-id=b45a36decdceb443ccb4d3445f29c9966de7dee89041ea315318c4f358836a09e07add42e10810f8961c3f92bf853"
    } ],
    "tickets" : {
      "ticketNumber" : "115",
      "isTrashed" : "false",
      "webUrl" : "https://desk.zoho.com/agent/zohocorp/desk/tickets/details/5000000114001",
      "id" : "5000000114001"
    },
    "hashtags" : [ {
      "offset" : "47",
      "length" : "33",
      "headerValue" : "Introduction",
      "headerId" : "Sample_header"
    } ],
    "commentedTime" : "2022-05-09T05:09:00.000Z",
    "commenterName" : "Jack",
    "content" : "<div>Changed Sample content zsu[@user:695624]zsu&nbsp; zsh[#sample_header:Introduction]zsh&nbsp;</div>",
    "commenterId" : "4658200004039",
    "commenter" : {
      "firstName" : "",
      "lastName" : "Jack",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200004039/photo?orgId=292828",
      "webUrl" : "https://desk.zoho.com/support/arunice/ShowHomePage.do#setup/users-control/agents/1000000000351",
      "roleName" : "CEO",
      "name" : "Jack",
      "id" : "4658200004039",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#5C6368",
          "textColor" : "#FFFFFF"
        },
        "name" : "MVP",
        "id" : "5000000081007",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
      },
      "type" : "AGENT",
      "email" : "Jack@gmail.com",
      "kbRole" : "REVIEWER"
    },
    "mentions" : {
      "groups" : [ {
        "offSet" : "260",
        "name" : "MVP",
        "length" : "28",
        "id" : "5000000113025",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/4658200004039?portalId=292828341431fq"
      } ],
      "users" : [ {
        "firstName" : "",
        "lastName" : "Cristiano",
        "photoURL" : "https://desk.zoho.com/api/v1/agents/4658200044017/photo?orgId=292828",
        "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
        "length" : "28",
        "name" : "Cristiano",
        "id" : "4658200044017",
        "label" : {
          "preferences" : {
            "shape" : "ROUNDED",
            "bgColor" : "#CE6785",
            "textColor" : "#FFFFFF"
          },
          "name" : "Prime user",
          "id" : "5000000081001",
          "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n8"
        },
        "type" : "AGENT",
        "email" : "Cristiano@gmail.com",
        "zuid" : "695624",
        "kbRole" : "REVIEWER"
      } ]
    },
    "isPublic" : true,
    "id" : "4658200041003",
    "contentType" : "html",
    "ticketId" : "5000000114001",
    "status" : "PUBLISHED"
  } ]
}

Contracts Comments

Contract comments refer to comments recorded on SLA contracts in the portal, for the reference of other agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create a contract comment

This API adds a comment to a contract.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/contracts/{contract_id}/comments

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contracts/4000000230035/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First contract comment"
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008892",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008892/content"
  } ],
  "commentedTime" : "2017-01-24T19:49:34.472Z",
  "id" : "4000000530051",
  "contentType" : "html",
  "content" : "First contract comment",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a contract comment

This API updates an existing contract comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "second contract comment edit"
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T19:50:08.000Z",
  "id" : "4000000530053",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "second contract comment edit",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a contract comment

This API deletes an existing contract comment.

Credit: 1 credit/call

DELETE api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get a contract comment

This API fetches a contract comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contracts/{contract_id}/comments/{comment_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contracts/4000000230035/comments/4000000530053?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-01-24T19:50:40.000Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T19:50:08.000Z",
  "id" : "4000000530053",
  "contentType" : "plainText",
  "content" : "second contract comment edit",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}

List all contract comment

This API lists a particular number of comments recorded on a contract, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

sortby can be commentedTime. default order : commentedTime in descending order , prefix - denotes desc

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/contracts/{contract_id}/comments

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contracts/4000000230035/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-01-24T19:50:40.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_edited.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/contracts/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T19:50:08.000Z",
    "id" : "4000000530053",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "second contract comment edit",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo?orgId=292828",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T19:49:34.000Z",
    "id" : "4000000530051",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "First contract comment",
    "mention" : [ ]
  } ]
}

Uploads

Uploads are temporary file attachments that exist with a ticket for a period of 24 hours.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "size" : "4769",
  "creatorId" : "4000000008692",
  "name" : "zoho.jpeg",
  "createdTime" : "2016-06-23T07:31:42.000Z",
  "isPublic" : false,
  "id" : "4000000055001"
}


Upload file

This API uploads a file.

Note:
This API call generates a unique ID only that can be associated with a single parent entity.
Refer to additional information regarding, bulk upload in custom functions.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description

File Params

file

Content-Type:multipart/form-data

File to attach

POST /api/v1/uploads

OAuth Scope

Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/uploads
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "size" : "4769",
  "creatorId" : "4000000008692",
  "name" : "zoho.jpeg",
  "createdTime" : "2016-06-23T07:31:42.000Z",
  "isPublic" : false,
  "id" : "4000000055001",
  "href" : "https://desk.zoho.com/api/v1/uploads/1892000001008043/contents"
}

Ticket Attachments

Ticket attachments are files you attach to a ticket to aid quick resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "creator" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
    "id" : "1892000000047001",
    "email" : "jade@zylker.com"
  },
  "size" : "1079",
  "creatorId" : "1892000000047001",
  "name" : "ScreenShot",
  "createdTime" : "2013-11-06T10:25:03.000Z",
  "isPublic" : true,
  "id" : "1892000000047041",
  "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content"
}


List ticket attachments

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

Query Params

Param Name
Data Type
Description
sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

isPublic

Boolean

optional

Key that returns if the attachment is public or no

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/tickets/{ticket_id}/attachments

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments?include=creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> GetTicketAttachmentsFilter filter = new GetTicketAttachmentsFilter.Builder().setIsPublic(isPublic).build(); <br/> List&lt;Attachment&gt; response = attachment.getTicketAttachments( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "issues.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : true,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "guidelines.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : true,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "CreditHistory.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "values.txt",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Ticket attachment

This API attaches a file to a ticket.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
isPublic

Boolean

optional

Field that determines whether the attachment is public or private

File Params

file

Content-Type:multipart/form-data

File to attach to the ticket

POST /api/v1/tickets/{ticket_id}/attachments

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.createTicketAttachment( file, ticketId, filter );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042001",
  "name" : "issues.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001/content"
}

Update Ticket attachment

This API updates an existing attachment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isPublic

boolean

optional

Whether to Show

PATCH /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL
  • Java

$ curl -X PATCH https://desk .zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isPublic" : true
}'

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.updateTicketAttachment( attachmentId, ticketId, attachmentObj );

Response Example

200

Delete Ticket attachment

This API deletes an attachment from a ticket.

Credit: 1 credit/call

DELETE /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL
  • Java

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> boolean response = attachment.deleteTicketAttachment( attachmentId, ticketId );

Response Example

200

Contacts Attachments

Contact attachments are files you attach to a contact to provide more context and reference information to other users.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "creator" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
    "id" : "1892000000047001",
    "email" : "jade@zylker.com"
  },
  "size" : "2345",
  "creatorId" : "1892000000047001",
  "name" : "contact_details.txt",
  "createdTime" : "2013-11-06T10:25:03.000Z",
  "isPublic" : false,
  "id" : "1892000000047042",
  "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content"
}


List Contact Attachments

This API lists the files attached to a contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/contacts/{contact_id}/attachments

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments?include=creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> List&lt;Attachment&gt; response = attachment.getContactAttachments( contactId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "creation.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "profile.jpg",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "contact_MobileNo.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "contact_profile.jpg",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Contact Attachment

This API attaches a file to a contact.

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

File to attach to the contact

POST /api/v1/contacts/{contact_id}/attachments

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.createContactAttachment( file, contactId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "profile.jpg",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001/content"
}

Delete Contact attachment

This API removes an attachment from a contact.

Credit: 1 credit/call

DELETE /api/v1/contacts/{contact_id}/attachments/{attachment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL
  • Java

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> boolean response = attachment.deleteContactAttachment( contactId, attachmentId );

Response Example

200

Accounts Attachments

Account attachments are files you attach to an account to provide more context and reference information to other users.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "creator" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
    "id" : "1892000000047001",
    "email" : "jade@zylker.com"
  },
  "size" : "2345",
  "creatorId" : "1892000000047001",
  "name" : "Associated_contacts.txt",
  "createdTime" : "2013-11-06T10:25:03.000Z",
  "isPublic" : false,
  "id" : "1892000000047042",
  "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content"
}


List Account attachments

This API lists the files attached to an account.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/accounts/{account_id}/attachments

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments?include=creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> List&lt;Attachment&gt; response = attachment.getAccountAttachments( accountId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "profile_photo.jpg",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "profile.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000089041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "logo.jpg",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "profile.pdf",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create Account attachment

This API attaches a file to an account.

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

File to attach to the account

POST /api/v1/accounts/{account_id}/attachments

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.createAccountAttachment( file, accountId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "AccountDetails.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001/content"
}

Delete Account attachment

This API deletes an attachment from a account.

Credit: 1 credit/call

DELETE /api/v1/accounts/{account_id}/attachments/{attachment_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL
  • Java

$ curl -X DELETE https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> boolean response = attachment.deleteAccountAttachment( accountId, attachmentId );

Response Example

200

Contact Deduplication

Deduplication refers to identifying multiple resources containing the same information and consolidating them into a single, unique resource. The process of deduplicating multiple entries of the same contact is called contact deduplication.

Example

[ {
  "fieldValue" : "Jade",
  "contacts" : [ {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000091433",
    "firstName" : "Jonathan",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
    "phone" : "555555",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "email" : "case@zylker.com"
  }, {
    "lastName" : "Jade",
    "secondaryEmail" : null,
    "ownerId" : null,
    "type" : null,
    "accountId" : "1892000000052077",
    "firstName" : "Christ",
    "photoURL" : null,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "isSpam" : false,
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
} ]


List duplicate contacts

This API lists the duplicate entries of a contact.The fieldName parameters is mandatory in the API request

Note:
If you encounter a 202 status code while executing this API request, it means there are 100,000 or more contacts in the help desk portal. Matching the records and finding duplicates will be time-consuming in such a scenario. Therefore, the deduplication request will be accepted, and after the process is completed, an automated report will be sent to the user who initiated the deduplication.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
fieldName

string

optional,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
firstName,

lastName,

email,

secondaryEmail,

phone,

fullName,
and
bothEmail.

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the contacts must be fetched

limit

integer

optional,
range : 1-100

Number of contacts to fetch

sortBy

string

optional,
max chars : 100

Key that sorts the contacts by a specific attribute: count or fieldValue. The default sorting order is ascending. A - prefix denotes descending order of sorting

swFieldValue

string

optional,
max chars : 100

Key that specifies the letter with which the field values must start

GET /api/v1/groupContactDuplicateValues

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groupContactDuplicateValues
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "count" : 16,
    "fieldValue" : "Jade"
  }, {
    "count" : 2,
    "fieldValue" : "saran"
  } ]
}

List details of duplicate contacts

This API lists all the details of duplicate contacts.The fieldName and fieldValues parameters are mandatory in the API request

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
fieldName

string

required,
max chars : 100

Name of the field whose values must be matched for deduplication. Values allowed are:
firstName,

lastName,

email,

secondaryEmail,

phone,

fullName,
and
bothEmail.

sortBy

string

optional,
max chars : 100

Key that sorts the contacts by a specific attribute: 
firstName,

lastName,

fullName,

phone,

email,

account,

createdTime,

modifiedTime

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the contacts must be fetched

limit

integer

optional,
range : 1-100

Number of contacts to fetch

fieldValues

string

required,
max chars : 10000

Actual values in each field related to the contact

include
see documentation

list

optional

Secondary information related to the contact. Value allowed is: accounts

GET /api/v1/groupContacts

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groupContacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldValue" : "Jade",
    "contacts" : [ {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000091433",
      "firstName" : "Jonathan",
      "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
      "phone" : "555555",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : null,
      "id" : "1892000000772003",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "0",
        "okPercentage" : "0",
        "goodPercentage" : "0"
      },
      "email" : "case@zylker.com"
    }, {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000052077",
      "firstName" : "Christ",
      "photoURL" : null,
      "phone" : null,
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : {
        "id" : "1892000000772030",
        "type" : "contacts_leads"
      },
      "id" : "1892000000772001",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "22",
        "okPercentage" : "31",
        "goodPercentage" : "47"
      },
      "email" : "jade@zylker.com"
    } ]
  }, {
    "fieldValue" : "Christ",
    "contacts" : [ {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000091433",
      "firstName" : "Christ",
      "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo",
      "phone" : "555555",
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : null,
      "id" : "1892000000772003",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "0",
        "okPercentage" : "0",
        "goodPercentage" : "0"
      },
      "email" : "case@zylker.com"
    }, {
      "lastName" : "Jade",
      "secondaryEmail" : null,
      "ownerId" : null,
      "type" : null,
      "accountId" : "1892000000052077",
      "firstName" : "Christ",
      "photoURL" : null,
      "phone" : null,
      "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
      "createdTime" : "2017-10-12T13:11:50.000Z",
      "zohoCRMContact" : {
        "id" : "1892000000772030",
        "type" : "contacts_leads"
      },
      "id" : "1892000000772001",
      "isSpam" : false,
      "customerHappiness" : {
        "badPercentage" : "22",
        "okPercentage" : "31",
        "goodPercentage" : "47"
      },
      "email" : "jade@zylker.com"
    } ]
  } ]
}

Get name of default field

This API fetches the name of the field set as the default field for contact deduplication.

Credit: 1 credit/call

GET /api/v1/contactsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contactsDeduplication/defaultFieldName
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldName" : "email"
}

Set default field for contact deduplication

This API sets the field you specify as the default field for deduplicating contacts.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
fieldName

string

required,
max chars : 100

The name of the field

markDefault

boolean

required

to mark the given field as default or remove the field from the default.

POST /api/v1/contactsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contactsDeduplication/defaultFieldName
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "email",
  "markDefault" : true
}'

Response Example

204

Account Deduplication

The process of deduplicating multiple entries of the same account is called account deduplication

Example

{
  "accounts" : [ {
    "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",
    "id" : "1892000000052077",
    "email" : "admin@zylker.com"
  }, {
    "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",
    "id" : "1892000000052077",
    "email" : "admin@zylker.com"
  } ],
  "fieldValue" : "Admin Account"
}


List duplicate accounts

This API lists the duplicate entries of an account.The fieldName parameters is mandatory in the API request

Note:
If you encounter a 202 status code while executing this API request, it means there are 100,000 or more accounts in the help desk portal. Matching the records and finding duplicates will be time-consuming in such a scenario. Therefore, the deduplication request will be accepted, and after the process is completed, an automated report will be sent to the user who initiated the deduplication.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
fieldName

string

optional,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
email,

phone,
and
accountName

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

swFieldValue

string

optional,
max chars : 100

Key that specifies the letter with which the field values must start

sortBy

string

optional,
max chars : 100

Key that sorts the accounts by a specific attribute: count or fieldValue. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/groupAccountDuplicateValues

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groupAccountDuplicateValues
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "count" : 16,
    "fieldValue" : "Admin Account"
  }, {
    "count" : 2,
    "fieldValue" : "Agent Account"
  } ]
}

List details of duplicate accounts

This API lists all the details of duplicate accounts.The fieldName and fieldValues parameters are mandatory in the API request

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
fieldName

string

required,
max chars : 100

Name of the field whose values must be matched for deduplication.Values allowed are:
email,

phone,
and
accountName

from

integer

optional,
default : 0,
range : >=0

Index number starting from which the accounts must be fetched

limit

integer

optional,
range : 1-100

Number of accounts to fetch

fieldValues

string

required,
max chars : 10000

Actual values in each field related to the account

sortBy

string

optional,
max chars : 100

Key that sorts the accounts by a specific attribute: accountName or createdTime or modifiedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/groupAccounts

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/groupAccounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "accounts" : [ {
      "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" : null,
      "id" : "1892000000052077",
      "email" : "admin@zylker.com"
    }, {
      "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" : null,
      "id" : "1892000000052077",
      "email" : "admin@zylker.com"
    } ],
    "fieldValue" : "Admin Account"
  }, {
    "accounts" : [ {
      "website" : "112121",
      "accountName" : "Agent 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"
      },
      "id" : "1892000000052077",
      "email" : "agent@zylker.com"
    }, {
      "website" : "112121",
      "accountName" : "Agent 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"
      },
      "id" : "1892000000052077",
      "email" : "agent@zylker.com"
    } ],
    "fieldValue" : "Agent Account"
  } ]
}

Get Default Field Name

This API fetches the name of the field set as the default field for account deduplication.

Credit: 1 credit/call

GET /api/v1/accountsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accountsDeduplication/defaultFieldName
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldName" : "email"
}

Set default field for account deduplication

This API sets the field you specify as the default field for deduplicating accounts.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
fieldName

string

required,
max chars : 100

The name of the field

markDefault

boolean

required

to mark the given field as default or remove the field from the default.

POST /api/v1/accountsDeduplication/defaultFieldName

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accountsDeduplication/defaultFieldName
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "accountName",
  "markDefault" : true
}'

Response Example

204

Entity Followers

Followers API will be following the entity like articles, kbCategory and notify the followers on any updates

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the user

firstName

string

First Name of the user

lastName

string

Last Name of the user

name

string

DisplayName of the user

email

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

webURL

string

URL to access the agent details.

userType

string

Type of the user followed the entity (Agents | Endusers)

moduleAPIName

string

moduleAPIName refers to API name of modules in Desk. allowedValues are (
articleTranslations
,
kbRootCategories
,
kbSections
)

entityId

long

Unique Id for the specified entity as moduleAPIName

label

object

Label details of the user

Example

{
  "firstName" : "",
  "lastName" : "deskagent",
  "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo?orgId=3115331",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
  "name" : "Desk Agent",
  "id" : "5000000012902",
  "label" : {
    "preferences" : {
      "shape" : "RECTANGLE",
      "bgColor" : "#5C6368",
      "textColor" : "#FFFFFF"
    },
    "name" : "MVP",
    "id" : "5000000081009",
    "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
  },
  "userType" : "AGENT",
  "email" : "deskagent@zylker.com"
}


Get Entity followers count

This API fetches the count of follower list based on given filter

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
userType

String

optional

To get the followers count based on userType allowed values
AGENTS
,
END_USERS
, default value : all users will be processed

GET /api/v1/{moduleAPIName}/{entityId}/followersCount

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleTranslations/4000000190069/followersCountuserType=END_USER
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 289
}

Get Entity followers details

This API fetches the list of follower details based on the given filter

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
userType

String

optional

To get the followers based on userType allowed values
AGENTS
,
END_USERS
, default value : all users will be processed

from

integer

required,
default : 1,
range : >=0

Index number, starting from which the followers must be listed. Default value is 1.

limit

integer

optional,
range : 1-100

Number of followers to list

GET /api/v1/{moduleAPIName}/{entityId}/followers

OAuth Scope

Desk.articles.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/articleTranslations/4000000190069/followers?userType=AGENT&from=1&limit=1
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo?orgId=3115331",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#setup/users-control/agents/5000000000347",
    "name" : "Desk Agent",
    "id" : "5000000012902",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#5C6368",
        "textColor" : "#FFFFFF"
      },
      "name" : "MVP",
      "id" : "5000000081009",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/35531135311?portalId=3153815r1fnf113131rf31n9"
    },
    "userType" : "AGENT",
    "email" : "deskagent@zylker.com"
  } ]
}

Account Followers

Account followers are users who follow an account to track the tickets raised from the account and the support provided.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

email

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

Example

{
  "firstName" : "",
  "lastName" : "deskagent",
  "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
  "id" : "5000000012902",
  "email" : "deskagent@zylker.com"
}


Add account followers

This API adds one or more users to the followers list of an account

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/accounts/{account_id}/addFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/addFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Remove account followers

This API removes one or more users from the followers list of an account

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/accounts/{account_id}/removeFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/accounts/4000000190069/removeFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Get account followers

This API fetches the list of users following an account.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the followers must be fetched

limit

integer

optional,
range : 1-100

Number of followers to list

GET api/v1/accounts/{account_id}/followers

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/accounts/4000000190069/followers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "id" : "5000000012903",
    "email" : "agent@zylker.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : "deskagent@zylker.com"
  } ]
}

Contact Followers

Contact followers are users who follow a contact to track the tickets raised by the contact and the support provided.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

email

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

Example

{
  "firstName" : "",
  "lastName" : "deskagent",
  "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
  "id" : "5000000012902",
  "email" : "deskagent@zylker.com"
}


Add contact followers

This API adds one or more users to the followers list of a contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/contacts/{contact_id}/addFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000190069/addFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Remove contact followers

This API removes one or more users from the followers list of a contact.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/contacts/{contact_id}/removeFollowers

OAuth Scope

Desk.contacts.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/contacts/4000000190069/removeFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Get contact followers

This API fetches the list of users following a contact.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the followers must be fetched

limit

integer

optional,
range : 1-100

Number of followers to list

GET api/v1/contacts/{contact_id}/followers

OAuth Scope

Desk.contacts.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/contacts/4000000190069/followers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "id" : "5000000012903",
    "email" : "agent@zylker.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : "deskagent@zylker.com"
  } ]
}

Ticket Followers

Ticket followers are users who follow a ticket to track the progress made in resolving it.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the user

firstName

string

Name of the user

lastName

string

Name of the user

email

string

Email ID of the user

photoURL

string

URL to access the photo of the user You need ZohoContacts.userphoto.READ OAuth Scope to access this API.

following

string

Key that returns the module being followed. Values allowed are
tickets,

contacts,
or
accounts

Example

{
  "firstName" : "",
  "lastName" : "deskagent",
  "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
  "following" : "ticket",
  "id" : "5000000012902",
  "email" : "deskagent@zylker.com"
}


Add ticket followers

This API adds one or more users to the followers list of a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/tickets/{ticket_id}/addFollowers

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000190069/addFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Remove ticket followers

This API removes one or more users from the followers list of a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
followerIds

list

required

the list of ids to be added as follower

POST api/v1/tickets/{ticket_id}/removeFollowers

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000190069/removeFollowers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "followerIds" : [ 5000000013292 ]
}'

Response Example

204

Get ticket followers

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

GET api/v1/tickets/{ticket_id}/followers

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000190069/followers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "firstName" : "",
    "lastName" : "agent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012903/photo",
    "following" : "ticket",
    "id" : "5000000012903",
    "email" : "agent@zylker.com"
  }, {
    "firstName" : "",
    "lastName" : "deskagent",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "following" : "contact",
    "id" : "5000000012902",
    "email" : "deskagent@zylker.com"
  } ]
}

Tasks Attachments

Task attachments are files you attach to a task to aid quick resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "creator" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
    "id" : "1892000000047001",
    "email" : "jade@zylker.com"
  },
  "size" : "2345",
  "creatorId" : "1892000000047001",
  "name" : "taskfile.txt",
  "createdTime" : "2013-11-06T10:25:03.000Z",
  "isPublic" : false,
  "id" : "1892000000047042",
  "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
}


List Task attachments

This API lists the files attached to a task.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

Index number, starting from which the attachments must be fetched

limit

integer

optional,
range : 1-100

Number of attachments to fetch

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/tasks/{task_id}/attachments

OAuth Scope

Desk.activities.READ , Desk.activities.tasks.READ , Desk.tasks.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments?include=creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> List&lt;Attachment&gt; response = attachment.getTaskAttachments( taskId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "issue.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "program.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "errorfixed.txt",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "error_page.pdf",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content"
  } ]
}

Create Task attachment

This API attaches a file to a task.

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

File to attach to the task

POST /api/v1/tasks/{task_id}/attachments

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.createTaskAttachment( file, taskId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "task_history.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001/content"
}

Delete Task attachment

This API removes an attachment from a task.

Credit: 1 credit/call

DELETE /api/v1/tasks/{task_id}/attachments/{attachment_id}

OAuth Scope

Desk.activities.UPDATE , Desk.activities.tasks.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL
  • Java

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> boolean response = attachment.deleteTaskAttachment( attachmentId, taskId );

Response Example

200

Product Attachments

Product attachments are the files you attach to a product to aid quick resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

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.

creatorId

long

ID of user who attached the file

createdTime

timestamp

Time of attaching the file

name

string

Name of the attachment

isPublic

boolean

Key that returns if the attachment is public or not

size

long

Size of the attachment

Example

{
  "creator" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
    "id" : "1892000000047001",
    "email" : "jade@zylker.com"
  },
  "size" : "2345",
  "creatorId" : "1892000000047001",
  "name" : "product.txt",
  "createdTime" : "2013-11-06T10:25:03.000Z",
  "isPublic" : false,
  "id" : "1892000000047042",
  "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000047042/content"
}


List all attachments

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

Query Params

Param Name
Data Type
Description
sortBy

string

optional,
max chars : 100

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

optional

from Index

limit

integer

optional,
range : 1-100

the number of attachments to be displayed

include
see documentation

string

optional,
max chars : 100

Secondary information related to the attachments. Value allowed is creator, which returns the details of users who added the attachments.

GET /api/v1/products/{product_id}/attachments

OAuth Scope

Desk.products.READ , Desk.settings.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/products/1892000001004024/attachments?include=creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> List&lt;Attachment&gt; response = attachment.getProductAttachments( productId, from, limit, sortBy, isAscending, include );

Response Example

{
  "data" : [ {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "ticket.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : false,
    "id" : "1892000000047041",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000047041/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "bsnl-feb14.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : false,
    "id" : "1892000000089041",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000000089041/content"
  }, {
    "size" : "97951",
    "creatorId" : "1892000000042002",
    "name" : "history.pdf",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001052021/content"
  }, {
    "creator" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000047001/photo?orgId=298902",
      "id" : "1892000000047001",
      "email" : "jade@zylker.com"
    },
    "size" : "97951",
    "creatorId" : "1892000000047001",
    "name" : "fixes.txt",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025",
    "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001052025/content"
  } ]
}

Create an attachment

This API attaches a file to a product.

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

attachment to be added

POST /api/v1/products/{product_id}/attachments

OAuth Scope

Desk.products.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL
  • Java

$ curl -X POST https://desk.zoho.com/api/v1/products/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> Attachment response = attachment.createProductAttachment( file, productId );

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042002",
  "name" : "tools.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001",
  "href" : "https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001010001/content"
}

Delete an attachment

This API deletes an attachment from a product.

Credit: 1 credit/call

DELETE /api/v1/products/{product_id}/attachments/{attachment_id}

OAuth Scope

Desk.products.UPDATE , Desk.settings.UPDATE

Request Example

  • CURL
  • Java

$ curl -X DELETE https://desk.zoho.com/api/v1/products/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

AttachmentAPI attachment = ZDesk.getAttachmentAPIInstance(mailId); <br/> boolean response = attachment.deleteProductAttachment( productId, attachmentId );

Response Example

204

Activities

Activity refers to secondary activities that your customer support agents perform. In Zoho Desk, activities are of three types: tasks, calls, and events. It is not mandatory for activities to be related only to ticket resolution.

Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "reminder" : [ {
    "alertType" : [ "EMAIL" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T10:32:11.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T16:32:11.000Z"
  }, {
    "relativeReminderInMin" : "10",
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "RELATIVE"
  } ],
  "contactId" : "3000000008749",
  "customFields" : { },
  "subject" : "New Event",
  "completedTime" : "2016-07-26T17:32:11.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "Normal",
  "duration" : "30",
  "createdTime" : "2016-07-26T16:32:11.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "startTime" : "2016-07-26T17:02:11.000Z",
  "id" : "3000000018001",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "completed"
}


List ticket activities

This API lists a particular number of activities associated with a ticket, based on the limit specified.

Mock API

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the activities must be listed

isCompleted

boolean

optional

Key that denotes if the activity was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam activities or not

limit

integer

optional,
range : 1-100

Number of activities to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: activityTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams,projects,integInfo.

GET /api/v1/tickets/{ticket_id}/activities

OAuth Scope

Desk.activities.calls.READ , Desk.activities.events.READ , Desk.activities.READ , Desk.activities.tasks.READ , Desk.calls.READ , Desk.tasks.READ , Desk.events.READ

Request Example

  • CURL
  • Java

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/activities?include=tickets,contacts,assignee,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

ActivityAPI activity = ZDesk.getActivityAPIInstance(mailId); <br/> GetTicketActivitiesFilter filter = new GetTicketActivitiesFilter.Builder().setIsCompleted(isCompleted).build(); <br/> List&lt;Activity&gt; response = activity.getTicketActivities( ticketId, from, limit, sortBy, isAscending, include, filter );

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "35",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Stall in Dubai Airport",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e484b8a02355a7e402",
    "createdTime" : "2019-04-12T05:21:21.000Z",
    "startTime" : "2019-12-25T16:52:11.000Z",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "35",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000083048",
    "isSpam" : false,
    "category" : "Demo",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "direction" : "inbound",
    "status" : "Not Started"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : "3000000008763",
      "id" : "5000000016294",
      "team" : {
        "name" : "Responsive Team",
        "id" : "3000000008763",
        "logoUrl" : "https://desk.zoho.com/api/v1/teams/3000000008763/logo?orgId=11278831"
      },
      "assignee" : {
        "photoURL" : null,
        "firstName" : "Steve",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Gadget Replacement",
    "completedTime" : "2019-04-17T07:12:09.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : {
      "name" : "Responsive Team",
      "id" : "3000000008763",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3000000008763/logo?orgId=11278831"
    },
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "teamId" : "3000000008763",
    "createdTime" : "2019-04-10T10:30:55.000Z",
    "startTime" : "2019-04-11T06:30:00.000Z",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "35",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000081089",
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "direction" : "outbound",
    "status" : "Completed"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "Steve",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Rest OS Version",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : "2019-04-24T06:30:00.000Z",
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : false,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Tasks/dv/9d4883f2d94d59e40af0073cf7981c2f",
    "createdTime" : "2019-04-10T10:07:26.000Z",
    "startTime" : "2019-04-24T06:30:00.000Z",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "id" : "5000000081036",
    "isSpam" : false,
    "category" : null,
    "activityType" : "Tasks",
    "ticketId" : "5000000016294",
    "direction" : "inbound",
    "status" : "Not Started"
  } ]
}

Delete spam activities

This API deletes all spam activities.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department to which the activities belong

POST /api/v1/activities/emptySpam

OAuth Scope

Desk.activities.calls.DELETE , Desk.activities.events.DELETE , Desk.activities.DELETE , Desk.activities.tasks.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/activities/emptySpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "4000000025121"
}'

Response Example

202

Calls

Calls refer to the support-related calls your customers make to your help desk and vice versa. It is mandatory for each call to be mapped to a contact.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the call

customFields 

deprecated

list

User-defined fields related to the call

cf

list

User-defined fields related to the call

departmentId
see documentation

long

ID of the department associated with the call and ticket

subject

string

Subject of the call

startTime

timestamp

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

Direction of the call: inbound or outbound

duration

integer

Duration of the call in seconds

status

string

Completion status of the call

ownerId

long

ID of the user to whom the call is assigned

priority

string

Priority of the call

description

string

Description of the call

createdTime

timestamp

Time when the call entry was added

modifiedTime

timestamp

Time when details of the call entry were modified

creatorId

string

ID of user who created the call

ticketId
see documentation

long

ID of the ticket associated with the call

contactId

long

ID of the contact associated with the call

ticket

Ticket

Details of the ticket associated with the call

Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "cf" : { },
  "reminder" : [ {
    "alertType" : [ "EMAIL" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T10:32:11.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T16:32:11.000Z"
  }, {
    "relativeReminderInMin" : "10",
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "RELATIVE"
  } ],
  "contactId" : "3000000008749",
  "subject" : "New Call",
  "completedTime" : "2016-07-26T17:32:11.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : "3000000015683",
  "priority" : "Normal",
  "duration" : "30",
  "createdTime" : "2016-07-25T17:32:11.000Z",
  "startTime" : "2016-07-25T16:52:11.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000018001",
  "isSpam" : false,
  "ticketId" : "3000000008753",
  "status" : "completed",
  "direction" : "inbound"
}


Get call

This API fetches the details of a call.

Mock API

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the call. Values allowed are: contacts, assignee,tickets,teams,livecalls,creator.

GET api/v1/calls/{call_id}

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , Desk.calls.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/calls/5000000081089?include=tickets,contacts,assignee,teams,creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2019-04-30T10:42:41.000Z",
  "subject" : "Call check scheduled",
  "completedTime" : "2019-04-17T07:12:09.000Z",
  "departmentId" : "5000000012710",
  "creatorId" : "5000000015911",
  "description" : null,
  "ownerId" : "5000000015911",
  "livecall" : {
    "recordings" : [ {
      "duration" : "84",
      "url" : "https://api.twilio.com/2010-04-01/Accounts/ACc3617ac782db73fcad51991c141243d6/Recordings/RE5ec62dec6cc69a9459e6ff8a096a7f31b"
    }, {
      "duration" : "675",
      "url" : "https://api.twilio.com/2010-04-01/Accounts/ACc3617ac782db73fcad51991c141243d6/Recordings/RE5ec62dec6cc69a9459e6ff8a096a7f23b"
    } ],
    "voiceMailDuration" : null,
    "id" : "6000000026017",
    "voiceMailUrl" : null
  },
  "duration" : "7380",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false
  },
  "createdTime" : "2019-04-10T10:30:55.000Z",
  "startTime" : "2019-04-11T06:30:00.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000081089",
  "direction" : "outbound",
  "creator" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "emailId" : "zylker@zylker.com",
    "id" : "5000000015911"
  },
  "cf" : { },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : "3691000006805001",
    "id" : "5000000016294",
    "team" : {
      "name" : "Testing Team",
      "id" : "3691000006805001",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805001/logo?orgId=11278831"
    },
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open"
  },
  "reminder" : [ {
    "alertType" : [ "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-24T06:30:00.000Z"
  }, {
    "alertType" : [ "SMS", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-23T06:30:00.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2019-04-22T06:30:00.000Z"
  } ],
  "contactId" : "5000000016252",
  "team" : {
    "name" : "Testing Team",
    "id" : "3691000006805001",
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805001/logo?orgId=11278831"
  },
  "priority" : "High",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "ticketId" : "5000000016294",
  "status" : "Completed"
}

List calls

This API fetches a particular number of calls, based on the limit specified.

Mock API

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the call. Values allowed are: contacts, assignee,tickets,teams.

from

integer

optional

Index number, starting from which the calls must be fetched

limit

integer

optional,
range : 1-100

Number of calls to fetch

departmentId
see documentation

long

optional

ID of the department from which the calls must be fetched

departmentIds
see documentation

long

optional

Departments from which the calls need to be queried

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

startTime

string

optional,
max chars : 100

Start time for completing the call. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

isCompleted

boolean

optional

Key that denotes whether the call is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the calls by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET api/v1/calls

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , Desk.calls.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/calls?include=tickets,contacts,assignee,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : null,
    "contactId" : null,
    "subject" : "hRl",
    "completedTime" : "2019-04-02T06:36:43.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e48740f9abf01f71bf",
    "contact" : null,
    "createdTime" : "2019-04-02T06:36:43.000Z",
    "startTime" : "2019-03-24T11:40:01.000Z",
    "id" : "5000000049385",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Canceled",
    "direction" : "inbound"
  }, {
    "ticket" : null,
    "contactId" : null,
    "subject" : "Irt",
    "completedTime" : "2019-04-02T06:37:06.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4603451fcf41c54b2",
    "contact" : null,
    "createdTime" : "2019-04-02T06:37:06.000Z",
    "startTime" : "2019-03-24T11:40:24.000Z",
    "id" : "5000000053840",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Canceled",
    "direction" : "inbound"
  }, {
    "ticket" : null,
    "contactId" : null,
    "subject" : "SG0",
    "completedTime" : "2019-04-02T06:36:28.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : {
      "name" : "Testing Team",
      "id" : "3691000006805001",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805001/logo?orgId=11278831"
    },
    "ownerId" : "5000000015911",
    "priority" : "Normal",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e46c76cc4bfd688f1b",
    "contact" : null,
    "createdTime" : "2019-04-02T06:36:28.000Z",
    "startTime" : "2019-04-01T11:39:44.000Z",
    "id" : "5000000047098",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : null,
    "activityType" : "Calls",
    "ticketId" : null,
    "status" : "Completed",
    "direction" : "inbound"
  } ]
}

Create call

This API adds a call entry to your help desk portal.

Mock API

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the call

cf

list

optional

User-defined fields related to the call

departmentId
see documentation

long

required

ID of the department associated with the call and ticket

subject

string

required,
max chars : 300

Subject of the call

startTime

timestamp

required

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

required,
max chars : 100

Direction of the call: inbound or outbound

duration

integer

required

Duration of the call in seconds

status

string

required,
max chars : 120

Completion status of the call

ownerId

long

optional

ID of the user to whom the call is assigned

priority

string

optional,
max chars : 120

Priority of the call

description

string

optional,
max chars : 65535

Description of the call

ticketId
see documentation

long

optional

ID of the ticket associated with the call

contactId

long

required

ID of the contact associated with the call

reminder

JSONArray

optional

Details of the reminder associated with the call

teamId

long

optional

ID of the team to which the call is assigned

recordingUrl

string

optional,
max chars : 2500

Recording or voice mail URL

POST api/v1/calls

OAuth Scope

Desk.activities.calls.CREATE , Desk.activities.CREATE , Desk.calls.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "duration" : "300",
  "reminder" : [ {
    "alertType" : [ "EMAIL", "SMS", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2018-12-25T04:52:13.000Z"
  } ],
  "contactId" : "1892000000088017",
  "subject" : "New Testing Call",
  "departmentId" : "3000000007043",
  "startTime" : "2016-07-25T16:52:11.000Z",
  "priority" : "High",
  "ticketId" : "3000000008753",
  "direction" : "inbound",
  "status" : "In Progress"
}'

Response Example

{
  "cf" : { },
  "contactId" : "1892000000088017",
  "subject" : "New Testing Call",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "duration" : "300",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "startTime" : "2016-07-25T16:52:11.000Z",
  "id" : "3000000054002",
  "ticketId" : "3000000008753",
  "direction" : "inbound",
  "status" : "In Progress"
}

Update call

This API updates the details of a call.

Mock API

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the call

cf

list

optional

User-defined fields related to the call

departmentId
see documentation

long

optional

ID of the department associated with the call and ticket

subject

string

optional,
max chars : 300

Subject of the call

startTime

timestamp

optional

Time when the call started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

direction

string

optional,
max chars : 100

Direction of the call: inbound or outbound

duration

integer

optional

Duration of the call in seconds

status

string

optional,
max chars : 120

Completion status of the call

ownerId

long

optional

ID of the user to whom the call is assigned

priority

string

optional,
max chars : 120

Priority of the call

description

string

optional,
max chars : 65535

Description of the call

ticketId
see documentation

long

optional

ID of the ticket associated with the call

contactId

long

optional

ID of the contact associated with the call

reminder

JSONArray

optional

Details of the reminder associated with the call

teamId

long

optional

ID of the team to which the call is assigned

recordingUrl

string

optional,
max chars : 2500

Recording or voice mail URL

PATCH api/v1/calls/{call_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , Desk.calls.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/calls/3000000054002
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactId" : "30000000088017",
  "description" : "Call completed with a callback request",
  "status" : "completed"
}'

Response Example

{
  "modifiedTime" : "2016-07-14T08:29:26.000Z",
  "cf" : { },
  "contactId" : "30000000088017",
  "subject" : "New Testing Call",
  "completedTime" : "2016-07-14T08:29:26.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : "Call completed with a callback request",
  "ownerId" : null,
  "priority" : "High",
  "duration" : "120",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "3000000054002",
  "isSpam" : false,
  "ticketId" : "3000000008753",
  "direction" : "inbound",
  "status" : "completed"
}

List calls by ticket

This API lists a particular number of calls associated with a ticket, based on the limit specified.

Mock API

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the calls must be listed

isCompleted

boolean

optional

Key that denotes if the call was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam calls or not

limit

integer

optional,
range : 1-100

Number of calls to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams.

GET /api/v1/tickets/{ticket_id}/calls

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , Desk.tickets.READ , Desk.calls.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/calls?include=tickets,contacts,assignee,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "subject" : "Call check scheduled",
    "completedTime" : "2019-04-17T07:12:09.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-10T10:30:55.000Z",
    "startTime" : "2019-04-11T06:30:00.000Z",
    "id" : "5000000081089",
    "direction" : "outbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013468",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4c0ddb2a7dd8a14ee",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "status" : "Completed"
  }, {
    "subject" : "ddddd",
    "completedTime" : "2019-04-17T07:11:43.000Z",
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4437f38846d520c51",
    "isCommented" : false,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false,
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-05T11:15:15.000Z",
    "startTime" : "2019-04-24T06:30:00.000Z",
    "id" : "5000000069105",
    "direction" : "outbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : "3691000006805001",
      "id" : "5000000016294",
      "team" : {
        "name" : "Testing Team",
        "id" : "3691000006805001",
        "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805001/logo?orgId=11278831"
      },
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : {
      "name" : "Testing Team",
      "id" : "3691000006805001",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805001/logo?orgId=11278831"
    },
    "priority" : "High",
    "layoutId" : "5000000013468",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Calls/dv/9d4883f2d94d59e4437f38846d520c51",
    "teamId" : "3691000006805001",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Call",
    "activityType" : "Calls",
    "ticketId" : "5000000016294",
    "status" : "Completed"
  } ]
}

Delete calls

This API moves call entries to the Recycle Bin of your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
entityIds

list

required

IDs of the activities to delete

POST /api/v1/calls/moveToTrash

OAuth Scope

Desk.activities.calls.DELETE , Desk.activities.DELETE , Desk.calls.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "entityIds" : [ "3000000053002" ]
}'

Response Example

204

Delete spam calls

This API deletes the given spam calls

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
callIds

list

required

IDs of the spam calls

POST /api/v1/calls/deleteSpam

OAuth Scope

Desk.activities.calls.DELETE , Desk.activities.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/deleteSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "callIds" : [ "1892000000007107", "1892000000001208" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000007107",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000001208",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422",
      "errorJson" : { }
    }
  } ]
}

Clear live call mapping from an activity

This API clears the live call mapping from an activity

Credit: 1 credit/call

POST /api/v1/calls/{call_id}/clearLiveCall

OAuth Scope

Desk.calls.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/{call_id}/clearLiveCall
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Update many calls

This API updates multiple calls at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/calls/updateMany

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , Desk.calls.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "mobile",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "8508569875"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Empty spam calls

This API deletes all spam calls.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department to which the activities belong

POST /api/v1/calls/emptySpam

OAuth Scope

Desk.activities.calls.DELETE , Desk.activities.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/emptySpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "4000000025121"
}'

Response Example

202

Calls Comments

Call comments refer to comments recorded on calls assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create a call comment

This API adds a comment to a call.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/calls/{call_id}/comments

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/calls/4000000530001/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First Call comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Call comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a call comment

This API updates an existing call comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "Edit Call comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Call comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a call comment

This API deletes an existing call comment.

Credit: 1 credit/call

DELETE api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get a call comment

This API fetches a call comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/calls/{call_id}/comments/{comment_id}

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/calls/4000000530001/comments/4000000530005
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Call Comment......",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all call comments

This API lists a particular number of comments recorded on a call, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/calls/{call_id}/comments

OAuth Scope

Desk.activities.calls.READ , Desk.activities.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/calls/4000000530001/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Second Call Comment......",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/calls/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Call comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Events

Events refer to pre-planned, and most of the time, directly customer-facing activities aimed at ticket resolution. The different events supported in Zoho Desk are: meetings and demos.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the event

customFields 

deprecated

list

User-defined fields related to the event

cf

list

User-defined fields related to the event

departmentId
see documentation

long

ID of the department associated with the event and ticket

subject

string

Subject of the event

startTime

timestamp

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

Duration of the event in seconds

status

string

Completion status of the event

ownerId

long

ID of the user to whom the event is assigned

priority

string

Priority of the event

description

string

Description of the event

createdTime

timestamp

Time when the event entry was added

modifiedTime

timestamp

Time when details of the event entry were modified

creatorId

string

ID of the user who created the event

category

string

Category of the event

ticketId
see documentation

long

ID of the ticket associated with the event

contactId

long

ID of the contact associated with the event

ticket

Ticket

Details of the ticket associated with the event

Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "cf" : { },
  "reminder" : [ {
    "alertType" : [ "EMAIL" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T10:32:11.000Z"
  }, {
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "ABSOLUTE",
    "reminderTime" : "2016-07-26T16:32:11.000Z"
  }, {
    "relativeReminderInMin" : "10",
    "alertType" : [ "EMAIL", "POPUP" ],
    "reminderType" : "RELATIVE"
  } ],
  "contactId" : "3000000008749",
  "subject" : "Conference with Tech leads",
  "completedTime" : "2016-07-26T17:32:11.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "Normal",
  "duration" : "30",
  "createdTime" : "2016-07-26T16:32:11.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "startTime" : "2016-07-26T17:02:11.000Z",
  "id" : "3000000018001",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "completed"
}


Get event

This API fetches the details of an event.

Mock API

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams,integInfo,creator.

GET api/v1/events/{event_id}

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , Desk.events.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/events/5000000065115?include=tickets?include=assignee,tickets,contacts,teams,creator
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2019-04-30T14:22:13.000Z",
  "subject" : "Zoholics 2019",
  "completedTime" : null,
  "departmentId" : "5000000012710",
  "creatorId" : "5000000015911",
  "description" : null,
  "ownerId" : "5000000015911",
  "secId" : "9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
  "duration" : "10980",
  "contact" : {
    "firstName" : null,
    "lastName" : "Lawrence",
    "phone" : "1 888 900 9646",
    "mobile" : null,
    "id" : "5000000016252",
    "isSpam" : false,
    "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
  },
  "createdTime" : "2019-04-04T06:48:36.000Z",
  "startTime" : "2019-04-18T06:30:00.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "id" : "5000000065115",
  "creator" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "emailId" : "zylker@zylker.com",
    "id" : "5000000015911"
  },
  "cf" : { },
  "ticket" : {
    "ticketNumber" : "101",
    "phone" : "1 888 900 9646",
    "subject" : "Here's your first ticket.",
    "dueDate" : "2019-03-29T09:51:26.000Z",
    "teamId" : "3691000006805021",
    "id" : "5000000016294",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "assignee" : {
      "photoURL" : null,
      "firstName" : "George",
      "lastName" : "McKinson",
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "status" : "Open",
    "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
  },
  "reminder" : null,
  "contactId" : "5000000016252",
  "team" : {
    "name" : "Desk Team",
    "id" : "3691000006805021",
    "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
  },
  "priority" : "High",
  "layoutId" : "5000000013470",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
  "teamId" : "3691000006805021",
  "assignee" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "5000000016294",
  "status" : "Not Started"
}

List events

This API lists a particular number of events, based on the limit specified.

Mock API

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the event. Values allowed are: contacts, assignee,tickets,teams,integInfo.

from

integer

optional

Index number, starting from which the events must be fetched

limit

integer

optional,
range : 1-100

Number of events to list

startTime

string

optional,
max chars : 100

Start time for completing the event. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today.You can pass multiple values by separating them with commas.

departmentId
see documentation

long

optional

ID of the department from which the events must be fetched

departmentIds
see documentation

long

optional

Departments from which the events need to be queried

assignee

long

optional

Key that filters tickets by assignee. Values allowed are any valid assignee ID or multiple assignee IDs separated by commas.

viewId
see documentation

long

optional

ID of the view to apply while fetching the resources

isCompleted

boolean

optional

Key that denotes whether the event is completed or not

sortBy

string

optional,
max chars : 100

Key that sorts the events by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET api/v1/events

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , Desk.events.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/events?include=assignee,tickets,contacts,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Partner's conference'",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : null,
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false
    },
    "createdTime" : "2019-04-04T06:48:36.000Z",
    "startTime" : "2019-04-18T06:30:00.000Z",
    "id" : "5000000065115",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started",
    "direction" : "inbound"
  }, {
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : "3691000006805021",
      "id" : "5000000016294",
      "team" : {
        "name" : "Desk Team",
        "id" : "3691000006805021",
        "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
      },
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "isSpam" : false,
      "status" : "Open"
    },
    "contactId" : "5000000016252",
    "subject" : "Developers meet",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "ownerId" : "5000000015911",
    "priority" : "High",
    "isCommented" : true,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e41c8e46db1a43ba49",
    "teamId" : "3691000006805021",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "isSpam" : false
    },
    "createdTime" : "2019-04-16T12:02:27.000Z",
    "startTime" : "2019-04-25T06:30:00.000Z",
    "id" : "5000000084070",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started",
    "direction" : "inbound"
  } ]
}

Create event

This API adds an event entry to your help desk portal.

Mock API

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the event

cf

list

optional

User-defined fields related to the event

departmentId
see documentation

long

required

ID of the department associated with the event and ticket

subject

string

required,
max chars : 300

Subject of the event

startTime

timestamp

required

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

required

Duration of the event in seconds

status

string

optional,
max chars : 120

Completion status of the event

ownerId

long

optional

ID of the user to whom the event is assigned

priority

string

optional,
max chars : 120

Priority of the event

description

string

optional,
max chars : 65535

Description of the event

category

string

optional,
max chars : 120

Category of the event

ticketId
see documentation

long

optional

ID of the ticket associated with the event

contactId

long

required

ID of the contact associated with the event

reminder

JSONArray

optional

Details of the reminder associated with the event

teamId

long

optional

ID of the team to which the event is assigned

POST api/v1/events

OAuth Scope

Desk.activities.events.CREATE , Desk.activities.CREATE , Desk.events.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "duration" : "40",
  "contactId" : "3000000001234",
  "subject" : "Dubai startup meet",
  "departmentId" : "3000000007043",
  "startTime" : "2016-07-14T08:27:26.000Z",
  "priority" : "High",
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}'

Response Example

{
  "cf" : { },
  "contactId" : "3000000001234",
  "subject" : "New Testing Event",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "duration" : "40",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "startTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Update event

This API updates the details of an event.

Mock API

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields 
deprecated

list

optional

User-defined fields related to the event

cf

list

optional

User-defined fields related to the event

departmentId
see documentation

long

optional

ID of the department associated with the event and ticket

subject

string

optional,
max chars : 300

Subject of the event

startTime

timestamp

optional

Time when the event started. The value of this key must be recorded in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

duration

integer

optional

Duration of the event in seconds

status

string

optional,
max chars : 120

Completion status of the event

ownerId

long

optional

ID of the user to whom the event is assigned

priority

string

optional,
max chars : 120

Priority of the event

description

string

optional,
max chars : 65535

Description of the event

category

string

optional,
max chars : 120

Category of the event

ticketId
see documentation

long

optional

ID of the ticket associated with the event

contactId

long

optional

ID of the contact associated with the event

reminder

JSONArray

optional

Details of the reminder associated with the event

teamId

long

optional

ID of the team to which the event is assigned

PATCH api/v1/events/{event_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , Desk.events.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/events/3000000054002
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactId" : "30000000088017",
  "description" : "Event completed with a callback request",
  "status" : "completed"
}'

Response Example

{
  "modifiedTime" : "2016-07-14T08:47:26.000Z",
  "cf" : { },
  "contactId" : "30000000088017",
  "subject" : "Event camp at Finland",
  "completedTime" : "2016-07-14T08:47:26.000Z",
  "departmentId" : "3000000007043",
  "creatorId" : "3000000008692",
  "description" : "Event completed with a callback request",
  "ownerId" : null,
  "priority" : "High",
  "duration" : "20",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/51123033fe97b2f886f750280ded9c40",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "modifiedBy" : {
    "firstName" : "George",
    "lastName" : "McKinson",
    "photoURL" : null,
    "id" : "5000000015911"
  },
  "startTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "isSpam" : false,
  "category" : "Meeting",
  "ticketId" : "3000000008753",
  "status" : "completed"
}

List events by ticket

This API lists a particular number of events associated with a ticket, based on the limit specified.

Mock API

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the events must be listed

isCompleted

boolean

optional

Key that denotes if the event was completed or not

isSpam

boolean

optional

Key that denotes whether to fetch spam events or not

limit

integer

optional,
range : 1-100

Number of events to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: startTime or createdTime.The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

string

optional,
max chars : 100

Allowed values are : contacts, assignee,tickets,teams,integInfo.

GET /api/v1/tickets/{ticket_id}/events

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , Desk.tickets.READ , Desk.events.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/5000000016294/events?include=assignee,tickets,contacts,teams
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "subject" : "Zoholics at Australia",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-04T06:48:36.000Z",
    "startTime" : "2019-04-18T06:30:00.000Z",
    "id" : "5000000065115",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : "3691000006805021",
      "id" : "5000000016294",
      "team" : {
        "name" : "Desk Team",
        "id" : "3691000006805021",
        "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
      },
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : {
      "name" : "Desk Team",
      "id" : "3691000006805021",
      "logoUrl" : "https://desk.zoho.com/api/v1/teams/3691000006805021/logo?orgId=11278831"
    },
    "priority" : "High",
    "layoutId" : "5000000013470",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e4McKinsonf5d2f01bbb8bd4",
    "teamId" : "3691000006805021",
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started"
  }, {
    "subject" : "sadfsadf",
    "completedTime" : null,
    "departmentId" : "5000000012710",
    "dueDate" : null,
    "creatorId" : "5000000015911",
    "ownerId" : "5000000015911",
    "secId" : "9d4883f2d94d59e41c8e46db1a43ba49",
    "isCommented" : true,
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "mobile" : null,
      "id" : "5000000016252",
      "secId" : "9d4883f2d94d59e42b7cc45393ad8ff8"
    },
    "createdTime" : "2019-04-16T12:02:27.000Z",
    "startTime" : "2019-04-25T06:30:00.000Z",
    "id" : "5000000084070",
    "direction" : "inbound",
    "ticket" : {
      "ticketNumber" : "101",
      "phone" : "1 888 900 9646",
      "subject" : "Here's your first ticket.",
      "dueDate" : "2019-03-29T09:51:26.000Z",
      "teamId" : null,
      "id" : "5000000016294",
      "assignee" : {
        "photoURL" : null,
        "firstName" : "George",
        "lastName" : "McKinson",
        "id" : "5000000015911"
      },
      "status" : "Open",
      "secId" : "9d4883f2d94d59e415b08d3d4c697d42"
    },
    "contactId" : "5000000016252",
    "team" : null,
    "priority" : "High",
    "layoutId" : "5000000013470",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Events/dv/9d4883f2d94d59e41c8e46db1a43ba49",
    "teamId" : null,
    "assignee" : {
      "firstName" : "George",
      "lastName" : "McKinson",
      "photoURL" : null,
      "id" : "5000000015911"
    },
    "isSpam" : false,
    "category" : "Meeting",
    "activityType" : "Events",
    "ticketId" : "5000000016294",
    "status" : "Not Started"
  } ]
}

Delete events

This API moves event entries to the Recycle Bin of your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
entityIds

list

required

IDs of the activities to delete

POST /api/v1/events/moveToTrash

OAuth Scope

Desk.activities.events.DELETE , Desk.activities.DELETE , Desk.events.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "entityIds" : [ "3000000053002" ]
}'

Response Example

204

Delete spam events

This API deletes the given spam events

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
eventIds

list

required

IDs of the spam events

POST /api/v1/events/deleteSpam

OAuth Scope

Desk.activities.events.DELETE , Desk.activities.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events/deleteSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "eventIds" : [ "1892000000001297", "1892000000001358" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000001297",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000001358",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422",
      "errorJson" : { }
    }
  } ]
}

Update many events

This API updates multiple events at once.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the entities to update. The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

isCustomField

boolean

optional

Key that denotes if the field is a user-defined field or not

POST /api/v1/events/updateMany

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , Desk.events.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "mobile",
  "isCustomField" : false,
  "ids" : [ "1892000000093303", "1892000000085009", "1892000000050003" ],
  "fieldValue" : "8508569875"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1892000000093303",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1892000000085009",
    "errors" : null
  }, {
    "success" : false,
    "id" : "1892000000050003",
    "errors" : {
      "errorMessage" : "Either the field is invalid or the field may be restricted to update",
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Empty spam events

This API deletes all spam events.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
departmentId
see documentation

long

required

ID of the department to which the activities belong

POST /api/v1/events/emptySpam

OAuth Scope

Desk.activities.events.DELETE , Desk.activities.DELETE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events/emptySpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "4000000025121"
}'

Response Example

202

Events Comments

Event comments refer to comments recorded on events assigned to agents. We are introducing a new key called contentType in the responses to ticket comment APIs. This new key supports two values: html and plaintext. Both types of content will be delivered only in plain text in API responses and the contentType key only indicates the presence of html formatting in the original comment.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the comment

content

string

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

commenterId

long

ID of the user who made the comment

commentedTime

timestamp

Time of comment creation

modifiedTime

timestamp

Time of comment modification

commenter

object

Details of the user who made the comment.

contentType

string

Used to denote the content-type which maybe html or plainText. The default type is html.

Example

{
  "commentedTime" : "2014-11-28T10:25:13.000Z",
  "isPublic" : false,
  "id" : "1892000000366001",
  "contentType" : "html",
  "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
  "commenterId" : "1892000000042001",
  "mention" : [ {
    "firstName" : "",
    "lastName" : "pandees",
    "photoURL" : null,
    "offSet" : "7",
    "length" : "28",
    "id" : "31138000000573164",
    "type" : "AGENT",
    "email" : "jade15tywin@zylker.com",
    "zuid" : "55616589"
  }, {
    "offSet" : "39",
    "length" : "46",
    "name" : "new team",
    "id" : "31138000001254025",
    "type" : "TEAM"
  }, {
    "offSet" : "59",
    "departmentId" : "3113800000634345",
    "entityNumber" : "1342",
    "length" : "26",
    "name" : "",
    "id" : "3113800000143134",
    "type" : "TICKET"
  } ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "PortalUser",
    "type" : "END_USER",
    "email" : "jade12tywin@zylker.com"
  }
}


Create a event comment

This API adds a comment to a event.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

POST api/v1/events/{event_id}/comments

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/events/4000000530001/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contentType" : "html",
  "content" : "First Event comment."
}'

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.534Z",
  "id" : "4000000530003",
  "contentType" : "html",
  "content" : "First Event comment.",
  "commenterId" : "4000000008692",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Update a event comment

This API updates an existing event comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 32000

Content of the comment. To retrieve or set user mentions, use this code format: zsu[@user:{zuid}zsu.

contentType

string

optional,
max chars : 100

Used to denote the content-type which maybe html or plainText. The default type is html.

PATCH api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "content" : "Edit Event comment"
}'

Response Example

{
  "modifiedTime" : "2017-01-24T14:56:20.447Z",
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T14:54:33.000Z",
  "id" : "4000000530003",
  "contentType" : "plainText",
  "commenterId" : "4000000008692",
  "content" : "Edit Event comment",
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "LightAgent",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

Delete a event comment

This API deletes an existing event comment.

Credit: 1 credit/call

DELETE api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.UPDATE , Desk.activities.UPDATE , Desk.tasks.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get a event comment

This API fetches a event comment from the portal.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/events/{event_id}/comments/{comment_id}

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/events/4000000530001/comments/4000000530005?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : null,
  "attachments" : [ {
    "size" : "12734",
    "name" : "Attachment_edited.png",
    "id" : "4000000008994",
    "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
  } ],
  "commentedTime" : "2017-01-24T15:04:47.000Z",
  "id" : "4000000530005",
  "contentType" : "plainText",
  "content" : "Second Event Comment......",
  "commenterId" : "4000000008692",
  "mention" : [ ],
  "commenter" : {
    "firstName" : "Jade",
    "lastName" : "Tywin",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
    "name" : "Jade Tywin",
    "roleName" : "CEO",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  }
}

List all event comments

This API lists a particular number of comments recorded on a event, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number starting from which the comments must be fetched

limit

integer

required,
default : 50,
range : 1-100

No. of comments to fetch

sortBy

string

optional,
max chars : 100

Sort comments by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

include
see documentation

String

optional

Secondary information related to the comments. Value allowed is mentions, which returns the details of users mentioned in the comments.

GET api/v1/events/{event_id}/comments

OAuth Scope

Desk.activities.events.READ , Desk.activities.READ , Desk.tasks.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/events/4000000530001/comments?include=mentions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T15:04:47.000Z",
    "id" : "4000000530005",
    "contentType" : "plainText",
    "commenterId" : "4000000008692",
    "content" : "Sample zsu[@user:55616589]zsu and zsu[@team:31138000001254025_new team]zsu testing",
    "mention" : [ {
      "firstName" : "",
      "lastName" : "pandees",
      "photoURL" : null,
      "offSet" : "7",
      "length" : "28",
      "id" : "31138000000573164",
      "type" : "AGENT",
      "email" : "jade15tywin@zylker.com",
      "zuid" : "55616589"
    }, {
      "offSet" : "39",
      "length" : "46",
      "name" : "new team",
      "id" : "31138000001254025",
      "type" : "TEAM"
    } ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "LightAgent",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  }, {
    "modifiedTime" : "2017-01-24T14:56:20.000Z",
    "attachments" : [ {
      "size" : "12734",
      "name" : "Attachment_list.png",
      "id" : "4000000008994",
      "href" : "https://desk.zoho.com/api/v1/events/4000000528005/comments/4000000529001/attachments/4000000008994/content"
    } ],
    "commentedTime" : "2017-01-24T14:54:33.000Z",
    "id" : "4000000530003",
    "contentType" : "html",
    "commenterId" : "4000000008692",
    "content" : "Edit Event comment",
    "mention" : [ ],
    "commenter" : {
      "firstName" : "Jade",
      "lastName" : "Tywin",
      "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo",
      "name" : "Jade Tywin",
      "roleName" : "PortalUser",
      "type" : "END_USER",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Display Entity

Display Entity helps to open a Entity in Agent's Browser automatically.

Auto Display an Entity

This API is used to instruct an agent's browser to open and display a given entity automatically without any manual action required by the agent.

agentId: Id of the agent in whose browser the entity to be opened.

entityName: Name of the entity that needs to be opened.Values allowed are: tickets, contacts.

entityId: Id of the entity.

Credit: 1 credit/call

POST /api/v1/agents/{agentId}/{entityName}/{entityId}/display

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/1917000000040001/tickets/1917000007169506/display
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Modules

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.

ATTRIBUTES

Attribute Name
Data Type
Description
singularLabel

string

SingularLabel of the module

pluralLabel

string

PluralLabel of the module

description

string

Description of the module

departmentIds

list

IDs of departments associated with the Module

profileIds

list

IDs of profileIds associated with the Module

apiName

string

Unique readonly name of the module

nameField

string

Specifies the name of the primary field of the module. When creating a module, a unique primary field is assigned to that module.

isCustomModule

boolean

Specifies whether the module is a custom module

isDeptSpecific

boolean

Specifies whether the module is department-specific

hasRecycleBin

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.

id

Long

The unique id of the module

createdBy

long

Id of the User who created the module

createdTime

timestamp

Specifies the time of creation of the Module

modifiedBy

long

Id of the User who modified the module

modifiedTime

timestamp

Specifies the time at which changes were made to the module

modifier

object

Details of user who modified the module

Example

{
  "displayLabel" : "Doctors",
  "modifiedTime" : "2024-04-19T09:35:02.000Z",
  "apiName" : "cm_doctors",
  "modifier" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "nameField" : "name",
  "profileIds" : [ "1000000029530", "1000000029533" ],
  "description" : "Doctor informations",
  "departmentIds" : [ "1000000774623", "1000000025632" ],
  "pluralLabel" : "Doctors",
  "singularLabel" : "Doctor",
  "createdBy" : "1000000000375",
  "isCustomModule" : true,
  "createdTime" : "2024-04-19T09:04:17.000Z",
  "modifiedBy" : "1000000000375",
  "isDeptSpecific" : true,
  "id" : "1000003000001"
}


Create Custom Module

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

Attributes

Param Name
Data Type
Description
singularLabel

string

required,
max chars : 50

Singular Label of the module

pluralLabel

string

required,
max chars : 50

Plural Label of the module

description

string

optional,
max chars : 200

Description of the module

departmentIds

list

optional

IDs of departments associated with the module

profileIds

list

optional

IDs of profileIds associated with the module

isDeptSpecific

boolean

optional

Specifies whether the module is department-specific. If the key is not provided, it will create an organization-level module.

POST /api/v1/organizationModules

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/organizationModules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "description" : "Doctor informations",
  "profileIds" : [ 1000000029530 ],
  "isDeptSpecific" : true,
  "pluralLabel" : "Doctors",
  "departmentIds" : [ 1000000774623, 1000000025632 ],
  "singularLabel" : "Doctor"
}'

Response Example

{
  "displayLabel" : "Doctors",
  "modifiedTime" : "2024-04-19T09:35:02.000Z",
  "apiName" : "cm_doctors",
  "modifier" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "nameField" : "name",
  "profileIds" : [ "1000000029530" ],
  "description" : "Doctor informations",
  "departmentIds" : [ "1000000774623", "1000000025632" ],
  "pluralLabel" : "Doctors",
  "singularLabel" : "Doctor",
  "hasRecycleBin" : true,
  "createdBy" : "1000000000375",
  "isCustomModule" : true,
  "createdTime" : "2024-04-19T09:04:17.000Z",
  "modifiedBy" : "1000000000375",
  "isDeptSpecific" : true,
  "id" : "1000003000001"
}

Edit Custom Module

The API edits a Custom Module.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
singularLabel

string

required,
max chars : 50

Singular Label of the module

pluralLabel

string

required,
max chars : 50

Plural Label of the module

description

string

optional,
max chars : 200

Description of the module

departmentIds

list

required

IDs of departments associated with the module

profileIds

list

required

IDs of profileIds associated with the module

PUT /api/v1/organizationModules/{moduleId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/organizationModules/1000003000001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "description" : "Doctor informations",
  "profileIds" : [ 1000000029530, 1000000029533 ],
  "pluralLabel" : "Doctors",
  "departmentIds" : [ 1000000774623, 1000000025632 ],
  "singularLabel" : "Doctor"
}'

Response Example

{
  "displayLabel" : "Doctors",
  "modifiedTime" : "2024-04-19T09:35:02.000Z",
  "apiName" : "cm_doctors",
  "modifier" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "nameField" : "name",
  "profileIds" : [ "1000000029530", "1000000029533" ],
  "description" : "Doctor informations",
  "departmentIds" : [ "1000000774623", "1000000025632" ],
  "pluralLabel" : "Doctors",
  "singularLabel" : "Doctor",
  "hasRecycleBin" : true,
  "createdBy" : "1000000000375",
  "isCustomModule" : true,
  "createdTime" : "2024-04-19T09:04:17.000Z",
  "modifiedBy" : "1000000000375",
  "isDeptSpecific" : true,
  "id" : "1000003000001"
}

Get a Module

This API fetches a single Module

Credit: 1 credit/call

GET /api/v1/organizationModules/{moduleId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizationModules/1000003000001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "displayLabel" : "Doctors",
  "modifiedTime" : "2024-04-19T09:35:02.000Z",
  "apiName" : "cm_doctors",
  "modifier" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "nameField" : "name",
  "profileIds" : [ "1000000029530", "1000000029533" ],
  "description" : "Doctor informations",
  "departmentIds" : [ "1000000774623", "1000000025632" ],
  "pluralLabel" : "Doctors",
  "singularLabel" : "Doctor",
  "hasRecycleBin" : true,
  "createdBy" : "1000000000375",
  "isCustomModule" : true,
  "createdTime" : "2024-04-19T09:04:17.000Z",
  "modifiedBy" : "1000000000375",
  "isDeptSpecific" : true,
  "id" : "1000003000001"
}

Get All Modules

The API fetches all the modules.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
GET /api/v1/organizationModules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizationModules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "displayLabel" : "Accounts",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "accounts",
    "modifier" : null,
    "nameField" : "accountName",
    "description" : null,
    "pluralLabel" : "Accounts",
    "singularLabel" : "Account",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : false,
    "id" : "1000000000377"
  }, {
    "displayLabel" : "Contacts",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "contacts",
    "modifier" : null,
    "nameField" : "lastName",
    "description" : null,
    "pluralLabel" : "Contacts",
    "singularLabel" : "Contact",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : false,
    "id" : "1000000000379"
  }, {
    "displayLabel" : "Tasks",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "tasks",
    "modifier" : null,
    "nameField" : "subject",
    "description" : null,
    "pluralLabel" : "Tasks",
    "singularLabel" : "Task",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000383"
  }, {
    "displayLabel" : "Tickets",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "tickets",
    "modifier" : null,
    "nameField" : "subject",
    "description" : null,
    "pluralLabel" : "Tickets",
    "singularLabel" : "Ticket",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000423"
  }, {
    "displayLabel" : "Contracts",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "contracts",
    "modifier" : null,
    "nameField" : "contractName",
    "description" : null,
    "pluralLabel" : "Contracts",
    "singularLabel" : "Contract",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000427"
  }, {
    "displayLabel" : "Products",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "products",
    "modifier" : null,
    "nameField" : "productName",
    "description" : null,
    "pluralLabel" : "Products",
    "singularLabel" : "Product",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : false,
    "id" : "1000000000429"
  }, {
    "displayLabel" : "Time Entry",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "timeEntry",
    "modifier" : null,
    "nameField" : "requestChargeType",
    "description" : null,
    "pluralLabel" : "Time Entry",
    "singularLabel" : "Time Entry",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000431"
  }, {
    "displayLabel" : "Agents",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "agents",
    "modifier" : null,
    "nameField" : "lastName",
    "description" : null,
    "pluralLabel" : "Agents",
    "singularLabel" : "Agent",
    "hasRecycleBin" : false,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : false,
    "id" : "1000000000435"
  }, {
    "displayLabel" : "Events",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "events",
    "modifier" : null,
    "nameField" : "subject",
    "description" : null,
    "pluralLabel" : "Events",
    "singularLabel" : "Event",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000445"
  }, {
    "displayLabel" : "Calls",
    "modifiedTime" : "2000-01-01T00:00:00.000Z",
    "apiName" : "calls",
    "modifier" : null,
    "nameField" : "subject",
    "description" : null,
    "pluralLabel" : "Calls",
    "singularLabel" : "Call",
    "hasRecycleBin" : true,
    "createdBy" : null,
    "isCustomModule" : false,
    "createdTime" : "2000-01-01T00:00:00.000Z",
    "modifiedBy" : null,
    "isDeptSpecific" : true,
    "id" : "1000000000447"
  }, {
    "displayLabel" : "Doctors",
    "modifiedTime" : "2024-04-19T09:35:02.000Z",
    "apiName" : "cm_doctors",
    "modifier" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "nameField" : "name",
    "description" : "Doctor informations",
    "pluralLabel" : "Doctors",
    "singularLabel" : "Doctor",
    "hasRecycleBin" : true,
    "createdBy" : "1000000000375",
    "isCustomModule" : true,
    "createdTime" : "2024-04-19T09:04:17.000Z",
    "modifiedBy" : "1000000000375",
    "isDeptSpecific" : true,
    "id" : "1000003000001"
  } ]
}

Get modules accessible to current user profile

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

GET /api/v1/myAccessibleModules

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myAccessibleModules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modules" : [ {
    "displayLabel" : "Contracts",
    "apiKey" : "contracts",
    "isEnabled" : false,
    "nameField" : null,
    "id" : "1000000000485",
    "pluralLabel" : "Contracts",
    "singularLabel" : "Contract"
  }, {
    "displayLabel" : "Time Entry",
    "apiKey" : "timeEntry",
    "isEnabled" : false,
    "nameField" : null,
    "id" : "1000000000489",
    "pluralLabel" : "Time Entry",
    "singularLabel" : "Time Entry"
  }, {
    "displayLabel" : "Department",
    "apiKey" : "departments",
    "isEnabled" : false,
    "nameField" : null,
    "id" : "1000000000491",
    "pluralLabel" : "Departments",
    "singularLabel" : "Department"
  }, {
    "displayLabel" : "Agents",
    "apiKey" : "agents",
    "isEnabled" : false,
    "nameField" : null,
    "id" : "1000000000493",
    "pluralLabel" : "Agents",
    "singularLabel" : "Agent"
  }, {
    "displayLabel" : "Topics",
    "apiKey" : "category",
    "isEnabled" : false,
    "nameField" : null,
    "id" : "1000000000527",
    "pluralLabel" : "Topics",
    "singularLabel" : "Topic"
  }, {
    "displayLabel" : "Ticketss",
    "apiKey" : "tickets",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000481",
    "pluralLabel" : "Ticketss",
    "singularLabel" : "Ticket"
  }, {
    "displayLabel" : "Reports",
    "apiKey" : "reports",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000463",
    "pluralLabel" : "Reports",
    "singularLabel" : "Report"
  }, {
    "displayLabel" : "Dashboards",
    "apiKey" : "dashboards",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000465",
    "pluralLabel" : "Dashboards",
    "singularLabel" : "Dashboard"
  }, {
    "displayLabel" : "Knowledge Base",
    "apiKey" : "kbCategory",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000483",
    "pluralLabel" : "Articles",
    "singularLabel" : "Article"
  }, {
    "displayLabel" : "Contacts",
    "apiKey" : "contacts",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000461",
    "pluralLabel" : "Contacts",
    "singularLabel" : "Contact"
  }, {
    "displayLabel" : "Products",
    "apiKey" : "products",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000487",
    "pluralLabel" : "Products",
    "singularLabel" : "Product"
  }, {
    "displayLabel" : "Accounts",
    "apiKey" : "accounts",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000459",
    "pluralLabel" : "Accounts",
    "singularLabel" : "Account"
  }, {
    "displayLabel" : "Community",
    "apiKey" : "community",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000533",
    "pluralLabel" : "Community",
    "singularLabel" : "Community"
  }, {
    "displayLabel" : "Social",
    "apiKey" : "social",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000535",
    "pluralLabel" : "Social",
    "singularLabel" : "Social"
  }, {
    "displayLabel" : "Chat",
    "apiKey" : "chat",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000537",
    "pluralLabel" : "Chat",
    "singularLabel" : "Chat"
  }, {
    "displayLabel" : "Activities",
    "apiKey" : "activities",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000471",
    "pluralLabel" : "Activities",
    "singularLabel" : "Activity"
  }, {
    "displayLabel" : "Calls",
    "apiKey" : "calls",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000531",
    "pluralLabel" : "Calls",
    "singularLabel" : "Call"
  }, {
    "displayLabel" : "Tasks",
    "apiKey" : "tasks",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000469",
    "pluralLabel" : "Tasks",
    "singularLabel" : "Task"
  }, {
    "displayLabel" : "Events",
    "apiKey" : "events",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000529",
    "pluralLabel" : "Events",
    "singularLabel" : "Event"
  }, {
    "displayLabel" : "IM",
    "apiKey" : "im",
    "isEnabled" : true,
    "nameField" : null,
    "id" : "1000000000475",
    "pluralLabel" : "IM",
    "singularLabel" : "IM"
  } ]
}

Get modules

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

GET /api/v1/modules

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/modules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modules" : [ {
    "displayLabel" : "Contracts",
    "apiKey" : "contracts",
    "nameField" : null,
    "id" : "1000000000485",
    "pluralLabel" : "Contracts",
    "singularLabel" : "Contract"
  }, {
    "displayLabel" : "Time Entry",
    "apiKey" : "timeEntry",
    "nameField" : null,
    "id" : "1000000000489",
    "pluralLabel" : "Time Entry",
    "singularLabel" : "Time Entry"
  }, {
    "displayLabel" : "Department",
    "apiKey" : "departments",
    "nameField" : null,
    "id" : "1000000000491",
    "pluralLabel" : "Departments",
    "singularLabel" : "Department"
  }, {
    "displayLabel" : "Agents",
    "apiKey" : "agents",
    "nameField" : null,
    "id" : "1000000000493",
    "pluralLabel" : "Agents",
    "singularLabel" : "Agent"
  }, {
    "displayLabel" : "Topics",
    "apiKey" : "category",
    "nameField" : null,
    "id" : "1000000000527",
    "pluralLabel" : "Topics",
    "singularLabel" : "Topic"
  }, {
    "displayLabel" : "Ticketss",
    "apiKey" : "tickets",
    "nameField" : null,
    "id" : "1000000000481",
    "pluralLabel" : "Ticketss",
    "singularLabel" : "Ticket"
  }, {
    "displayLabel" : "Reports",
    "apiKey" : "reports",
    "nameField" : null,
    "id" : "1000000000463",
    "pluralLabel" : "Reports",
    "singularLabel" : "Report"
  }, {
    "displayLabel" : "Dashboards",
    "apiKey" : "dashboards",
    "nameField" : null,
    "id" : "1000000000465",
    "pluralLabel" : "Dashboards",
    "singularLabel" : "Dashboard"
  }, {
    "displayLabel" : "Knowledge Base",
    "apiKey" : "kbCategory",
    "nameField" : null,
    "id" : "1000000000483",
    "pluralLabel" : "Articles",
    "singularLabel" : "Article"
  }, {
    "displayLabel" : "Contacts",
    "apiKey" : "contacts",
    "nameField" : null,
    "id" : "1000000000461",
    "pluralLabel" : "Contacts",
    "singularLabel" : "Contact"
  }, {
    "displayLabel" : "Products",
    "apiKey" : "products",
    "nameField" : null,
    "id" : "1000000000487",
    "pluralLabel" : "Products",
    "singularLabel" : "Product"
  }, {
    "displayLabel" : "Accounts",
    "apiKey" : "accounts",
    "nameField" : null,
    "id" : "1000000000459",
    "pluralLabel" : "Accounts",
    "singularLabel" : "Account"
  }, {
    "displayLabel" : "Community",
    "apiKey" : "community",
    "nameField" : null,
    "id" : "1000000000533",
    "pluralLabel" : "Community",
    "singularLabel" : "Community"
  }, {
    "displayLabel" : "Social",
    "apiKey" : "social",
    "nameField" : null,
    "id" : "1000000000535",
    "pluralLabel" : "Social",
    "singularLabel" : "Social"
  }, {
    "displayLabel" : "Chat",
    "apiKey" : "chat",
    "nameField" : null,
    "id" : "1000000000537",
    "pluralLabel" : "Chat",
    "singularLabel" : "Chat"
  }, {
    "displayLabel" : "Activities",
    "apiKey" : "activities",
    "nameField" : null,
    "id" : "1000000000471",
    "pluralLabel" : "Activities",
    "singularLabel" : "Activity"
  }, {
    "displayLabel" : "Calls",
    "apiKey" : "calls",
    "nameField" : null,
    "id" : "1000000000531",
    "pluralLabel" : "Calls",
    "singularLabel" : "Call"
  }, {
    "displayLabel" : "Tasks",
    "apiKey" : "tasks",
    "nameField" : null,
    "id" : "1000000000469",
    "pluralLabel" : "Tasks",
    "singularLabel" : "Task"
  }, {
    "displayLabel" : "Events",
    "apiKey" : "events",
    "nameField" : null,
    "id" : "1000000000529",
    "pluralLabel" : "Events",
    "singularLabel" : "Event"
  }, {
    "displayLabel" : "IM",
    "apiKey" : "im",
    "nameField" : null,
    "id" : "1000000000475",
    "pluralLabel" : "IM",
    "singularLabel" : "IM"
  } ]
}

Records

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

The primary field of the Module for the record

layout

object

The layout of the record

owner

object

The owner of the record

cf

object

The custom fields associated with the Module for the record

department

object

Department associated with the record

id

Long

The unique ID of the record

isPresence

boolean

Specifies whether the record is trashed. The value will be 'false' for records that are in recyclebin.

modifiedBy

object

The user who modified the record

modifiedTime

timestamp

Specifies the time at which changes were made to the record

createdBy

object

The User who created the record

createdTime

timestamp

Specifies the time of creation of the record

Example

{
  "layout" : {
    "id" : "1000003000004",
    "layoutName" : "Standard - Department1"
  },
  "owner" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "modifiedTime" : "2024-04-22T13:55:53.000Z",
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description"
  },
  "createdBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "name" : "Doctor 1",
  "createdTime" : "2024-04-22T13:55:53.000Z",
  "modifiedBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "isPresence" : true,
  "id" : "1000003019049",
  "department" : {
    "departmentName" : "Department1",
    "id" : "1000000025632"
  }
}


Create a Record

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

Attributes

Param Name
Data Type
Description
name

string

required

The primary field of the Module for the record

layout

jsonObject

optional

Layout of the record

department

jsonObject

optional

Department of the record

Note: This key is mandatory if the module is a department-specific module

owner

jsonObject

optional

The owner of the record

cf

jsonObject

optional

Custom fields associated with the record

POST /api/v1/{moduleApiName}

OAuth Scope

Desk.custommodule.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/cm_doctors
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "layout" : {
    "id" : "1000003000004"
  },
  "owner" : {
    "id" : "1000000000375"
  },
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description"
  },
  "name" : "Doctor 1",
  "department" : {
    "id" : "1000000025632"
  }
}'

Response Example

{
  "layout" : {
    "id" : "1000003000004",
    "layoutName" : "Standard - Department1"
  },
  "owner" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "modifiedTime" : "2024-04-22T13:55:53.000Z",
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description"
  },
  "createdBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "name" : "Doctor 1",
  "createdTime" : "2024-04-22T13:55:53.000Z",
  "modifiedBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "isPresence" : true,
  "id" : "1000003019049",
  "department" : {
    "departmentName" : "Department1",
    "id" : "1000000025632"
  }
}

Update a Record

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

Attributes

Param Name
Data Type
Description
name

string

required

The primary field of the Module for the record

layout

jsonObject

optional

Layout of the record

owner

jsonObject

optional

The owner of the record

cf

jsonObject

optional

Custom fields associated with the record

PATCH /api/v1/{moduleApiName}/{entityId}

OAuth Scope

Desk.custommodule.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/cm_doctors/1000003019049
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "layout" : {
    "id" : "1000003000004"
  },
  "owner" : {
    "id" : "1000000000375"
  },
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description change"
  },
  "name" : "Doctor 1",
  "department" : {
    "id" : "1000000025632"
  }
}'

Response Example

{
  "layout" : {
    "id" : "1000003000004",
    "layoutName" : "Standard - Department1"
  },
  "owner" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "modifiedTime" : "2024-04-22T14:09:41.000Z",
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description change"
  },
  "createdBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "name" : "Doctor 1",
  "createdTime" : "2024-04-22T13:55:53.000Z",
  "modifiedBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "isPresence" : true,
  "id" : "1000003019049",
  "department" : {
    "departmentName" : "Department1",
    "id" : "1000000025632"
  }
}

Get a Record

This API fetches a single record.

Credit: 1 credit/call

GET /api/v1/{moduleApiName}/{entityId}

OAuth Scope

Desk.custommodule.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/cm_doctors/1000003019049
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "layout" : {
    "id" : "1000003000004",
    "layoutName" : "Standard - Department1"
  },
  "owner" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "modifiedTime" : "2024-04-22T14:09:41.000Z",
  "cf" : {
    "cf_doctor_description" : "Doctor 1 description change"
  },
  "createdBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "name" : "Doctor 1",
  "createdTime" : "2024-04-22T13:55:53.000Z",
  "modifiedBy" : {
    "firstName" : "",
    "lastName" : "Kyle",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
    "id" : "4000000000329",
    "email" : "kyle@zylker.com"
  },
  "isPresence" : true,
  "id" : "1000003019049",
  "department" : {
    "departmentName" : "Department1",
    "id" : "1000000025632"
  }
}

Get Records

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

Query Params

Param Name
Data Type
Description
viewId

long

optional

The ID of the view from which records need to be fetched.

from

integer

optional,
default : 0

The starting index number from where the records should be fetched.

limit

integer

optional,
default : 50,
range : 1-50

The number of records that need to be fetched.

sortBy

string

optional,
max chars : 100

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.

fields

string

optional,
max chars : 100

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.

GET /api/v1/{moduleApiName}

OAuth Scope

Desk.custommodule.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/cm_doctors?limit=50&from=1&viewId=1000003000413&sortBy=-createdTime&fields=createdTime,id
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "layout" : {
      "id" : "1000003000004",
      "layoutName" : "Standard - Department1"
    },
    "owner" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "modifiedTime" : "2024-04-22T14:18:17.000Z",
    "createdBy" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "name" : "Doctor 2",
    "createdTime" : "2024-04-22T14:18:17.000Z",
    "modifiedBy" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "id" : "1000003019058",
    "department" : {
      "departmentName" : "Department1",
      "id" : "1000000025632"
    }
  }, {
    "layout" : {
      "id" : "1000003000004",
      "layoutName" : "Standard - Department1"
    },
    "owner" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "modifiedTime" : "2024-04-22T14:09:41.000Z",
    "createdBy" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "name" : "Doctor 1",
    "createdTime" : "2024-04-22T13:55:53.000Z",
    "modifiedBy" : {
      "firstName" : "",
      "lastName" : "Kyle",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000329/photo?orgId=3981311",
      "id" : "4000000000329",
      "email" : "kyle@zylker.com"
    },
    "id" : "1000003019049",
    "department" : {
      "departmentName" : "Department1",
      "id" : "1000000025632"
    }
  } ]
}

Get record count

This API fetches the number of records.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

ID of the view from which the record count needs to be fetched.

GET /api/v1/{moduleApiName}/count

OAuth Scope

Desk.custommodule.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/cm_doctors/count?viewId=1000003000413
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "2"
}

Move Records To Trash

This API moves records to the Recycle Bin.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
recordIds

list

required

IDs of the records to move to the Recycle Bin

POST /api/v1/{moduleApiName}/moveToTrash

OAuth Scope

Desk.custommodule.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/cm_doctors/moveToTrash
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "recordIds" : [ "1000003019001" ]
}'

Response Example

{
  "data" : [ {
    "success" : true,
    "id" : "1000003019001",
    "errors" : null
  } ]
}

Update Many records

The API simultaneously updates multiple records.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the records to update. Note: The maximum number of IDs allowed is 50.

fieldName

string

required,
max chars : 320

Name of the field to update

fieldValue

string

optional,
max chars : 320

Value in the field

POST /api/v1/{moduleApiName}/updateMany

OAuth Scope

Desk.custommodule.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/cm_doctors/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldName" : "cf_doctor_description",
  "ids" : [ "1000003019070", "1000003019058" ],
  "fieldValue" : "Doctor description"
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1000003019058",
    "errors" : null
  }, {
    "success" : true,
    "id" : "1000003019070",
    "errors" : null
  } ]
}

OrganizationFields

Account refers to customer organizations that use your products or services. An account can have multiple contacts.

ATTRIBUTES

Attribute Name
Data Type
Description
isEncryptedField

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

displayLabel

string

Name of the field on the UI

name 

deprecated

string

Name of the custom field

apiName

string

Unique readonly name of the custom field that can be used to update value of record in api

i18NLabel

string

i18nlabel for the field label

type

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

maxLength

integer

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

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

roundingOption

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

defaultValue

string

Default value set for a field. Applicable for Checkbox fields

showToHelpCenter

boolean

Is this field available in help center

toolTip

string

the tool tip of the field

toolTipType

string

the tool tip of the field

isTrackLastActivityTime

boolean

While enabled tracks the last activity of the particular field

Example

{
  "displayLabel" : "Department",
  "apiName" : "departmentId",
  "isCustomField" : false,
  "showToHelpCenter" : true,
  "isEncryptedField" : false,
  "id" : "4000000000353",
  "type" : "LookUp",
  "maxLength" : 50,
  "isMandatory" : false,
  "properties" : {
    "translatable" : true
  }
}


Get organization fields in a module

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

Query Params

Param Name
Data Type
Description
module

String

required

the module name with in which search to be done. Value may be tickets, contacts , accounts ,tasks , calls , events, timeEntry,products, contracts, agents

apiNames

string

optional,
max chars : 100

Key that fetches only the fields whose apiNames are given. Multiple values can be passed, with commas for separation.

departmentId
see documentation

long

optional

Key that fetches only the fields for the given departmentId.

GET /api/v1/organizationFields

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields?module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "displayLabel" : "Department",
    "apiName" : "departmentId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000353",
    "type" : "LookUp",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Account Name",
    "apiName" : "accountId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000355",
    "type" : "LookUp",
    "maxLength" : 300,
    "isMandatory" : false
  }, {
    "displayLabel" : "Contact Name",
    "apiName" : "contactId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000357",
    "type" : "LookUp",
    "maxLength" : 300,
    "isMandatory" : true
  }, {
    "displayLabel" : "Email",
    "apiName" : "email",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000359",
    "type" : "Email",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Phone",
    "apiName" : "phone",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000361",
    "type" : "Phone",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Subject",
    "apiName" : "subject",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000363",
    "type" : "Text",
    "maxLength" : 255,
    "isMandatory" : true
  }, {
    "displayLabel" : "Description",
    "apiName" : "description",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000365",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ {
      "statusType" : "Open",
      "value" : "Open"
    }, {
      "statusType" : "Open",
      "value" : "Open_july"
    }, {
      "statusType" : "Open",
      "value" : "Open_newDept"
    }, {
      "statusType" : "On Hold",
      "value" : "On Hold"
    }, {
      "statusType" : "Open",
      "value" : "Escalated"
    }, {
      "statusType" : "Closed",
      "value" : "Closed1"
    }, {
      "statusType" : "Open",
      "value" : "Closed"
    }, {
      "statusType" : "Closed",
      "value" : "newDeptClosed"
    }, {
      "statusType" : "Closed",
      "value" : "julyDeptClosed"
    }, {
      "statusType" : "Closed",
      "value" : "julyDeptClosed1"
    } ],
    "apiName" : "status",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000367",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : true
  }, {
    "displayLabel" : "Product Name",
    "apiName" : "productId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000369",
    "type" : "LookUp",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Case Owner",
    "apiName" : "assigneeId",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000371",
    "type" : "LookUp",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Category",
    "allowedValues" : [ {
      "value" : "General"
    }, {
      "value" : "Defects"
    }, {
      "value" : "ManojKumar"
    } ],
    "apiName" : "category",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000421",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Sub Category",
    "allowedValues" : [ {
      "value" : "Sub General"
    }, {
      "value" : "Sub Defects"
    }, {
      "value" : "Sub Defects1235"
    } ],
    "apiName" : "subCategory",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000423",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Due Date",
    "apiName" : "dueDate",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000405",
    "type" : "DateTime",
    "maxLength" : 300,
    "isMandatory" : false
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ {
      "value" : "-None-"
    }, {
      "value" : "High"
    }, {
      "value" : "Medium"
    }, {
      "value" : "Low"
    } ],
    "apiName" : "priority",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000407",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Mode",
    "allowedValues" : [ {
      "value" : "Phone"
    }, {
      "value" : "Email"
    }, {
      "value" : "Web"
    }, {
      "value" : "Twitter"
    }, {
      "value" : "Facebook"
    }, {
      "value" : "Chat"
    }, {
      "value" : "Forums"
    }, {
      "value" : "Feedback Widget"
    } ],
    "apiName" : "channel",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000409",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Is Overdue",
    "apiName" : "Is Overdue",
    "isCustomField" : false,
    "defaultValue" : "true",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000411",
    "type" : "Boolean",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Is Escalated",
    "apiName" : "Is Escalated",
    "isCustomField" : false,
    "defaultValue" : "true",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000413",
    "type" : "Boolean",
    "maxLength" : 50,
    "isMandatory" : false
  }, {
    "displayLabel" : "Classification",
    "allowedValues" : [ {
      "value" : "-None-"
    }, {
      "value" : "Question"
    }, {
      "value" : "Problem"
    }, {
      "value" : "Feature"
    }, {
      "value" : "Others"
    } ],
    "apiName" : "classification",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000415",
    "type" : "Picklist",
    "maxLength" : 120,
    "isMandatory" : false
  }, {
    "displayLabel" : "Resolution",
    "apiName" : "resolution",
    "isCustomField" : false,
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "id" : "4000000000417",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  }, {
    "displayLabel" : "Sample Text Field",
    "apiName" : "cf_sample_text_field",
    "isCustomField" : false,
    "toolTipType" : "placeHolder",
    "showToHelpCenter" : true,
    "isEncryptedField" : false,
    "toolTip" : "Sample Text Field",
    "id" : "4000000000447",
    "type" : "Textarea",
    "maxLength" : 1000000,
    "isMandatory" : false
  }, {
    "displayLabel" : "Large Text Field",
    "apiName" : "cf_large_text_field",
    "isCustomField" : true,
    "i18NLabel" : "Large Text Field",
    "name" : "LargeText field",
    "isEncryptedField" : false,
    "id" : "4000000000449",
    "type" : "LargeText",
    "maxLength" : 16000000,
    "isMandatory" : false,
    "properties" : {
      "translatable" : true
    }
  } ]
}

Create Field

This API creates a field

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
module

String

required

Name of the module whose fields must be fetched. Values allowed are tickets, contacts, accounts, tasks, timeEntry, products , calls , events, and contracts.

Attributes

Param Name
Data Type
Description
isEncryptedField

boolean

optional

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

displayLabel

string

required,
max chars : 250

Name of the field on the UI

name 
deprecated

string

optional,
max chars : 250

Name of the custom field

type

string

required,
max chars : 100

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

maxLength

integer

optional

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

optional

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

optional

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

roundingOption

string

optional,
max chars : 120

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

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields

toolTip

string

optional,
max chars : 200

the tool tip of the field

toolTipType

string

optional,
max chars : 200

the tool tip of the field

isTrackLastActivityTime

boolean

optional

While enabled tracks the last activity of the particular field

POST /api/v1/organizationFields

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/organizationFields?module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "displayLabel" : "Sample Text Field",
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : true,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "type" : "Text",
  "maxLength" : "50"
}'

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : true,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 50,
  "isMandatory" : false
}

Edit Field

This API edits a field

Credit: 50 credits/call

Attributes

Param Name
Data Type
Description
isEncryptedField

boolean

optional

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

displayLabel

string

optional,
max chars : 250

Name of the field on the UI

name 
deprecated

string

optional,
max chars : 250

Name of the custom field

type

string

optional,
max chars : 100

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

maxLength

integer

optional

Maximum permissible length of the value in the field. Applicable for Text, Number, Decimal, and Currency fields

decimalPlaces

integer

optional

Number of decimal places the value in a field can take. Applicable for Decimal and Currency fields

roundingPrecision

integer

optional

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

roundingOption

string

optional,
max chars : 120

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

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields

toolTip

string

optional,
max chars : 200

the tool tip of the field

toolTipType

string

optional,
max chars : 200

the tool tip of the field

isTrackLastActivityTime

boolean

optional

While enabled tracks the last activity of the particular field

PATCH /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/organizationFields/4000000049001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "displayLabel" : "Sample Text Field",
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : false,
  "toolTip" : "Sample Text Field",
  "type" : "Text",
  "maxLength" : "40"
}'

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : false,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 40,
  "isMandatory" : false
}

Get Field

This API get a field

Credit: 1 credit/call

GET /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields/4000000049001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "displayLabel" : "Sample Text Field",
  "apiName" : "cf_sample_text_field",
  "isCustomField" : true,
  "toolTipType" : "placeHolder",
  "showToHelpCenter" : false,
  "isEncryptedField" : true,
  "toolTip" : "Sample Text Field",
  "id" : "4000000049001",
  "type" : "Text",
  "maxLength" : 40,
  "isMandatory" : false
}

Get Field Permissions

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

GET /api/v1/organizationFields/{field_id}/permissions

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/organizationFields/4000000049001/permissions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "profileName" : "Administrator",
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Standard",
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Supervisor",
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Support Manager",
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Newbie Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Light Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  } ]
}

Update Field Permissions

This API update field permissions

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
profiles

list

optional

null

PATCH /api/v1/organizationFields/{field_id}/permissions

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/organizationFields/4000000049001/permissions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "profiles" : [ {
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isWriteOnly" : true
  }, {
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isWriteOnly" : true
  } ]
}'

Response Example

{
  "data" : [ {
    "profileName" : "Administrator",
    "isReadOnly" : false,
    "profileId" : "4000000012339",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Standard",
    "isReadOnly" : false,
    "profileId" : "4000000012342",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Supervisor",
    "isReadOnly" : false,
    "profileId" : "4000000012348",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Support Manager",
    "isReadOnly" : false,
    "profileId" : "4000000012351",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Newbie Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012354",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  }, {
    "profileName" : "Light Agent",
    "isReadOnly" : false,
    "profileId" : "4000000012357",
    "isInVisibleAccess" : false,
    "isReadAccess" : false,
    "isInVisible" : false,
    "isWriteOnly" : true,
    "isWriteAccess" : true,
    "isCustomProfile" : false
  } ]
}

Delete Field

This API delete a custom field

Credit: 500 credits/call

DELETE /api/v1/organizationFields/{field_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/organizationFields/4000000049001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get organization custom fields count in a module

This API returns the custom field count allowed and available in a module.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
module

String

required

Name 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.

departmentId
see documentation

long

optional

ID of the department in which the layout is configured.

GET /api/v1/customFieldCount

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/customFieldCount?module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "customFieldCounts" : [ {
    "types" : [ "Text", "PickList", "Email", "Phone", "Website" ],
    "maximumLimit" : 100,
    "available" : 100,
    "type" : "Varchar"
  }, {
    "types" : [ "Textarea", "Multiselect" ],
    "maximumLimit" : 30,
    "available" : 30,
    "type" : "Text"
  }, {
    "types" : [ "Number" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Integer"
  }, {
    "types" : [ "Percent", "Decimal", "Currency" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Double"
  }, {
    "types" : [ "Date" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Date"
  }, {
    "types" : [ "DateTime" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "DateTime"
  }, {
    "types" : [ "Checkbox" ],
    "maximumLimit" : 20,
    "available" : 20,
    "type" : "Boolean"
  }, {
    "types" : [ "Text", "Website", "Email", "Number", "Phone", "Percent", "Decimal" ],
    "maximumLimit" : 10,
    "available" : 10,
    "type" : "DESK_SEARCHABLE_CTEXT_OEK"
  }, {
    "maximumLimit" : 10,
    "available" : 10,
    "type" : "Formula"
  } ],
  "totalAvailableCount" : 230
}

Get organization custom fields criteria references

This API fetches criteria references of a custom field

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
featureType

String

required

Feature name from which criteria references has to be fetched - DirectAssignment, RoundRobin, WorkFlow, SLA, Supervise, BluePrint, CustomView, Report, GameTrophy, GameBadge, LayoutRules, ValidationRules

from

integer

required,
default : 0,
range : >=0

Index number, starting from which the rules must be listed

limit

integer

required,
default : 50,
range : 1-50

Number of references to fetch

GET /api/v1/organizationFields/{field_id}/criteriaReferences

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/organizationFields/4000000049001/criteriaReferences?featureType=DirectAssignment&from=0&limit30
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "DirectAssignment" : [ {
    "encryptedId" : "c50bd2066db398caace9491e3010e657",
    "name" : "DA Rule1",
    "id" : 21000000057136
  }, {
    "encryptedId" : "c50bd2066db398caace9491e789a5cb3",
    "name" : "DA Rule2",
    "id" : 21000000067146
  } ]
}

Layouts

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the layout

createdBy

long

ID of user who created the layout

modifiedBy

long

ID of user who modified the layout

departmentId

long

ID of department in which the layout is configured

createdTime

timestamp

Time of creating the layout

modifiedTime

timestamp

Time of modifying the layout

isDefaultLayout

boolean

Key that returns if the layout is the default layout in the module

layoutName

string

Name of the layout

layoutDesc

string

Description of the layout

layoutDisplayName

string

Display Name of the layout in HelpCenter

sections

list

sections in the layout

Example

{
  "modifiedTime" : "2017-07-01T07:36:04.000Z",
  "skipDeptAccessValidation" : false,
  "layoutProfiles" : [ {
    "profileName" : "Support Administrator",
    "isDefault" : true,
    "id" : 4000000015183,
    "type" : "ADMIN"
  }, {
    "profileName" : "Agent",
    "isDefault" : true,
    "id" : 4000000015186,
    "type" : "STANDARD"
  }, {
    "profileName" : "Help Center",
    "isDefault" : true,
    "id" : 4000000015189,
    "type" : "PORTAL"
  }, {
    "profileName" : "Supervisor",
    "isDefault" : false,
    "id" : "4000000015192",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Support Manager",
    "isDefault" : false,
    "id" : "4000000015195",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Newbie Agent",
    "isDefault" : false,
    "id" : "4000000015198",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Light Agent",
    "isDefault" : true,
    "id" : "4000000015201",
    "type" : "LIGHT"
  } ],
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "layoutDisplayName" : "Default Ticket Layout",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "layoutDesc" : "Layout for the ticket module",
  "layoutName" : "Default Ticket Layout"
}


List Layouts

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

Query Params

Param Name
Data Type
Description
module

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

departmentId
see documentation

long

optional

ID of the department in which the layouts are configured

status

String

required,
default : active

Status of the layout. The allowed values are
active,inactive, and all

from

integer

required,
default : 0

The starting index number from where the layouts should be fetched

limit

integer

required,
default : 100

The number of layouts to be fetched

layoutName

string

optional,
max chars : 200

Name of the layout

id

long

optional

ID of the layout

GET /api/v1/layouts

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts?module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2019-05-09T06:24:10.000Z",
    "departmentId" : "4000000012710",
    "module" : "Cases",
    "layoutDisplayName" : "New Layout For Tickets",
    "layoutDesc" : "DESC",
    "isDefaultLayout" : true,
    "layoutName" : "New Layout For Tickets",
    "skipDeptAccessValidation" : false,
    "layoutProfiles" : [ {
      "profileName" : "Support Administrator",
      "isDefault" : true,
      "id" : "4000000015183",
      "type" : "ADMIN"
    }, {
      "profileName" : "Agent",
      "isDefault" : true,
      "id" : "4000000015186",
      "type" : "STANDARD"
    }, {
      "profileName" : "Help Center",
      "isDefault" : true,
      "id" : "4000000015189",
      "type" : "PORTAL"
    } ],
    "createdBy" : "4000000015894",
    "createdTime" : "2019-05-03T06:36:33.000Z",
    "modifiedBy" : "4000000015894",
    "id" : "4000000013464",
    "status" : "active"
  }, {
    "modifiedTime" : "2019-05-06T01:45:58.000Z",
    "departmentId" : "4000000012710",
    "module" : "Cases",
    "layoutDisplayName" : "cloneLayout",
    "layoutDesc" : "DESC",
    "isDefaultLayout" : false,
    "layoutName" : "cloneLayout",
    "skipDeptAccessValidation" : false,
    "layoutProfiles" : [ {
      "profileName" : "Support Administrator",
      "isDefault" : true,
      "id" : "4000000015183",
      "type" : "ADMIN"
    }, {
      "profileName" : "Agent",
      "isDefault" : true,
      "id" : "4000000015186",
      "type" : "STANDARD"
    }, {
      "profileName" : "Help Center",
      "isDefault" : true,
      "id" : "4000000015189",
      "type" : "PORTAL"
    }, {
      "profileName" : "Supervisor",
      "isDefault" : false,
      "id" : "4000000015192",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Support Manager",
      "isDefault" : false,
      "id" : "4000000015195",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Newbie Agent",
      "isDefault" : false,
      "id" : "4000000015198",
      "type" : "CUSTOM"
    }, {
      "profileName" : "Light Agent",
      "isDefault" : true,
      "id" : "4000000015201",
      "type" : "LIGHT"
    } ],
    "createdBy" : "4000000015894",
    "createdTime" : "2019-05-06T01:45:58.000Z",
    "modifiedBy" : "4000000015894",
    "id" : "4000000017001",
    "status" : "active"
  } ]
}

Get Layout

This API fetches a layout configured for a module

Credit: 1 credit/call

GET /api/v1/layouts/{layout_id}

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007177
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-07-01T07:36:04.000Z",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "layoutDisplayName" : "Default Ticket Layout",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Education Type",
      "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
      "apiName" : "cf_education_type",
      "isCustomField" : true,
      "defaultValue" : "Education :: University :: Private",
      "isNested" : true,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000009999",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "apiName" : "category",
      "isCustomField" : false,
      "defaultValue" : "General",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000421",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "apiName" : "status",
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isNested" : false,
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000407",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutDesc" : "Default Layout of the Ticket",
  "layoutName" : "Default Ticket Layout"
}

Clone Layout

This API creates new Layout by cloning existing layout.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
layoutName

string

required,
max chars : 150

Name of the layout

layoutDesc

string

optional,
max chars : 500

Description of the layout

layoutDisplayName

string

required,
max chars : 150

Display Name of the layout in HelpCenter

isDefaultLayout

boolean

required

Key that returns if the layout is the default layout in the module

departmentId

long

optional

Id which helps to clone a layout in another department

POST /api/v1/layouts/{layout_id}/clone

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000013462/clone
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skipDeptAccessValidation" : false,
  "layoutDisplayName" : "Clonned Account Layout",
  "isDefaultLayout" : false,
  "layoutDesc" : "Layout of the accounts",
  "layoutName" : "cloneAccLayout1"
}'

Response Example

{
  "modifiedTime" : "2019-05-08T02:21:34.000Z",
  "module" : "Accounts",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "layout of the accounts",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Account Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountName",
      "id" : "4000000000404",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 200,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000408",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000406",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Website",
      "isCustomField" : false,
      "name" : "website",
      "id" : "4000000000410",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "URL",
      "maxLength" : 2083,
      "isMandatory" : false
    }, {
      "displayLabel" : "Country",
      "isCustomField" : false,
      "name" : "country",
      "id" : "4000000000438",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Text",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Account Owner",
      "isCustomField" : false,
      "name" : "ownerId",
      "id" : "4000000000412",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Education Type",
      "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
      "apiName" : "cf_education_type",
      "isCustomField" : true,
      "defaultValue" : "Education :: University :: Private",
      "isNested" : true,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000009999",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "cloneAccLayout1",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-08T02:21:34.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000039001",
  "status" : "active"
}

Create Layout

This API creates the layout

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isDefaultLayout

boolean

required

Key that returns if the layout is the default layout in the module

sections

list

required

sections in the layout

module

string

required,
max chars : 100

mdoule name

POST /api/v1/layouts

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skipDeptAccessValidation" : false,
  "module" : "accounts",
  "departmentId" : "4000000012710",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "DESC",
  "sections" : [ {
    "name" : "Account Information",
    "i18NLabel" : "Account Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "id" : "4000000000404",
      "isMandatory" : true
    }, {
      "id" : "4000000000408",
      "isMandatory" : false
    }, {
      "id" : "4000000000406",
      "isMandatory" : false
    }, {
      "id" : "4000000000410",
      "isMandatory" : false
    }, {
      "id" : "4000000000438",
      "isMandatory" : false
    }, {
      "id" : "4000000000412",
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "accounts layout "
}'

Response Example

{
  "modifiedTime" : "2019-05-09T04:52:57.000Z",
  "departmentId" : "4000000012710",
  "module" : "Accounts",
  "layoutDisplayName" : "Clonned Account Layout",
  "layoutDesc" : "DESC",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Account Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountName",
      "id" : "4000000000404",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 200,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000408",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000406",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Website",
      "isCustomField" : false,
      "name" : "website",
      "id" : "4000000000410",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "URL",
      "maxLength" : 2083,
      "isMandatory" : false
    }, {
      "displayLabel" : "Country",
      "isCustomField" : false,
      "name" : "country",
      "id" : "4000000000438",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Text",
      "maxLength" : 30,
      "isMandatory" : false
    }, {
      "displayLabel" : "Account Owner",
      "isCustomField" : false,
      "name" : "ownerId",
      "id" : "4000000000412",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "accounts layout ",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-09T04:52:57.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000043004",
  "status" : "active"
}

Update Layout

This API updates details of an existing layout.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isDefaultLayout

boolean

optional

Key that returns if the layout is the default layout in the module

sections

list

optional

sections in the layout

module

string

optional,
max chars : 100

mdoule name

PATCH /api/v1/layouts/{layout_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007177
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skipDeptAccessValidation" : false,
  "layoutDisplayName" : "ClonedLayout",
  "layoutDesc" : "Layout cloned from default layout",
  "sections" : [ {
    "name" : "Ticket Information",
    "i18NLabel" : "Ticket Information",
    "id" : 1,
    "fields" : [ {
      "id" : "4000000000353",
      "isMandatory" : true
    }, {
      "id" : "4000000000357",
      "isMandatory" : true
    }, {
      "id" : "4000000000355",
      "isMandatory" : false
    }, {
      "id" : "4000000000359",
      "isMandatory" : false
    }, {
      "id" : "4000000000361",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
      "defaultValue" : "Education :: University :: Private",
      "isNested" : true,
      "sortBy" : "userDefined",
      "id" : "4000000009999",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "defaultValue" : "Sub General",
      "isNested" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "General", "Defects" ],
      "defaultValue" : "General",
      "isNested" : false,
      "id" : "4000000000421",
      "isMandatory" : false
    }, {
      "id" : "4000000000363",
      "isMandatory" : true
    }, {
      "id" : "4000000000365",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "defaultValue" : "Open",
      "isNested" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isMandatory" : true
    }, {
      "id" : "4000000000371",
      "isMandatory" : false
    }, {
      "id" : "4000000000369",
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "i18NLabel" : "Additional Information",
    "id" : 2,
    "fields" : [ {
      "id" : "4000000000405",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "defaultValue" : "-None-",
      "isNested" : false,
      "id" : "4000000000407",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "defaultValue" : "Phone",
      "isNested" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isMandatory" : false
    }, {
      "id" : "4000000000411",
      "isMandatory" : false
    }, {
      "id" : "4000000000413",
      "isMandatory" : false
    }, {
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "defaultValue" : "-None-",
      "isNested" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isMandatory" : false
    }, {
      "id" : "4000000000417",
      "isMandatory" : false
    }, {
      "id" : "4000000000447",
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "ClonedLayout"
}'

Response Example

{
  "modifiedTime" : "2017-07-01T07:36:04.000Z",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "layoutDisplayName" : "ClonedLayout",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Education Type",
      "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
      "apiName" : "cf_education_type",
      "isCustomField" : true,
      "defaultValue" : "Education :: University :: Private",
      "isNested" : true,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000009999",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000423",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "apiName" : "category",
      "isCustomField" : false,
      "defaultValue" : "General",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000421",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "apiName" : "status",
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isNested" : false,
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000407",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000409",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000000415",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutDesc" : "Layout cloned from default layout",
  "layoutName" : "Default Ticket Layout"
}

Delete Layout

This API deletes a layout

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
transferToLayoutId

long

required

The layout id to which the entities in the deleted layout to be transferred to

DELETE /api/v1/layouts/{layout_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000038053
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "transferToLayoutId" : "4000000038039"
}'

Response Example

204

DeActivate Layout

This Api deactivates existing layout

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
transferToLayoutId

long

required

The layout id to which the entities in the deleted layout to be transferred to

POST /api/v1/layouts/{layout_id}/deactivate

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000038053/deactivate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "transferToLayoutId" : "4000000038039"
}'

Response Example

204

Activate Layout

This api activates the deactivated Layout.

Credit: 1 credit/call

POST /api/v1/layouts/{layout_id}/activate

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000038053/activate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2019-05-09T09:42:28.000Z",
  "departmentId" : "4000000012710",
  "module" : "Cases",
  "layoutDisplayName" : "ClonedLayout",
  "layoutDesc" : "DESC",
  "isDefaultLayout" : false,
  "sections" : [ {
    "name" : "Case Information",
    "isCustomSection" : true,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "isCustomField" : false,
      "name" : "departmentId",
      "id" : "4000000000556",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "isCustomField" : false,
      "name" : "contactId",
      "id" : "4000000000560",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountId",
      "id" : "4000000000558",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000562",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000564",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "isCustomField" : false,
      "name" : "subject",
      "id" : "4000000000566",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "isCustomField" : false,
      "name" : "description",
      "id" : "4000000000568",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isNested" : false,
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000570",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Ticket Owner",
      "isCustomField" : false,
      "name" : "assigneeId",
      "id" : "4000000000574",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "isCustomField" : false,
      "name" : "productId",
      "id" : "4000000000572",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : true,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "isCustomField" : false,
      "name" : "dueDate",
      "id" : "4000000000610",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "name" : "priority",
      "sortBy" : "userDefined",
      "id" : "4000000000614",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Channel",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "name" : "channel",
      "sortBy" : "userDefined",
      "id" : "4000000000616",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "name" : "classification",
      "sortBy" : "userDefined",
      "id" : "4000000000622",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "isCustomField" : false,
      "name" : "resolution",
      "id" : "4000000000624",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "Tickets New Layout 6",
  "skipDeptAccessValidation" : false,
  "createdBy" : "4000000015894",
  "createdTime" : "2019-05-06T05:30:06.000Z",
  "modifiedBy" : "4000000015894",
  "id" : "4000000038033",
  "status" : "active"
}

Get Layout Profiles

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

GET /api/v1/layouts/{layout_id}/profiles

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000038033/profiles
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "profileName" : "Support Administrator",
    "isDefault" : true,
    "id" : "4000000015183",
    "type" : "ADMIN"
  }, {
    "profileName" : "Agent",
    "isDefault" : true,
    "id" : "4000000015186",
    "type" : "STANDARD"
  }, {
    "profileName" : "Help Center",
    "isDefault" : true,
    "id" : "4000000015189",
    "type" : "PORTAL"
  }, {
    "profileName" : "Supervisor",
    "isDefault" : false,
    "id" : "4000000015192",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Support Manager",
    "isDefault" : false,
    "id" : "4000000015195",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Newbie Agent",
    "isDefault" : false,
    "id" : "4000000015198",
    "type" : "CUSTOM"
  }, {
    "profileName" : "Light Agent",
    "isDefault" : true,
    "id" : "4000000015201",
    "type" : "LIGHT"
  } ]
}

Associate Layout profiles

This api Associates the given profiles to the layout

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
layoutProfileIds

list

optional

The profile id to which the layout needs to be associated to

PATCH /api/v1/layouts/{layout_id}/profiles

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000013464/profiles
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "layoutProfileIds" : [ 4000000015183, 4000000015186, 4000000015189 ]
}'

Response Example

204

Standard Layout Format

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

Query Params

Param Name
Data Type
Description
module

String

required

Name of the module whose layouts must be fetched. Values allowed are tickets, contacts, accounts , calls , events, tasks, timeEntry, products, and contracts.

GET /api/v1/layouts/standardLayoutFormat

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/standardLayoutFormat?module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "Case Information",
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "isCustomField" : false,
      "name" : "departmentId",
      "id" : "4000000000556",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "isCustomField" : false,
      "name" : "accountId",
      "id" : "4000000000558",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Contact Name",
      "isCustomField" : false,
      "name" : "contactId",
      "id" : "4000000000560",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Email",
      "isCustomField" : false,
      "name" : "email",
      "id" : "4000000000562",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "isCustomField" : false,
      "name" : "phone",
      "id" : "4000000000564",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "isCustomField" : false,
      "name" : "subject",
      "id" : "4000000000566",
      "isSystemMandatory" : true,
      "isRemovable" : false,
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "isCustomField" : false,
      "name" : "description",
      "id" : "4000000000568",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open", "On Hold", "Escalated", "Closed" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000570",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Product Name",
      "isCustomField" : false,
      "name" : "productId",
      "id" : "4000000000572",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Ticket Owner",
      "isCustomField" : false,
      "name" : "assigneeId",
      "id" : "4000000000574",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "isCustomField" : false,
      "name" : "dueDate",
      "id" : "4000000000610",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "priority",
      "sortBy" : "userDefined",
      "id" : "4000000000614",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Channel",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "name" : "channel",
      "sortBy" : "userDefined",
      "id" : "4000000000616",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "name" : "classification",
      "sortBy" : "userDefined",
      "id" : "4000000000622",
      "isSystemMandatory" : false,
      "isRemovable" : true,
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "isCustomField" : false,
      "name" : "resolution",
      "id" : "4000000000624",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ]
}

Get MyForm

This API fetches details of a layout, based on the profile of the current user.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
layoutId

long

optional

ID of the layout

GET /api/v1/myForm

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myForm?layoutId=4000000007177
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2017-07-10T10:32:11.000Z",
  "createdBy" : "4000000009118",
  "departmentId" : "4000000007175",
  "createdTime" : "2017-07-01T07:36:04.000Z",
  "modifiedBy" : "4000000009118",
  "id" : "4000000007177",
  "isDefaultLayout" : true,
  "sections" : [ {
    "name" : "Ticket Information",
    "isCustomSection" : false,
    "id" : 1,
    "fields" : [ {
      "displayLabel" : "Department",
      "apiName" : "departmentId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000353",
      "type" : "LookUp",
      "maxLength" : 50,
      "isMandatory" : true
    }, {
      "displayLabel" : "Contact Name",
      "apiName" : "contactId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000357",
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : true
    }, {
      "displayLabel" : "Account Name",
      "apiName" : "accountId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000355",
      "type" : "LookUp",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Email",
      "apiName" : "email",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000359",
      "type" : "Email",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Phone",
      "apiName" : "phone",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000361",
      "type" : "Phone",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Education Type",
      "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
      "apiName" : "cf_education_type",
      "isCustomField" : true,
      "defaultValue" : "Education :: University :: Private",
      "isNested" : true,
      "isSystemMandatory" : false,
      "type" : "Picklist",
      "isEncryptedField" : false,
      "sortBy" : "userDefined",
      "id" : "4000000009999",
      "isRemovable" : true,
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "apiName" : "subCategory",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "Sub General",
      "isNested" : false,
      "isEncryptedField" : false,
      "id" : "4000000000423",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects", "ManojKumar" ],
      "apiName" : "category",
      "isCustomField" : false,
      "isReadOnly" : false,
      "defaultValue" : "General",
      "isNested" : false,
      "isEncryptedField" : false,
      "id" : "4000000000421",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Subject",
      "apiName" : "subject",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000363",
      "type" : "Text",
      "maxLength" : 255,
      "isMandatory" : true
    }, {
      "displayLabel" : "Description",
      "apiName" : "description",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000365",
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "Open_newDept", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed", "julyDeptClosed", "julyDeptClosed1" ],
      "apiName" : "status",
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isNested" : false,
      "type" : "Picklist",
      "isReadOnly" : false,
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Open_newDept", "Escalated", "On Hold", "Closed", "Closed1", "julyDeptClosed", "julyDeptClosed1", "Open" ],
      "isEncryptedField" : false,
      "id" : "4000000000367",
      "maxLength" : 120,
      "isMandatory" : true
    }, {
      "displayLabel" : "Case Owner",
      "apiName" : "assigneeId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000371",
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Product Name",
      "apiName" : "productId",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000369",
      "type" : "LookUp",
      "maxLength" : 120,
      "isMandatory" : false
    } ]
  }, {
    "name" : "Additional Information",
    "isCustomSection" : false,
    "id" : 2,
    "fields" : [ {
      "displayLabel" : "Due Date",
      "apiName" : "dueDate",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000405",
      "type" : "DateTime",
      "maxLength" : 300,
      "isMandatory" : false
    }, {
      "displayLabel" : "Priority",
      "allowedValues" : [ "-None-", "High", "Medium", "Low" ],
      "apiName" : "priority",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isEncryptedField" : false,
      "id" : "4000000000407",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "apiName" : "channel",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "Phone",
      "isNested" : false,
      "isEncryptedField" : false,
      "id" : "4000000000409",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Overdue",
      "apiName" : "Is Overdue",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000411",
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Is Escalated",
      "apiName" : "Is Escalated",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "true",
      "isEncryptedField" : false,
      "id" : "4000000000413",
      "type" : "Boolean",
      "maxLength" : 50,
      "isMandatory" : false
    }, {
      "displayLabel" : "Classification",
      "allowedValues" : [ "-None-", "Question", "Problem", "Feature", "Others" ],
      "apiName" : "classification",
      "isReadOnly" : false,
      "isCustomField" : false,
      "defaultValue" : "-None-",
      "isNested" : false,
      "isEncryptedField" : false,
      "id" : "4000000000415",
      "type" : "Picklist",
      "maxLength" : 120,
      "isMandatory" : false
    }, {
      "displayLabel" : "Resolution",
      "apiName" : "resolution",
      "isReadOnly" : false,
      "isCustomField" : false,
      "isEncryptedField" : false,
      "id" : "4000000000417",
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    }, {
      "displayLabel" : "Sample TextArea",
      "apiName" : "cf_sample_textarea",
      "isCustomField" : true,
      "toolTipType" : "placeHolder",
      "isEncryptedField" : false,
      "toolTip" : "Sample Field",
      "id" : "4000000000447",
      "isSystemMandatory" : false,
      "isRemovable" : false,
      "type" : "Textarea",
      "maxLength" : 1000000,
      "isMandatory" : false
    } ]
  } ],
  "layoutName" : "Default Ticket Layout"
}

Replace PickList Value in all Existing Records

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

Attributes

Param Name
Data Type
Description
fieldId

long

required

field Id

oldValue

string

required,
max chars : 100

oldValue

newValue

string

required,
max chars : 100

newValue

POST /api/v1/layouts/{layout_id}/replaceValues

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007177/replaceValues
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "newValue" : "Sub Defects1235",
  "oldValue" : "Sub Defects",
  "fieldId" : "4000000000423"
}'

Response Example

200

Update Layout Field

This API updates details of a field in the layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description

Attributes

Param Name
Data Type
Description
expression

string

optional,
max chars : 1500

Formula Expression

isMandatory

boolean

optional

Key that returns if a field is mandatory in a layout or not

defaultValue

string

optional,
max chars : 120

Default value set for a field. Applicable for Checkbox fields and PickList fields

allowedValues

list

optional

Values allowed in a field. Applicable for PickList fields

sortBy

string

optional,
max chars : 100

Key that sorts values in a PickList field either alphabetically or by a user-defined order

isNested

boolean

optional

Key that returns if the picklist is nested or not

PATCH /api/v1/layouts/{layout_id}/fields/{field_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007177/fields/21000000023005
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
  "defaultValue" : "Education :: University :: Private",
  "isNested" : true,
  "sortBy" : "userDefined",
  "isMandatory" : true
}'

Response Example

{
  "displayLabel" : "Education Type",
  "allowedValues" : [ "Education :: University :: Private", "Education :: University :: Public", "Education :: School :: Private", "Education :: School :: Public" ],
  "apiName" : "cf_education_type",
  "isCustomField" : true,
  "defaultValue" : "Education :: University :: Private",
  "isNested" : true,
  "i18NLabel" : "Education Type",
  "isSystemMandatory" : false,
  "type" : "Picklist",
  "name" : "Education Type",
  "isEncryptedField" : false,
  "sortBy" : "userDefined",
  "id" : "21000000023005",
  "isRemovable" : true,
  "maxLength" : 120,
  "isMandatory" : true
}

Remove Field in Layout

This API is to remove fields from a layout.

Credit: 1 credit/call

POST /api/v1/layouts/{layout_id}/fields/([0-9]+)/unassociate

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007177/fields/4000000000353/unassociate
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Clone Fields to other Layout

This API is to clone a field to other layouts.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
layoutIds

list

optional

List of layout ids to which the field should be cloned.

POST /api/v1/layouts/{layout_id}/fields/([0-9]+)/cloneFieldsInLayout

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/layouts/4000000007177/fields/4000000000353/cloneFieldsInLayout
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "layoutIds" : [ "4000000007187", "4000000007197" ]
}'

Response Example

200

Get PickList Value in Layout

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

Query Params

Param Name
Data Type
Description
fileType

string

optional,
max chars : 100

Export Format in which format should be shown.This value can be CSV

GET /api/v1/layouts/([0-9]+)/fields/([0-9]+)/value

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000013556/fields/4000000028001/value
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

LayoutRules

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

Name of the rule

description

string

A short description of the rule

fieldName

string

Name of the primary field to be used for creating the rule

displayLabel

string

Display Label of the primary field to be used for creating the rule

status

string

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

To execute the rule in help centre or not: true or false

fieldConditions

list

Conditions in the layout rule

Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "fieldName" : "phone",
  "executeInHelpCentre" : false,
  "name" : "Rule 1",
  "description" : "Rule 1 for layout",
  "id" : "4000000020001",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "status" : "active"
}


Get Layout Rule

This API fetches a single rule from your help desk layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000020001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 1",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000020001",
  "status" : "active"
}

Get Layout Rules for department or layout

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

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Get the rules of the department

layoutId

long

optional

Get the rules of the layout

module

String

optional

Name of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events

activeLayouts

Boolean

optional

Get the rules for active layouts

activeRules

Boolean

optional

Get the rules that are active in the layout

executeInHelpCentre

Boolean

optional

Get the rules that can be executed in help centre

from

integer

optional,
default : 0,
range : >=0

Index number, starting from which the rules must be fetched

limit

integer

required,
default : 50,
range : 1-50

Number of rules to be fetched. Default is 50

searchString

String

optional

Get the rules that have this search term

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/layoutRules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layoutRules?layoutId=4000000007723&module=tickets&activeRules=true&from=0&limit=10&searchString=Rule
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldConditions" : [ {
      "name" : "condition 1",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "carol@zylker.com" ]
      }, {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9993292892" ]
      } ],
      "actions" : {
        "showSections" : [ "Additional Information" ],
        "showFields" : [ "subject" ],
        "setMandatoryFields" : [ "priority" ]
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "email",
    "description" : "Rule 1 for layout",
    "systemGenerated" : false,
    "layoutId" : "4000000007723",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "name" : "Rule 1",
    "createdTime" : "2018-09-14T01:07:22.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000020001",
    "status" : "active"
  }, {
    "fieldConditions" : [ {
      "name" : "condition 2",
      "pattern" : "(1or2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9993292892" ]
      }, {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "carol@zylker.com" ]
      } ],
      "actions" : {
        "showSections" : [ "Additional Information" ],
        "showFields" : [ "subject" ],
        "setMandatoryFields" : [ "priority" ]
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "phone",
    "description" : "Rule 2 for layout",
    "systemGenerated" : false,
    "layoutId" : "4000000007723",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "name" : "Rule 2",
    "createdTime" : "2018-09-14T01:07:22.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000021001",
    "status" : "active"
  } ]
}

Create Layout Rule

This API creates a rule for a field in a layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 255

Name of the rule

description

string

optional,
max chars : 255

A short description of the rule

fieldName

string

required,
max chars : 255

Name of the primary field to be used for creating the rule

displayLabel

string

optional,
max chars : 250

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

required

Conditions in the layout rule

POST /api/v1/layouts/{layout_id}/layoutRules

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : true,
  "name" : "Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9993292892" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 2 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : true,
  "createdBy" : "4000000015963",
  "name" : "Rule 2",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Update Layout Rule

This API updates the details of an existing layout rule in a particular layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 255

Name of the rule

description

string

optional,
max chars : 255

A short description of the rule

fieldName

string

optional,
max chars : 255

Name of the primary field to be used for creating the rule

displayLabel

string

optional,
max chars : 250

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

optional

Conditions in the layout rule

PATCH /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000021001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)or3",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Ramkumar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Honda" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  }, {
    "name" : "condition 2",
    "pattern" : "1 and (2 or 3)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Sundar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Maruthi" ]
    } ],
    "actions" : {
      "showSections" : [ ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "Description" ]
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "name" : "Rule 11",
  "description" : "Rule 1 for layout",
  "layoutId" : "4000000007723",
  "status" : "active"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)or3",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Ramkumar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Honda" ]
    } ],
    "actions" : {
      "showSections" : [ "Additional Information" ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "priority" ]
    }
  }, {
    "name" : "condition 2",
    "pattern" : "1 and (2 or 3)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "accountId",
      "value" : [ "Sundar" ]
    }, {
      "condition" : "is",
      "fieldName" : "productId",
      "value" : [ "Maruthi" ]
    } ],
    "actions" : {
      "showSections" : [ ],
      "showFields" : [ "subject" ],
      "setMandatoryFields" : [ "Description" ]
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 11",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Delete Layout Rule

This API deletes a layout rule created for a field from a layout.

Credit: 1 credit/call

DELETE /api/v1/layouts/{layout_id}/layoutRules/{layoutRule_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000007723/layoutRules/4000000021001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List Criteria Fields For Layout Rules

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

Query Params

Param Name
Data Type
Description
category

String

required

Category for getting the field criteria for primary or secondary fields

GET /api/v1/layouts/{layout_id}/layoutRules/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000013564/layoutRules/criteriaFields?category=primary
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "accountId",
      "fieldLabel" : "Account Name",
      "i18NLabel" : "Account Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "contactId",
      "fieldLabel" : "Contact Name",
      "i18NLabel" : "Contact Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "phone",
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "status",
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "productId",
      "fieldLabel" : "Product Name",
      "i18NLabel" : "Product Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "dueDate",
      "fieldLabel" : "Due Date",
      "i18NLabel" : "Due Date",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "priority",
      "fieldLabel" : "Priority",
      "i18NLabel" : "Priority",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "channel",
      "fieldLabel" : "Mode",
      "i18NLabel" : "Mode",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "classification",
      "fieldLabel" : "Classification",
      "i18NLabel" : "Classification",
      "type" : "text"
    } ]
  } ]
}

ValidationRules

Validation rules verify that the data an agent enters in a record meets the standards you specify before the agent can save the record.

ATTRIBUTES

Attribute Name
Data Type
Description
fieldName

string

Name of the primary field to be used for creating the validation rule

displayLabel

string

Display Label of the primary field to be used for creating the rule

status

string

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

To execute the rule in help centre or not: true or false

fieldConditions

list

Conditions in the validation rule

Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994259718" ]
    }, {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zylker.com" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "fieldName" : "phone",
  "executeInHelpCentre" : true,
  "name" : "Validation Rule 1",
  "description" : "Validation Rule 1 for layout",
  "id" : "4000000020001",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "status" : "active"
}


Get Layout Validation Rule

This API fetches a validation rule configured for your layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

GET /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000018001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 1",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "raj@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994259718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "modifiedTime" : "2018-09-14T01:08:42.000Z",
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "createdTime" : "2018-09-14T01:07:22.000Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000018001",
  "systemGenerated" : false,
  "layoutId" : "4000000013564",
  "status" : "active"
}

Get Layout Validation Rules for department or layout

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

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Get the rules of the department

layoutId

long

optional

Get the rules of the layout

module

String

optional

Name of the module for which you want to fetch the layout rules. Allowed values are tickets, contacts, accounts, tasks, timeEntry, contracts, products, calls, events

activeLayouts

Boolean

optional

Get the rules for active layouts

activeRules

Boolean

optional

Get the rules that are active in the layout

from

integer

optional,
default : 0,
range : >=0

Index number, starting from which the rules must be fetched

limit

integer

required,
default : 50,
range : 1-50

Number of rules to be fetched. Default is 50

searchString

String

optional

Get the rules that have this search term

executeInHelpCentre

Boolean

optional

Get the rules that can be executed in help centre

include

string

optional,
max chars : 100

Additional information related to the rules. Values allowed are: creator and modifier.

GET /api/v1/validationRules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/validationRules?layoutId=4000000007723&module=tickets&activeRules=true&from=0&limit=10&searchString=Rule
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "fieldConditions" : [ {
      "name" : "condition 2",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "carol@zylker.com" ]
      }, {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9994259718" ]
      } ],
      "actions" : {
        "alert" : "Sample Alert"
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "email",
    "executeInHelpCentre" : true,
    "createdBy" : "4000000015963",
    "createdTime" : "2018-09-13T01:16:46.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000017001",
    "systemGenerated" : false,
    "layoutId" : "4000000013564"
  }, {
    "fieldConditions" : [ {
      "name" : "condition 1",
      "pattern" : "(1and2)",
      "conditions" : [ {
        "condition" : "is",
        "fieldName" : "phone",
        "value" : [ "9994259718" ]
      }, {
        "condition" : "is",
        "fieldName" : "email",
        "value" : [ "carol@zylker.com" ]
      } ],
      "actions" : {
        "alert" : "Sample Alert"
      }
    } ],
    "modifiedTime" : "2018-09-14T01:08:42.000Z",
    "fieldName" : "phone",
    "executeInHelpCentre" : false,
    "createdBy" : "4000000015963",
    "createdTime" : "2018-09-13T01:49:03.000Z",
    "modifiedBy" : "4000000015963",
    "id" : "4000000018001",
    "systemGenerated" : false,
    "layoutId" : "4000000013564",
    "status" : "active"
  } ]
}

Create Layout Validation Rule

This API creates a validation rule for a field in a layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

Attributes

Param Name
Data Type
Description
fieldName

string

required,
max chars : 255

Name of the primary field to be used for creating the validation rule

displayLabel

string

optional,
max chars : 250

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

required

Conditions in the validation rule

POST /api/v1/layouts/layout_id/validationRules

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "executeInHelpCentre" : true,
  "fieldName" : "email",
  "name" : "Validation Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  } ],
  "modifiedTime" : "2018-09-07T06:50:48.697Z",
  "fieldName" : "email",
  "executeInHelpCentre" : true,
  "createdBy" : "4000000015963",
  "createdTime" : "2018-09-07T06:50:48.697Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000018001",
  "systemGenerated" : false,
  "layoutId" : "4000000013564",
  "status" : "active"
}

Update Layout Validation Rule

This API updates the details of an existing validation rule in a particular layout.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to rules. Values allowed are: creator, modifier

Attributes

Param Name
Data Type
Description
fieldName

string

optional,
max chars : 255

Name of the primary field to be used for creating the validation rule

displayLabel

string

optional,
max chars : 250

Display Label of the primary field to be used for creating the rule

status

string

optional,
max chars : 100

Activation status of the validation rule: ACTIVE or DEACTIVE

executeInHelpCentre

boolean

optional

To execute the rule in help centre or not: true or false

fieldConditions

list

optional

Conditions in the validation rule

PATCH /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000021001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  }, {
    "name" : "condition 3",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "99922299922" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert1"
    }
  } ],
  "fieldName" : "email",
  "executeInHelpCentre" : false,
  "name" : "Validation Rule 1",
  "description" : "Rule 1 for layout"
}'

Response Example

{
  "fieldConditions" : [ {
    "name" : "condition 2",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "9994219718" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert"
    }
  }, {
    "name" : "condition 3",
    "pattern" : "(1and2)",
    "conditions" : [ {
      "condition" : "is",
      "fieldName" : "email",
      "value" : [ "carol@zylker.com" ]
    }, {
      "condition" : "is",
      "fieldName" : "phone",
      "value" : [ "99922299922" ]
    } ],
    "actions" : {
      "alert" : "Sample Alert1"
    }
  } ],
  "modifiedTime" : "2018-09-07T06:50:48.697Z",
  "fieldName" : "email",
  "description" : "Rule 1 for layout",
  "systemGenerated" : false,
  "layoutId" : "4000000007723",
  "executeInHelpCentre" : false,
  "createdBy" : "4000000015963",
  "name" : "Rule 11",
  "createdTime" : "2018-09-07T06:50:48.697Z",
  "modifiedBy" : "4000000015963",
  "id" : "4000000021001",
  "status" : "active"
}

Delete Validation Rule

This API deletes a validation rule created for a field from a layout.

Credit: 1 credit/call

DELETE /api/v1/layouts/{layout_id}/validationRules/{validationRule_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/layouts/4000000007723/validationRules/4000000021001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List Criteria Fields For Layout Validation Rules

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

Query Params

Param Name
Data Type
Description
category

String

required

Category for getting the field criteria for primary or secondary fields

GET /api/v1/layouts/{layout_id}/validationRules/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/layouts/4000000013564/validationRules/criteriaFields?category=primary
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "email",
      "fieldLabel" : "Email",
      "i18NLabel" : "Email",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "phone",
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "subject",
      "fieldLabel" : "Subject",
      "i18NLabel" : "Subject",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "status",
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldName" : "classification",
      "fieldLabel" : "Classification",
      "i18NLabel" : "Classification",
      "type" : "text"
    } ]
  } ]
}

DependencyMappings

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. 

ATTRIBUTES

Attribute Name
Data Type
Description
layoutId

long

ID of the layout in which the dependency is mapped

parentId

long

ID of the parent field

childId

long

ID of the child field

mappings

list

JSON object that shows the mapping configured

Example

{
  "parent" : {
    "displayLabel" : "Category",
    "allowedValues" : [ "General", "Defects" ],
    "id" : "4000000000421"
  },
  "mappings" : {
    "General" : [ "Sub General" ],
    "Defects" : [ "Sub Defects" ]
  },
  "id" : "4000000007315",
  "childId" : "4000000000423",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421",
  "child" : {
    "displayLabel" : "Sub Category",
    "allowedValues" : [ "Sub General", "Sub Defects" ],
    "id" : "4000000000423"
  }
}


List dependency mappings in a layout

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

Query Params

Param Name
Data Type
Description
layoutId

long

optional

ID of the layout in which the dependency is mapped

GET /api/v1/dependencyMappings

OAuth Scope

Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/dependencyMappings?layoutId=4000000007177
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "parent" : {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "id" : "4000000000421"
    },
    "mappings" : {
      "General" : [ "Sub General" ],
      "Defects" : [ "Sub Defects" ]
    },
    "id" : "4000000007315",
    "childId" : "4000000000423",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000421",
    "child" : {
      "displayLabel" : "Sub Category",
      "allowedValues" : [ "Sub General", "Sub Defects" ],
      "id" : "4000000000423"
    }
  }, {
    "parent" : {
      "displayLabel" : "Category",
      "allowedValues" : [ "General", "Defects" ],
      "id" : "4000000000421"
    },
    "mappings" : {
      "General" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "Defects" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ]
    },
    "id" : "4000000031003",
    "childId" : "4000000000367",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000421",
    "child" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "id" : "4000000000367"
    }
  }, {
    "parent" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "On Hold", "Escalated", "Closed", "Closed1", "newDeptClosed", "julyDeptClosed", "Open_july", "Open_newDept" ],
      "id" : "4000000000367"
    },
    "mappings" : {
      "newDeptClosed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open_july" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Escalated" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open_newDept" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "On Hold" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Closed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Closed1" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "julyDeptClosed" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "Open" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ]
    },
    "id" : "4000000032003",
    "childId" : "4000000000409",
    "layoutId" : "4000000007177",
    "parentId" : "4000000000367",
    "child" : {
      "displayLabel" : "Mode",
      "allowedValues" : [ "Phone", "Email", "Web", "Twitter", "Facebook", "Chat", "Forums", "Feedback Widget" ],
      "id" : "4000000000409"
    }
  } ]
}

Get possible dependency mappings in a layout

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

Query Params

Param Name
Data Type
Description
layoutId

long

required

layout Id

GET /api/v1/availableDependencyMappings

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/availableDependencyMappings?layoutId=4000000007179
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "children" : [ {
    "displayLabel" : "Category",
    "allowedValues" : [ "-None-", "Call", "Meeting", "Demo" ],
    "id" : "4000000000145"
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ "Not Started", "Deferred", "In Progress", "Waiting on someone else", "Completed_july1", "Completed_newDept" ],
    "id" : "4000000000147"
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Highest", "Low", "Lowest", "Normal" ],
    "id" : "4000000000149"
  } ],
  "parents" : [ {
    "displayLabel" : "Category",
    "allowedValues" : [ "-None-", "Call", "Meeting", "Demo" ],
    "id" : "4000000000145"
  }, {
    "displayLabel" : "Status",
    "allowedValues" : [ "Not Started", "Deferred", "In Progress", "Waiting on someone else", "Completed_july1", "Completed_newDept" ],
    "id" : "4000000000147"
  }, {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Highest", "Low", "Lowest", "Normal" ],
    "id" : "4000000000149"
  } ]
}

Create dependency mapping

This API creates a dependency mapping between two fields.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
layoutId

long

required

ID of the layout in which the dependency is mapped

parentId

long

required

ID of the parent field

childId

long

required

ID of the child field

mappings

list

required

JSON object that shows the mapping configured

POST /api/v1/dependencyMappings

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/dependencyMappings
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "mappings" : {
    "General" : [ "Medium", "High" ],
    "Defects" : [ "Low" ]
  },
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421"
}'

Response Example

{
  "parent" : {
    "displayLabel" : "Category",
    "allowedValues" : [ "General", "Defects" ],
    "id" : "4000000000421"
  },
  "mappings" : {
    "General" : [ "High", "Medium" ],
    "Defects" : [ "Low" ]
  },
  "id" : "4000000047001",
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421",
  "child" : {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Medium", "Low" ],
    "id" : "4000000000407"
  }
}

Update dependency mapping

This API updates details of an existing dependency mapping.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
mappings

list

optional

a Json object which consist of elements which are inturn a json array

PATCH /api/v1/dependencyMappings/{dependencymapping_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/dependencyMappings/4000000047001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "mappings" : {
    "General" : [ "Medium", "Low" ],
    "Defects" : [ "Low", "Medium" ]
  }
}'

Response Example

{
  "parent" : {
    "displayLabel" : "Category",
    "allowedValues" : [ "General", "Defects" ],
    "id" : "4000000000421"
  },
  "mappings" : {
    "General" : [ "Medium", "Low" ],
    "Defects" : [ "Medium", "Low" ]
  },
  "id" : "4000000047001",
  "childId" : "4000000000407",
  "layoutId" : "4000000007177",
  "parentId" : "4000000000421",
  "child" : {
    "displayLabel" : "Priority",
    "allowedValues" : [ "High", "Medium", "Low" ],
    "id" : "4000000000407"
  }
}

Delete dependency mapping

This API deletes a dependency mapping from a layout.

Credit: 1 credit/call

DELETE /api/v1/dependencyMappings/{dependencymapping_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/dependencyMappings/4000000047001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

MailReplyAddress

MailReplyAddress refers to the email ID from which replies are sent to customers.

Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "techsupport@zylker.com",
  "isVerified" : true,
  "isSmtpEnabled" : true,
  "displayName" : "Tech",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : true,
  "isActive" : true,
  "smtpDetails" : {
    "password" : "lfijkrffr",
    "port" : "465",
    "host" : "smtp.zoho.com",
    "userName" : "techsupport@zylker.com",
    "connectionType" : "SSL"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000028003",
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}


Get details of a MailReplyAddress

This API fetches the details of a MailReplyAddress. 

Credit: 1 credit/call

GET /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress/4000000028003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "techsupport@zylker.com",
  "isVerified" : true,
  "isSmtpEnabled" : true,
  "displayName" : "Tech",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : true,
  "isActive" : true,
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "userName" : "techsupport@zylker.com",
    "connectionType" : "SSL"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000028003",
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}

List MailReplyAddresses

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

ID of the Department from which the addresses need to be queried.

isActive

boolean

optional

Key that returns if the mailReplyAddress is active or not

from

integer

optional

Index number, starting from which the mail addresses must be fetched

limit

integer

optional,
range : 1-100

Number of mail addresses to fetch

GET /api/v1/mailReplyAddress

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress?departmentId=4000000007043
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "support@zylker.com",
    "isVerified" : true,
    "isSmtpEnabled" : true,
    "displayName" : "Support",
    "departmentId" : "4000000007043",
    "isDepartmentDefault" : true,
    "isActive" : true,
    "smtpDetails" : {
      "port" : "465",
      "host" : "smtp.zoho.com",
      "userName" : "support@zylker.com",
      "connectionType" : "SSL"
    },
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000025003",
    "serviceProviderType" : "CustomSMTP"
  }, {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "market@zylker.com",
    "isVerified" : true,
    "isSmtpEnabled" : false,
    "displayName" : "Marketing",
    "departmentId" : "4000000007043",
    "isDepartmentDefault" : false,
    "isActive" : false,
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000026001",
    "serviceProviderType" : "ZohoSMTP"
  }, {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "techsupport@zylker.com",
    "isVerified" : true,
    "isSmtpEnabled" : true,
    "displayName" : "Tech",
    "departmentId" : "4000000007043",
    "isDepartmentDefault" : false,
    "isActive" : true,
    "smtpDetails" : {
      "port" : "465",
      "host" : "smtp.zoho.com",
      "userName" : "techsupport@zylker.com",
      "connectionType" : "SSL"
    },
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "Sam",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000028003",
    "serviceProviderType" : "CustomSMTP"
  } ]
}

Add MailReplyAddress

This API adds a MailReplyAddress to your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

required

ID of the department in which the MailReplyAddress must be configured

address

string

required,
max chars : 100

Email ID to add

displayName

string

required,
max chars : 100

Display name for the MailReplyAddress

isSmtpEnabled 
deprecated

boolean

optional

Key that enables or disables SMTP authentication for the MailReplyAddress

smtpDetails

JSONObject

optional

Details related to the SMTP authentication for the MailReplyAddress

serviceProviderType

string

optional,
max chars : 50

MailService Provider name

isDepartmentDefault

boolean

optional

Key specifying if this MailReplyAddress is the default reply-to address for the department

POST /api/v1/mailReplyAddress

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/mailReplyAddress
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "address" : "support@zylker.com",
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "password " : "lfijkrffr",
    "userName" : "support@zylker.com",
    "connectionType" : "SSL"
  },
  "isSmtpEnabled" : true,
  "displayName" : "My address",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : true,
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}'

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "support@zylker.com",
  "isVerified" : false,
  "displayName" : "My address",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : true,
  "isActive" : true,
  "url" : "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?prompt=select_account&access_type=offline&scope=https://outlook.office.com/IMAP.AccessAsUser.All+https://outlook.office.com/POP.AccessAsUser.All+https://outlook.office.com/SMTP.Send+https://outlook.office.com/User.Read+https://outlook.office.com/Mail.ReadWrite.Shared+offline_access&response_type=code&redirect_uri=https://mail.zoho.com/api/accounts/Outlook/v2/redirect&state=dA700Cyn67320K8B8Ld0yRt9P3wc20Lli677&client_id=c12b-b8d1-860624b&login_hint=infotech@zylker.com",
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "userName" : "support@zylker.com",
    "connectionType" : "SSL"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000028003",
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}

Update MailReplyAddress

This API updates details of an existing MailReplyAddress.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

optional

ID of the department(s) in which the MailReplyAddress is configured

displayName

string

optional,
max chars : 100

Display Name

isActive

boolean

optional

Key that returns if the MailReplyAddress is active or not

isSmtpEnabled 
deprecated

boolean

optional

Is SMTP Enabled

serviceProviderType

string

optional,
max chars : 50

MailService Provider name

smtpDetails

JSONObject

optional

Details related to the SMTP authentication for the MailReplyAddress

isDepartmentDefault

boolean

optional

Key specifying if this MailReplyAddress is the default reply-to address for the department

PATCH /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "smtpDetails" : {
    "port" : "465",
    "host" : "smtp.zoho.com",
    "password " : "lfijk$&rffr**",
    "userName" : "techsupport@zylker.com",
    "connectionType" : "SSL"
  },
  "isSmtpEnabled" : true,
  "displayName" : "TechSupport",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : false,
  "isActive" : true,
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}'

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "techsupport@zylker.com",
  "isVerified" : true,
  "displayName" : "TechSupport",
  "departmentId" : "4000000007043",
  "isDepartmentDefault" : false,
  "isActive" : true,
  "url" : "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?prompt=select_account&access_type=offline&scope=https://outlook.office.com/IMAP.AccessAsUser.All+https://outlook.office.com/POP.AccessAsUser.All+https://outlook.office.com/SMTP.Send+https://outlook.office.com/User.Read+https://outlook.office.com/Mail.ReadWrite.Shared+offline_access&response_type=code&redirect_uri=https://mail.zoho.com/api/accounts/Outlook/v2/redirect&state=dA700Cyn67320K8B8Ld0yRt9P3wc20Lli677&client_id=c12b-b8d1-860624b&login_hint=infotech@zylker.com",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000028003",
  "serviceProviderType" : "ZohoSMTP|CustomSMTP"
}

Delete MailReplyAddress

This API deletes a MailReplyAddress from your help desk.

Credit: 1 credit/call

DELETE /api/v1/mailReplyAddress/{mailReplyAddress_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Send Verification Mail

This API sends a verification link to the MailReplyAddress configured in your help desk portal.

Credit: 1 credit/call

POST /api/v1/mailReplyAddress/{mailReplyAddress_id}/sendVerification

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/mailReplyAddress/4000000039003/sendVerification
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

SupportEmailAddress

SupportEmailAddress refers to the email ID to which customer correspondences are forwarded. 

Example

{
  "address" : "support@zylker.com",
  "departmentId" : "4000000007043",
  "id" : "4000000026003",
  "friendlyName" : "Tech",
  "isMailFetching" : true
}


Get details of a SupportEmailAddress

This API fetches the details of a SupportEmailAddress. 

Credit: 1 credit/call

GET /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailAddress/4000000026003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "support@zylker.com",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "departmentId" : "4000000007043",
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000026003",
  "friendlyName" : "Tech",
  "isMailFetching" : true
}

List SupportEmailAddresses

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

ID of the department(s) from which the SupportEmailAddresses must be fetched.

from

integer

optional

Index number, starting from which the mail addresses must be fetched

limit

integer

optional,
range : 1-100

Number of mail addresses to fetch

GET /api/v1/supportEmailAddress

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailAddress?departmentId=4000000007043
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "marketing@zylker.com",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "departmentId" : "4000000007043",
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000025003",
    "friendlyName" : "Marketing",
    "isMailFetching" : true
  }, {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "sales@zylker.com",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "departmentId" : "4000000007043",
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000026001",
    "friendlyName" : "Sales",
    "isMailFetching" : false
  }, {
    "modifiedTime" : "2023-01-06T11:55:26.000Z",
    "address" : "support@zylker.com",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "departmentId" : "4000000007043",
    "createdTime" : "2023-01-06T09:55:26.000Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
      "firstName" : "",
      "lastName" : "Steve",
      "id" : "4000000028043",
      "email" : "steve@zylker.com"
    },
    "id" : "4000000026003",
    "friendlyName" : "Support",
    "isMailFetching" : true
  } ]
}

Add SupportEmailAddress

This API adds a SupportEmailAddress to your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

required

ID of the department in which the SupportEmailAddress must be configured

friendlyName

string

required,
max chars : 100

Display name for the SupportEmailAddress

address

string

required,
max chars : 100

Email ID to add

POST /api/v1/supportEmailAddress

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/supportEmailAddress
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "address" : "support@zylker.com",
  "departmentId" : "4000000007043",
  "friendlyName" : "Support"
}'

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "support@zylker.com",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "departmentId" : "4000000007043",
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000026003",
  "friendlyName" : "Support",
  "isMailFetching" : true
}

Update SupportEmailAddress

This API updates details of an existing SupportEmailAddress.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

optional

ID of the department in which the SupportEmailAddress is configured

friendlyName

string

optional,
max chars : 100

Display name for the SupportEmailAddress

isMailFetching

boolean

optional

Key that returns if the SupportEmailAddress fetches emails or not

PATCH /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/supportEmailAddress/4000000039003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "4000000007043",
  "friendlyName" : "TechSupport",
  "isMailFetching" : true
}'

Response Example

{
  "modifiedTime" : "2023-01-06T11:55:26.000Z",
  "address" : "support@zylker.com",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "departmentId" : "4000000007043",
  "createdTime" : "2023-01-06T09:55:26.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000028043/photo?orgId=11171343",
    "firstName" : "Sam",
    "lastName" : "Steve",
    "id" : "4000000028043",
    "email" : "steve@zylker.com"
  },
  "id" : "4000000026003",
  "friendlyName" : "TechSupport",
  "isMailFetching" : true
}

Delete SupportEmailAddress

This API deletes a SupportEmailAddress from your help desk.

Credit: 1 credit/call

DELETE /api/v1/supportEmailAddress/{supportEmailAddress_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/supportEmailAddress/4000000039003
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

MailConfigurations

MailConfiguration refers to the secondary configurations related to the email addresses in your help desk portal.

Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}


List department-level MailConfigurations

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

GET /api/v1/departments/{department_Id}/mailConfigurations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/departments/4000000007043/mailConfigurations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

List organization-level MailConfigurations

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

GET /api/v1/mailConfigurations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/mailConfigurations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

Update department-level MailConfigurations

This API updates the MailConfigurations set for a specific department.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
autoCCToMailbox

boolean

optional

Key that enables or disables auto CC of email replies to your 

createContactWithReplyTo

boolean

optional

Key that enables or disables creation of contacts from 'Reply To' email addresses

agentNameInTicketReply

boolean

optional

Key that enables or disables display of the agent's name in replies to customers

createTicketForOriginalSender

boolean

optional

Key that enables or disables creation of tickets on behalf of the sender while forwarding emails

privateThreadConfig

boolean

optional

Key that enables or disables private thread handling

PATCH /api/v1/departments/{department_Id}/mailConfigurations

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/departments/4000000007043/mailConfigurations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}'

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

Update organization-level MailConfigurations

This API updates the MailConfigurations set for the entire help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
autoCCToMailbox

boolean

optional

Key that enables or disables auto CC of email replies to your 

createContactWithReplyTo

boolean

optional

Key that enables or disables creation of contacts from 'Reply To' email addresses

agentNameInTicketReply

boolean

optional

Key that enables or disables display of the agent's name in replies to customers

createTicketForOriginalSender

boolean

optional

Key that enables or disables creation of tickets on behalf of the sender while forwarding emails

privateThreadConfig

boolean

optional

Key that enables or disables private thread handling

PATCH /api/v1/mailConfigurations

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/mailConfigurations
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}'

Response Example

{
  "privateThreadConfig" : true,
  "agentNameInTicketReply" : true,
  "createContactWithReplyTo" : false,
  "createTicketForOriginalSender" : true,
  "autoCCToMailbox" : true
}

SupportEmailDomain

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

{
  "updatedTime" : "2013-11-04T11:21:07.000Z",
  "updatedBy" : "4000000007089",
  "supportEmailDomain" : "zylker.zohodesk.com",
  "oldDomain" : "zylkernew.zohodesk.com"
}


Update SupportEmailAddress SubDomain

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

Attributes

Param Name
Data Type
Description
supportEmailDomain

string

optional,
max chars : 100

Name of the new email subdomain

PATCH /api/v1/supportEmailDomain

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/supportEmailDomain
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "supportEmailDomain" : "zylkernew"
}'

Response Example

{
  "updatedTime" : "2013-11-04T11:21:07.000Z",
  "updatedBy" : "4000000007089",
  "supportEmailDomain" : "zylkernew.zohodesk.com",
  "oldDomain" : "zylker.zohodesk.com"
}

Get SupportEmailAddress SubDomain

This API fetches the subdomain of the support email address.

Credit: 1 credit/call

GET /api/v1/supportEmailDomain

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/supportEmailDomain
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "updatedTime" : "2013-11-04T11:21:07.000Z",
  "updatedBy" : "4000000007089",
  "supportEmailDomain" : "zylkernew.zohodesk.com",
  "oldDomain" : "zylker.zohodesk.com"
}

Locales

These public APIs help access details of the countries,languages and time zones supported in Zoho Desk.

Example

{
  "languages" : {
    "English (United States)" : "en_US",
    "Japanese" : "ja_JP"
  },
  "countries" : {
    "Albanian" : "sq_AL",
    "Afghanistan" : "ps_AF"
  }
}


List all countries

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.

GET /api/v1/countries

OAuth Scope

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/countries
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "Puerto Rico",
    "currencySymbol" : "USD",
    "id" : "PR",
    "currencyCode" : "USD"
  }, {
    "name" : "Palestinian Territories",
    "currencySymbol" : "ILS",
    "id" : "PS",
    "currencyCode" : "ILS"
  }, {
    "name" : "Portugal",
    "currencySymbol" : "EUR",
    "id" : "PT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Palau",
    "currencySymbol" : "USD",
    "id" : "PW",
    "currencyCode" : "USD"
  }, {
    "name" : "Paraguay",
    "currencySymbol" : "PYG",
    "id" : "PY",
    "currencyCode" : "PYG"
  }, {
    "name" : "Qatar",
    "currencySymbol" : "QAR",
    "id" : "QA",
    "currencyCode" : "QAR"
  }, {
    "name" : "Andorra",
    "currencySymbol" : "EUR",
    "id" : "AD",
    "currencyCode" : "EUR"
  }, {
    "name" : "United Arab Emirates",
    "currencySymbol" : "AED",
    "id" : "AE",
    "currencyCode" : "AED"
  }, {
    "name" : "Afghanistan",
    "currencySymbol" : "AFN",
    "id" : "AF",
    "currencyCode" : "AFN"
  }, {
    "name" : "Antigua & Barbuda",
    "currencySymbol" : "XCD",
    "id" : "AG",
    "currencyCode" : "XCD"
  }, {
    "name" : "Anguilla",
    "currencySymbol" : "XCD",
    "id" : "AI",
    "currencyCode" : "XCD"
  }, {
    "name" : "Albania",
    "currencySymbol" : "ALL",
    "id" : "AL",
    "currencyCode" : "ALL"
  }, {
    "name" : "Armenia",
    "currencySymbol" : "AMD",
    "id" : "AM",
    "currencyCode" : "AMD"
  }, {
    "name" : "Netherlands Antilles",
    "currencySymbol" : "ANG",
    "id" : "AN",
    "currencyCode" : "ANG"
  }, {
    "name" : "Angola",
    "currencySymbol" : "AOA",
    "id" : "AO",
    "currencyCode" : "AOA"
  }, {
    "name" : "Antarctica",
    "currencySymbol" : "XXX",
    "id" : "AQ",
    "currencyCode" : "-"
  }, {
    "name" : "Argentina",
    "currencySymbol" : "ARS",
    "id" : "AR",
    "currencyCode" : "ARS"
  }, {
    "name" : "American Samoa",
    "currencySymbol" : "USD",
    "id" : "AS",
    "currencyCode" : "USD"
  }, {
    "name" : "Austria",
    "currencySymbol" : "EUR",
    "id" : "AT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Réunion",
    "currencySymbol" : "EUR",
    "id" : "RE",
    "currencyCode" : "EUR"
  }, {
    "name" : "Australia",
    "currencySymbol" : "$",
    "id" : "AU",
    "currencyCode" : "AUD"
  }, {
    "name" : "Aruba",
    "currencySymbol" : "AWG",
    "id" : "AW",
    "currencyCode" : "AWG"
  }, {
    "name" : "Åland Islands",
    "currencySymbol" : "EUR",
    "id" : "AX",
    "currencyCode" : "EUR"
  }, {
    "name" : "Azerbaijan",
    "currencySymbol" : "AZN",
    "id" : "AZ",
    "currencyCode" : "AZN"
  }, {
    "name" : "Romania",
    "currencySymbol" : "RON",
    "id" : "RO",
    "currencyCode" : "RON"
  }, {
    "name" : "Bosnia & Herzegovina",
    "currencySymbol" : "BAM",
    "id" : "BA",
    "currencyCode" : "BAM"
  }, {
    "name" : "Barbados",
    "currencySymbol" : "BBD",
    "id" : "BB",
    "currencyCode" : "BBD"
  }, {
    "name" : "Serbia",
    "currencySymbol" : "RSD",
    "id" : "RS",
    "currencyCode" : "RSD"
  }, {
    "name" : "Bangladesh",
    "currencySymbol" : "BDT",
    "id" : "BD",
    "currencyCode" : "BDT"
  }, {
    "name" : "Belgium",
    "currencySymbol" : "EUR",
    "id" : "BE",
    "currencyCode" : "EUR"
  }, {
    "name" : "Russia",
    "currencySymbol" : "RUB",
    "id" : "RU",
    "currencyCode" : "RUB"
  }, {
    "name" : "Burkina Faso",
    "currencySymbol" : "XOF",
    "id" : "BF",
    "currencyCode" : "XOF"
  }, {
    "name" : "Bulgaria",
    "currencySymbol" : "BGN",
    "id" : "BG",
    "currencyCode" : "BGN"
  }, {
    "name" : "Rwanda",
    "currencySymbol" : "RWF",
    "id" : "RW",
    "currencyCode" : "RWF"
  }, {
    "name" : "Bahrain",
    "currencySymbol" : "BHD",
    "id" : "BH",
    "currencyCode" : "BHD"
  }, {
    "name" : "Burundi",
    "currencySymbol" : "BIF",
    "id" : "BI",
    "currencyCode" : "BIF"
  }, {
    "name" : "Benin",
    "currencySymbol" : "XOF",
    "id" : "BJ",
    "currencyCode" : "XOF"
  }, {
    "name" : "St. Barthélemy",
    "currencySymbol" : "EUR",
    "id" : "BL",
    "currencyCode" : "EUR"
  }, {
    "name" : "Bermuda",
    "currencySymbol" : "BMD",
    "id" : "BM",
    "currencyCode" : "BMD"
  }, {
    "name" : "Brunei",
    "currencySymbol" : "BND",
    "id" : "BN",
    "currencyCode" : "BND"
  }, {
    "name" : "Bolivia",
    "currencySymbol" : "BOB",
    "id" : "BO",
    "currencyCode" : "BOB"
  }, {
    "name" : "Saudi Arabia",
    "currencySymbol" : "SAR",
    "id" : "SA",
    "currencyCode" : "SAR"
  }, {
    "name" : "Caribbean Netherlands",
    "currencySymbol" : "USD",
    "id" : "BQ",
    "currencyCode" : "USD"
  }, {
    "name" : "Solomon Islands",
    "currencySymbol" : "SBD",
    "id" : "SB",
    "currencyCode" : "SBD"
  }, {
    "name" : "Brazil",
    "currencySymbol" : "BRL",
    "id" : "BR",
    "currencyCode" : "BRL"
  }, {
    "name" : "Seychelles",
    "currencySymbol" : "SCR",
    "id" : "SC",
    "currencyCode" : "SCR"
  }, {
    "name" : "Bahamas",
    "currencySymbol" : "BSD",
    "id" : "BS",
    "currencyCode" : "BSD"
  }, {
    "name" : "Sudan",
    "currencySymbol" : "SDG",
    "id" : "SD",
    "currencyCode" : "SDG"
  }, {
    "name" : "Bhutan",
    "currencySymbol" : "BTN",
    "id" : "BT",
    "currencyCode" : "BTN"
  }, {
    "name" : "Sweden",
    "currencySymbol" : "SEK",
    "id" : "SE",
    "currencyCode" : "SEK"
  }, {
    "name" : "Bouvet Island",
    "currencySymbol" : "NOK",
    "id" : "BV",
    "currencyCode" : "NOK"
  }, {
    "name" : "Singapore",
    "currencySymbol" : "$",
    "id" : "SG",
    "currencyCode" : "SGD"
  }, {
    "name" : "Botswana",
    "currencySymbol" : "BWP",
    "id" : "BW",
    "currencyCode" : "BWP"
  }, {
    "name" : "St. Helena",
    "currencySymbol" : "SHP",
    "id" : "SH",
    "currencyCode" : "SHP"
  }, {
    "name" : "Slovenia",
    "currencySymbol" : "EUR",
    "id" : "SI",
    "currencyCode" : "EUR"
  }, {
    "name" : "Belarus",
    "currencySymbol" : "BYN",
    "id" : "BY",
    "currencyCode" : "BYN"
  }, {
    "name" : "Svalbard & Jan Mayen",
    "currencySymbol" : "NOK",
    "id" : "SJ",
    "currencyCode" : "NOK"
  }, {
    "name" : "Belize",
    "currencySymbol" : "BZD",
    "id" : "BZ",
    "currencyCode" : "BZD"
  }, {
    "name" : "Slovakia",
    "currencySymbol" : "EUR",
    "id" : "SK",
    "currencyCode" : "EUR"
  }, {
    "name" : "Sierra Leone",
    "currencySymbol" : "SLL",
    "id" : "SL",
    "currencyCode" : "SLL"
  }, {
    "name" : "San Marino",
    "currencySymbol" : "EUR",
    "id" : "SM",
    "currencyCode" : "EUR"
  }, {
    "name" : "Senegal",
    "currencySymbol" : "XOF",
    "id" : "SN",
    "currencyCode" : "XOF"
  }, {
    "name" : "Somalia",
    "currencySymbol" : "SOS",
    "id" : "SO",
    "currencyCode" : "SOS"
  }, {
    "name" : "Canada",
    "currencySymbol" : "$",
    "id" : "CA",
    "currencyCode" : "CAD"
  }, {
    "name" : "Suriname",
    "currencySymbol" : "SRD",
    "id" : "SR",
    "currencyCode" : "SRD"
  }, {
    "name" : "Cocos (Keeling) Islands",
    "currencySymbol" : "AUD",
    "id" : "CC",
    "currencyCode" : "AUD"
  }, {
    "name" : "South Sudan",
    "currencySymbol" : "SSP",
    "id" : "SS",
    "currencyCode" : "SSP"
  }, {
    "name" : "Congo - Kinshasa",
    "currencySymbol" : "CDF",
    "id" : "CD",
    "currencyCode" : "CDF"
  }, {
    "name" : "São Tomé & Príncipe",
    "currencySymbol" : "STN",
    "id" : "ST",
    "currencyCode" : "STN"
  }, {
    "name" : "Central African Republic",
    "currencySymbol" : "XAF",
    "id" : "CF",
    "currencyCode" : "XAF"
  }, {
    "name" : "El Salvador",
    "currencySymbol" : "SVC",
    "id" : "SV",
    "currencyCode" : "SVC"
  }, {
    "name" : "Congo - Brazzaville",
    "currencySymbol" : "XAF",
    "id" : "CG",
    "currencyCode" : "XAF"
  }, {
    "name" : "Switzerland",
    "currencySymbol" : "CHF",
    "id" : "CH",
    "currencyCode" : "CHF"
  }, {
    "name" : "Sint Maarten",
    "currencySymbol" : "ANG",
    "id" : "SX",
    "currencyCode" : "ANG"
  }, {
    "name" : "Côte d’Ivoire",
    "currencySymbol" : "XOF",
    "id" : "CI",
    "currencyCode" : "XOF"
  }, {
    "name" : "Syria",
    "currencySymbol" : "SYP",
    "id" : "SY",
    "currencyCode" : "SYP"
  }, {
    "name" : "Eswatini",
    "currencySymbol" : "SZL",
    "id" : "SZ",
    "currencyCode" : "SZL"
  }, {
    "name" : "Cook Islands",
    "currencySymbol" : "NZD",
    "id" : "CK",
    "currencyCode" : "NZD"
  }, {
    "name" : "Chile",
    "currencySymbol" : "CLP",
    "id" : "CL",
    "currencyCode" : "CLP"
  }, {
    "name" : "Cameroon",
    "currencySymbol" : "XAF",
    "id" : "CM",
    "currencyCode" : "XAF"
  }, {
    "name" : "China",
    "currencySymbol" : "CNY",
    "id" : "CN",
    "currencyCode" : "CNY"
  }, {
    "name" : "Colombia",
    "currencySymbol" : "COP",
    "id" : "CO",
    "currencyCode" : "COP"
  }, {
    "name" : "Costa Rica",
    "currencySymbol" : "CRC",
    "id" : "CR",
    "currencyCode" : "CRC"
  }, {
    "name" : "Turks & Caicos Islands",
    "currencySymbol" : "USD",
    "id" : "TC",
    "currencyCode" : "USD"
  }, {
    "name" : "Chad",
    "currencySymbol" : "XAF",
    "id" : "TD",
    "currencyCode" : "XAF"
  }, {
    "name" : "Cuba",
    "currencySymbol" : "CUP",
    "id" : "CU",
    "currencyCode" : "CUP"
  }, {
    "name" : "French Southern Territories",
    "currencySymbol" : "EUR",
    "id" : "TF",
    "currencyCode" : "EUR"
  }, {
    "name" : "Cape Verde",
    "currencySymbol" : "CVE",
    "id" : "CV",
    "currencyCode" : "CVE"
  }, {
    "name" : "Togo",
    "currencySymbol" : "XOF",
    "id" : "TG",
    "currencyCode" : "XOF"
  }, {
    "name" : "Curaçao",
    "currencySymbol" : "ANG",
    "id" : "CW",
    "currencyCode" : "ANG"
  }, {
    "name" : "Thailand",
    "currencySymbol" : "THB",
    "id" : "TH",
    "currencyCode" : "THB"
  }, {
    "name" : "Christmas Island",
    "currencySymbol" : "AUD",
    "id" : "CX",
    "currencyCode" : "AUD"
  }, {
    "name" : "Cyprus",
    "currencySymbol" : "EUR",
    "id" : "CY",
    "currencyCode" : "EUR"
  }, {
    "name" : "Tajikistan",
    "currencySymbol" : "TJS",
    "id" : "TJ",
    "currencyCode" : "TJS"
  }, {
    "name" : "Czechia",
    "currencySymbol" : "CZK",
    "id" : "CZ",
    "currencyCode" : "CZK"
  }, {
    "name" : "Tokelau",
    "currencySymbol" : "NZD",
    "id" : "TK",
    "currencyCode" : "NZD"
  }, {
    "name" : "Timor-Leste",
    "currencySymbol" : "USD",
    "id" : "TL",
    "currencyCode" : "USD"
  }, {
    "name" : "Turkmenistan",
    "currencySymbol" : "TMT",
    "id" : "TM",
    "currencyCode" : "TMT"
  }, {
    "name" : "Tunisia",
    "currencySymbol" : "TND",
    "id" : "TN",
    "currencyCode" : "TND"
  }, {
    "name" : "Tonga",
    "currencySymbol" : "TOP",
    "id" : "TO",
    "currencyCode" : "TOP"
  }, {
    "name" : "Turkey",
    "currencySymbol" : "TRY",
    "id" : "TR",
    "currencyCode" : "TRY"
  }, {
    "name" : "Trinidad & Tobago",
    "currencySymbol" : "TTD",
    "id" : "TT",
    "currencyCode" : "TTD"
  }, {
    "name" : "Germany",
    "currencySymbol" : "EUR",
    "id" : "DE",
    "currencyCode" : "EUR"
  }, {
    "name" : "Tuvalu",
    "currencySymbol" : "AUD",
    "id" : "TV",
    "currencyCode" : "AUD"
  }, {
    "name" : "Taiwan",
    "currencySymbol" : "TWD",
    "id" : "TW",
    "currencyCode" : "TWD"
  }, {
    "name" : "Djibouti",
    "currencySymbol" : "DJF",
    "id" : "DJ",
    "currencyCode" : "DJF"
  }, {
    "name" : "Tanzania",
    "currencySymbol" : "TZS",
    "id" : "TZ",
    "currencyCode" : "TZS"
  }, {
    "name" : "Denmark",
    "currencySymbol" : "DKK",
    "id" : "DK",
    "currencyCode" : "DKK"
  }, {
    "name" : "Dominica",
    "currencySymbol" : "XCD",
    "id" : "DM",
    "currencyCode" : "XCD"
  }, {
    "name" : "Dominican Republic",
    "currencySymbol" : "DOP",
    "id" : "DO",
    "currencyCode" : "DOP"
  }, {
    "name" : "Ukraine",
    "currencySymbol" : "UAH",
    "id" : "UA",
    "currencyCode" : "UAH"
  }, {
    "name" : "Uganda",
    "currencySymbol" : "UGX",
    "id" : "UG",
    "currencyCode" : "UGX"
  }, {
    "name" : "Algeria",
    "currencySymbol" : "DZD",
    "id" : "DZ",
    "currencyCode" : "DZD"
  }, {
    "name" : "U.S. Outlying Islands",
    "currencySymbol" : "USD",
    "id" : "UM",
    "currencyCode" : "USD"
  }, {
    "name" : "Ecuador",
    "currencySymbol" : "USD",
    "id" : "EC",
    "currencyCode" : "USD"
  }, {
    "name" : "United States",
    "currencySymbol" : "$",
    "id" : "US",
    "currencyCode" : "USD"
  }, {
    "name" : "Estonia",
    "currencySymbol" : "EUR",
    "id" : "EE",
    "currencyCode" : "EUR"
  }, {
    "name" : "Egypt",
    "currencySymbol" : "EGP",
    "id" : "EG",
    "currencyCode" : "EGP"
  }, {
    "name" : "Western Sahara",
    "currencySymbol" : "MAD",
    "id" : "EH",
    "currencyCode" : "MAD"
  }, {
    "name" : "Uruguay",
    "currencySymbol" : "UYU",
    "id" : "UY",
    "currencyCode" : "UYU"
  }, {
    "name" : "Uzbekistan",
    "currencySymbol" : "UZS",
    "id" : "UZ",
    "currencyCode" : "UZS"
  }, {
    "name" : "Vatican City",
    "currencySymbol" : "EUR",
    "id" : "VA",
    "currencyCode" : "EUR"
  }, {
    "name" : "Eritrea",
    "currencySymbol" : "ERN",
    "id" : "ER",
    "currencyCode" : "ERN"
  }, {
    "name" : "St. Vincent & Grenadines",
    "currencySymbol" : "XCD",
    "id" : "VC",
    "currencyCode" : "XCD"
  }, {
    "name" : "Spain",
    "currencySymbol" : "EUR",
    "id" : "ES",
    "currencyCode" : "EUR"
  }, {
    "name" : "Ethiopia",
    "currencySymbol" : "ETB",
    "id" : "ET",
    "currencyCode" : "ETB"
  }, {
    "name" : "Venezuela",
    "currencySymbol" : "VES",
    "id" : "VE",
    "currencyCode" : "VES"
  }, {
    "name" : "British Virgin Islands",
    "currencySymbol" : "USD",
    "id" : "VG",
    "currencyCode" : "USD"
  }, {
    "name" : "U.S. Virgin Islands",
    "currencySymbol" : "USD",
    "id" : "VI",
    "currencyCode" : "USD"
  }, {
    "name" : "Vietnam",
    "currencySymbol" : "VND",
    "id" : "VN",
    "currencyCode" : "VND"
  }, {
    "name" : "Vanuatu",
    "currencySymbol" : "VUV",
    "id" : "VU",
    "currencyCode" : "VUV"
  }, {
    "name" : "Finland",
    "currencySymbol" : "EUR",
    "id" : "FI",
    "currencyCode" : "EUR"
  }, {
    "name" : "Fiji",
    "currencySymbol" : "FJD",
    "id" : "FJ",
    "currencyCode" : "FJD"
  }, {
    "name" : "Falkland Islands",
    "currencySymbol" : "FKP",
    "id" : "FK",
    "currencyCode" : "FKP"
  }, {
    "name" : "Micronesia",
    "currencySymbol" : "USD",
    "id" : "FM",
    "currencyCode" : "USD"
  }, {
    "name" : "Faroe Islands",
    "currencySymbol" : "DKK",
    "id" : "FO",
    "currencyCode" : "DKK"
  }, {
    "name" : "France",
    "currencySymbol" : "EUR",
    "id" : "FR",
    "currencyCode" : "EUR"
  }, {
    "name" : "Wallis & Futuna",
    "currencySymbol" : "XPF",
    "id" : "WF",
    "currencyCode" : "XPF"
  }, {
    "name" : "Gabon",
    "currencySymbol" : "XAF",
    "id" : "GA",
    "currencyCode" : "XAF"
  }, {
    "name" : "United Kingdom",
    "currencySymbol" : "£",
    "id" : "GB",
    "currencyCode" : "GBP"
  }, {
    "name" : "Samoa",
    "currencySymbol" : "WST",
    "id" : "WS",
    "currencyCode" : "WST"
  }, {
    "name" : "Grenada",
    "currencySymbol" : "XCD",
    "id" : "GD",
    "currencyCode" : "XCD"
  }, {
    "name" : "Georgia",
    "currencySymbol" : "GEL",
    "id" : "GE",
    "currencyCode" : "GEL"
  }, {
    "name" : "French Guiana",
    "currencySymbol" : "EUR",
    "id" : "GF",
    "currencyCode" : "EUR"
  }, {
    "name" : "Guernsey",
    "currencySymbol" : "GBP",
    "id" : "GG",
    "currencyCode" : "GBP"
  }, {
    "name" : "Ghana",
    "currencySymbol" : "GHS",
    "id" : "GH",
    "currencyCode" : "GHS"
  }, {
    "name" : "Gibraltar",
    "currencySymbol" : "GIP",
    "id" : "GI",
    "currencyCode" : "GIP"
  }, {
    "name" : "Greenland",
    "currencySymbol" : "DKK",
    "id" : "GL",
    "currencyCode" : "DKK"
  }, {
    "name" : "Gambia",
    "currencySymbol" : "GMD",
    "id" : "GM",
    "currencyCode" : "GMD"
  }, {
    "name" : "Guinea",
    "currencySymbol" : "GNF",
    "id" : "GN",
    "currencyCode" : "GNF"
  }, {
    "name" : "Guadeloupe",
    "currencySymbol" : "EUR",
    "id" : "GP",
    "currencyCode" : "EUR"
  }, {
    "name" : "Equatorial Guinea",
    "currencySymbol" : "XAF",
    "id" : "GQ",
    "currencyCode" : "XAF"
  }, {
    "name" : "Greece",
    "currencySymbol" : "EUR",
    "id" : "GR",
    "currencyCode" : "EUR"
  }, {
    "name" : "South Georgia & South Sandwich Islands",
    "currencySymbol" : "GBP",
    "id" : "GS",
    "currencyCode" : "GBP"
  }, {
    "name" : "Guatemala",
    "currencySymbol" : "GTQ",
    "id" : "GT",
    "currencyCode" : "GTQ"
  }, {
    "name" : "Guam",
    "currencySymbol" : "USD",
    "id" : "GU",
    "currencyCode" : "USD"
  }, {
    "name" : "Guinea-Bissau",
    "currencySymbol" : "XOF",
    "id" : "GW",
    "currencyCode" : "XOF"
  }, {
    "name" : "Guyana",
    "currencySymbol" : "GYD",
    "id" : "GY",
    "currencyCode" : "GYD"
  }, {
    "name" : "Kosovo",
    "currencySymbol" : "XXX",
    "id" : "XK",
    "currencyCode" : "-"
  }, {
    "name" : "Hong Kong SAR China",
    "currencySymbol" : "HKD",
    "id" : "HK",
    "currencyCode" : "HKD"
  }, {
    "name" : "Heard & McDonald Islands",
    "currencySymbol" : "AUD",
    "id" : "HM",
    "currencyCode" : "AUD"
  }, {
    "name" : "Honduras",
    "currencySymbol" : "HNL",
    "id" : "HN",
    "currencyCode" : "HNL"
  }, {
    "name" : "Croatia",
    "currencySymbol" : "HRK",
    "id" : "HR",
    "currencyCode" : "HRK"
  }, {
    "name" : "Haiti",
    "currencySymbol" : "HTG",
    "id" : "HT",
    "currencyCode" : "HTG"
  }, {
    "name" : "Yemen",
    "currencySymbol" : "YER",
    "id" : "YE",
    "currencyCode" : "YER"
  }, {
    "name" : "Hungary",
    "currencySymbol" : "HUF",
    "id" : "HU",
    "currencyCode" : "HUF"
  }, {
    "name" : "Indonesia",
    "currencySymbol" : "IDR",
    "id" : "ID",
    "currencyCode" : "IDR"
  }, {
    "name" : "Mayotte",
    "currencySymbol" : "EUR",
    "id" : "YT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Ireland",
    "currencySymbol" : "€",
    "id" : "IE",
    "currencyCode" : "EUR"
  }, {
    "name" : "Israel",
    "currencySymbol" : "ILS",
    "id" : "IL",
    "currencyCode" : "ILS"
  }, {
    "name" : "Isle of Man",
    "currencySymbol" : "GBP",
    "id" : "IM",
    "currencyCode" : "GBP"
  }, {
    "name" : "India",
    "currencySymbol" : "Rs.",
    "id" : "IN",
    "currencyCode" : "INR"
  }, {
    "name" : "British Indian Ocean Territory",
    "currencySymbol" : "USD",
    "id" : "IO",
    "currencyCode" : "USD"
  }, {
    "name" : "South Africa",
    "currencySymbol" : "R",
    "id" : "ZA",
    "currencyCode" : "ZAR"
  }, {
    "name" : "Iraq",
    "currencySymbol" : "IQD",
    "id" : "IQ",
    "currencyCode" : "IQD"
  }, {
    "name" : "Iran",
    "currencySymbol" : "IRR",
    "id" : "IR",
    "currencyCode" : "IRR"
  }, {
    "name" : "Iceland",
    "currencySymbol" : "ISK",
    "id" : "IS",
    "currencyCode" : "ISK"
  }, {
    "name" : "Italy",
    "currencySymbol" : "EUR",
    "id" : "IT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Zambia",
    "currencySymbol" : "ZMW",
    "id" : "ZM",
    "currencyCode" : "ZMW"
  }, {
    "name" : "Jersey",
    "currencySymbol" : "GBP",
    "id" : "JE",
    "currencyCode" : "GBP"
  }, {
    "name" : "Zimbabwe",
    "currencySymbol" : "ZWL",
    "id" : "ZW",
    "currencyCode" : "ZWL"
  }, {
    "name" : "Jamaica",
    "currencySymbol" : "JMD",
    "id" : "JM",
    "currencyCode" : "JMD"
  }, {
    "name" : "Jordan",
    "currencySymbol" : "JOD",
    "id" : "JO",
    "currencyCode" : "JOD"
  }, {
    "name" : "Japan",
    "currencySymbol" : "JPY",
    "id" : "JP",
    "currencyCode" : "JPY"
  }, {
    "name" : "Kenya",
    "currencySymbol" : "KES",
    "id" : "KE",
    "currencyCode" : "KES"
  }, {
    "name" : "Kyrgyzstan",
    "currencySymbol" : "KGS",
    "id" : "KG",
    "currencyCode" : "KGS"
  }, {
    "name" : "Cambodia",
    "currencySymbol" : "KHR",
    "id" : "KH",
    "currencyCode" : "KHR"
  }, {
    "name" : "Kiribati",
    "currencySymbol" : "AUD",
    "id" : "KI",
    "currencyCode" : "AUD"
  }, {
    "name" : "Comoros",
    "currencySymbol" : "KMF",
    "id" : "KM",
    "currencyCode" : "KMF"
  }, {
    "name" : "St. Kitts & Nevis",
    "currencySymbol" : "XCD",
    "id" : "KN",
    "currencyCode" : "XCD"
  }, {
    "name" : "North Korea",
    "currencySymbol" : "KPW",
    "id" : "KP",
    "currencyCode" : "KPW"
  }, {
    "name" : "South Korea",
    "currencySymbol" : "KRW",
    "id" : "KR",
    "currencyCode" : "KRW"
  }, {
    "name" : "Kuwait",
    "currencySymbol" : "KWD",
    "id" : "KW",
    "currencyCode" : "KWD"
  }, {
    "name" : "Cayman Islands",
    "currencySymbol" : "KYD",
    "id" : "KY",
    "currencyCode" : "KYD"
  }, {
    "name" : "Kazakhstan",
    "currencySymbol" : "KZT",
    "id" : "KZ",
    "currencyCode" : "KZT"
  }, {
    "name" : "Laos",
    "currencySymbol" : "LAK",
    "id" : "LA",
    "currencyCode" : "LAK"
  }, {
    "name" : "Lebanon",
    "currencySymbol" : "LBP",
    "id" : "LB",
    "currencyCode" : "LBP"
  }, {
    "name" : "St. Lucia",
    "currencySymbol" : "XCD",
    "id" : "LC",
    "currencyCode" : "XCD"
  }, {
    "name" : "Liechtenstein",
    "currencySymbol" : "CHF",
    "id" : "LI",
    "currencyCode" : "CHF"
  }, {
    "name" : "Sri Lanka",
    "currencySymbol" : "LKR",
    "id" : "LK",
    "currencyCode" : "LKR"
  }, {
    "name" : "Liberia",
    "currencySymbol" : "LRD",
    "id" : "LR",
    "currencyCode" : "LRD"
  }, {
    "name" : "Lesotho",
    "currencySymbol" : "LSL",
    "id" : "LS",
    "currencyCode" : "LSL"
  }, {
    "name" : "Lithuania",
    "currencySymbol" : "EUR",
    "id" : "LT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Luxembourg",
    "currencySymbol" : "EUR",
    "id" : "LU",
    "currencyCode" : "EUR"
  }, {
    "name" : "Latvia",
    "currencySymbol" : "EUR",
    "id" : "LV",
    "currencyCode" : "EUR"
  }, {
    "name" : "Libya",
    "currencySymbol" : "LYD",
    "id" : "LY",
    "currencyCode" : "LYD"
  }, {
    "name" : "Morocco",
    "currencySymbol" : "MAD",
    "id" : "MA",
    "currencyCode" : "MAD"
  }, {
    "name" : "Monaco",
    "currencySymbol" : "EUR",
    "id" : "MC",
    "currencyCode" : "EUR"
  }, {
    "name" : "Moldova",
    "currencySymbol" : "MDL",
    "id" : "MD",
    "currencyCode" : "MDL"
  }, {
    "name" : "Montenegro",
    "currencySymbol" : "EUR",
    "id" : "ME",
    "currencyCode" : "EUR"
  }, {
    "name" : "St. Martin",
    "currencySymbol" : "EUR",
    "id" : "MF",
    "currencyCode" : "EUR"
  }, {
    "name" : "Madagascar",
    "currencySymbol" : "MGA",
    "id" : "MG",
    "currencyCode" : "MGA"
  }, {
    "name" : "Marshall Islands",
    "currencySymbol" : "USD",
    "id" : "MH",
    "currencyCode" : "USD"
  }, {
    "name" : "North Macedonia",
    "currencySymbol" : "MKD",
    "id" : "MK",
    "currencyCode" : "MKD"
  }, {
    "name" : "Mali",
    "currencySymbol" : "XOF",
    "id" : "ML",
    "currencyCode" : "XOF"
  }, {
    "name" : "Myanmar (Burma)",
    "currencySymbol" : "MMK",
    "id" : "MM",
    "currencyCode" : "MMK"
  }, {
    "name" : "Mongolia",
    "currencySymbol" : "MNT",
    "id" : "MN",
    "currencyCode" : "MNT"
  }, {
    "name" : "Macao SAR China",
    "currencySymbol" : "MOP",
    "id" : "MO",
    "currencyCode" : "MOP"
  }, {
    "name" : "Northern Mariana Islands",
    "currencySymbol" : "USD",
    "id" : "MP",
    "currencyCode" : "USD"
  }, {
    "name" : "Martinique",
    "currencySymbol" : "EUR",
    "id" : "MQ",
    "currencyCode" : "EUR"
  }, {
    "name" : "Mauritania",
    "currencySymbol" : "MRU",
    "id" : "MR",
    "currencyCode" : "MRU"
  }, {
    "name" : "Montserrat",
    "currencySymbol" : "XCD",
    "id" : "MS",
    "currencyCode" : "XCD"
  }, {
    "name" : "Malta",
    "currencySymbol" : "€",
    "id" : "MT",
    "currencyCode" : "EUR"
  }, {
    "name" : "Mauritius",
    "currencySymbol" : "MUR",
    "id" : "MU",
    "currencyCode" : "MUR"
  }, {
    "name" : "Maldives",
    "currencySymbol" : "MVR",
    "id" : "MV",
    "currencyCode" : "MVR"
  }, {
    "name" : "Malawi",
    "currencySymbol" : "MWK",
    "id" : "MW",
    "currencyCode" : "MWK"
  }, {
    "name" : "Mexico",
    "currencySymbol" : "MXN",
    "id" : "MX",
    "currencyCode" : "MXN"
  }, {
    "name" : "Malaysia",
    "currencySymbol" : "MYR",
    "id" : "MY",
    "currencyCode" : "MYR"
  }, {
    "name" : "Mozambique",
    "currencySymbol" : "MZN",
    "id" : "MZ",
    "currencyCode" : "MZN"
  }, {
    "name" : "Namibia",
    "currencySymbol" : "NAD",
    "id" : "NA",
    "currencyCode" : "NAD"
  }, {
    "name" : "New Caledonia",
    "currencySymbol" : "XPF",
    "id" : "NC",
    "currencyCode" : "XPF"
  }, {
    "name" : "Niger",
    "currencySymbol" : "XOF",
    "id" : "NE",
    "currencyCode" : "XOF"
  }, {
    "name" : "Norfolk Island",
    "currencySymbol" : "AUD",
    "id" : "NF",
    "currencyCode" : "AUD"
  }, {
    "name" : "Nigeria",
    "currencySymbol" : "NGN",
    "id" : "NG",
    "currencyCode" : "NGN"
  }, {
    "name" : "Nicaragua",
    "currencySymbol" : "NIO",
    "id" : "NI",
    "currencyCode" : "NIO"
  }, {
    "name" : "Netherlands",
    "currencySymbol" : "EUR",
    "id" : "NL",
    "currencyCode" : "EUR"
  }, {
    "name" : "Norway",
    "currencySymbol" : "NOK",
    "id" : "NO",
    "currencyCode" : "NOK"
  }, {
    "name" : "Nepal",
    "currencySymbol" : "NPR",
    "id" : "NP",
    "currencyCode" : "NPR"
  }, {
    "name" : "Nauru",
    "currencySymbol" : "AUD",
    "id" : "NR",
    "currencyCode" : "AUD"
  }, {
    "name" : "Niue",
    "currencySymbol" : "NZD",
    "id" : "NU",
    "currencyCode" : "NZD"
  }, {
    "name" : "New Zealand",
    "currencySymbol" : "$",
    "id" : "NZ",
    "currencyCode" : "NZD"
  }, {
    "name" : "Oman",
    "currencySymbol" : "OMR",
    "id" : "OM",
    "currencyCode" : "OMR"
  }, {
    "name" : "Panama",
    "currencySymbol" : "PAB",
    "id" : "PA",
    "currencyCode" : "PAB"
  }, {
    "name" : "Peru",
    "currencySymbol" : "PEN",
    "id" : "PE",
    "currencyCode" : "PEN"
  }, {
    "name" : "French Polynesia",
    "currencySymbol" : "XPF",
    "id" : "PF",
    "currencyCode" : "XPF"
  }, {
    "name" : "Papua New Guinea",
    "currencySymbol" : "PGK",
    "id" : "PG",
    "currencyCode" : "PGK"
  }, {
    "name" : "Philippines",
    "currencySymbol" : "Php",
    "id" : "PH",
    "currencyCode" : "PHP"
  }, {
    "name" : "Pakistan",
    "currencySymbol" : "PKR",
    "id" : "PK",
    "currencyCode" : "PKR"
  }, {
    "name" : "Poland",
    "currencySymbol" : "PLN",
    "id" : "PL",
    "currencyCode" : "PLN"
  }, {
    "name" : "St. Pierre & Miquelon",
    "currencySymbol" : "EUR",
    "id" : "PM",
    "currencyCode" : "EUR"
  }, {
    "name" : "Pitcairn Islands",
    "currencySymbol" : "NZD",
    "id" : "PN",
    "currencyCode" : "NZD"
  } ],
  "countries" : {
    "Papua New Guinea" : "en_PG",
    "Cambodia" : "km_KH",
    "Kazakhstan" : "ru_KZ",
    "Paraguay" : "es_PY",
    "Syria" : "ar_SY",
    "Bahamas" : "en_BS",
    "Solomon Islands" : "en_SB",
    "Montserrat" : "en_MS",
    "Mali" : "fr_ML",
    "Marshall Islands" : "en_MH",
    "Guadeloupe" : "fr_GP",
    "Panama" : "es_PA",
    "Laos" : "lo_LA",
    "Vatican" : "it_VA",
    "Argentina" : "es_AR",
    "Falkland Islands" : "en_FK",
    "Virgin Islands" : "en_VI",
    "Seychelles" : "en_SC",
    "Belize" : "en_BZ",
    "Zambia" : "en_ZM",
    "Bahrain" : "ar_BH",
    "Congo" : "fr_CG",
    "Namibia" : "en_NA",
    "Comoros" : "fr_KM",
    "Faroe Islands" : "fo_FO",
    "Finland" : "fi_FI",
    "Netherlands Antilles" : "nl_AN",
    "Georgia" : "ka_GE",
    "Yemen" : "ar_YE",
    "Eritrea" : "en_ER",
    "Puerto Rico" : "es_PR",
    "Aruba" : "nl_AW",
    "Madagascar" : "en_MG",
    "Libya" : "ar_LY",
    "Sweden" : "sv_SE",
    "Malawi" : "en_MW",
    "Andorra" : "ca_AD",
    "Liechtenstein" : "de_LI",
    "Algerian" : "ar_DZ",
    "Poland" : "pl_PL",
    "Bulgaria" : "bg_BG",
    "Jordan" : "ar_JO",
    "Tunisia" : "ar_TN",
    "Tuvalu" : "en_TV",
    "United Arab Emirates" : "ar_AE",
    "Kenya" : "sw_KE",
    "French Polynesia" : "fr_PF",
    "Brunei" : "ms_BN",
    "Djibouti" : "ar_DJ",
    "Lebanon" : "ar_LB",
    "Azerbaijan" : "az_AZ",
    "Cuba" : "es_CU",
    "Czech Republic" : "cs_CZ",
    "Mauritania" : "ar_MR",
    "Saint Lucia" : "en_LC",
    "Mayotte" : "fr_YT",
    "Israel" : "iw_IL",
    "San Marino" : "it_SM",
    "Australia" : "en_AU",
    "Tajikistan" : "fa_TJ",
    "Myanmar" : "my_MM",
    "Cameroon" : "fr_CM",
    "Gibraltar" : "en_GI",
    "Cyprus" : "el_CY",
    "Northern Mariana Islands" : "en_MP",
    "Malaysia" : "ms_MY",
    "BelgiumFrench" : "fr_BE",
    "dIvoire" : "fr_CI",
    "Iceland" : "is_IS",
    "Oman" : "ar_OM",
    "Armenia" : "hy_AM",
    "Gabon" : "fr_GA",
    "CanadaFrench" : "fr_CA",
    "Brazil" : "pt_BR",
    "Slovenia" : "sl_SI",
    "LuxembourgFrench" : "fr_LU",
    "Antigua and Barbuda" : "en_AG",
    "Colombia" : "es_CO",
    "Ecuador" : "es_EC",
    "Moldova" : "ro_MD",
    "Vanuatu" : "bi_VU",
    "United States Minor Outlying Islands" : "en_UM",
    "Cocos Islands" : "en_CC",
    "Honduras" : "es_HN",
    "Italy" : "it_IT",
    "Antarctica" : "en_AQ",
    "Nauru" : "en_NR",
    "SwitzerlandFrench" : "fr_CH",
    "Haiti" : "fr_HT",
    "Afghanistan" : "ps_AF",
    "Burundi" : "fr_BI",
    "CanadaEnglish" : "en_CA",
    "Singapore" : "en_SG",
    "French Guiana" : "fr_GF",
    "GuineaBissau" : "pt_GW",
    "American Samoa" : "en_AS",
    "Christmas Island" : "en_CX",
    "Russia" : "ru_RU",
    "Netherlands" : "nl_NL",
    "China" : "zh_CN",
    "Martinique" : "fr_MQ",
    "The Democratic Republic Of Congo" : "fr_CD",
    "Kyrgyzstan" : "uz_KG",
    "Wallis And Futuna" : "fr_WF",
    "Reunion" : "fr_RE",
    "Saint Pierre And Miquelon" : "fr_PM",
    "Bhutan" : "en_BT",
    "Romania" : "ro_RO",
    "Togo" : "fr_TG",
    "Philippines" : "en_PH",
    "Uzbekistan" : "uz_UZ",
    "Pitcairn" : "en_PN",
    "British Virgin Islands" : "en_VG",
    "Zimbabwe" : "en_ZW",
    "British Indian Ocean Territory" : "en_IO",
    "Dominica" : "en_DM",
    "Indonesia" : "id_ID",
    "Benin" : "fr_BJ",
    "Angola" : "pt_AO",
    "Sudan" : "ar_SD",
    "Portugal" : "pt_PT",
    "New Caledonia" : "fr_NC",
    "Grenada" : "en_GD",
    "North Korea" : "ko_KP",
    "Cayman Islands" : "en_KY",
    "Greece" : "el_GR",
    "Latvia" : "lv_LV",
    "Mongolia" : "mn_MN",
    "Iran" : "fa_IR",
    "Morocco" : "ar_MA",
    "Guatemala" : "es_GT",
    "Guyana" : "en_GY",
    "Iraq" : "ar_IQ",
    "Chile" : "es_CL",
    "Nepal" : "ne_NP",
    "SpainCatalan" : "ca_ES",
    "Tanzania" : "sw_TZ",
    "Ukraine" : "uk_UA",
    "Ghana" : "en_GH",
    "Anguilla" : "en_AI",
    "Saint Vincent And The Grenadines" : "en_VC",
    "SwitzerlandItalian" : "it_CH",
    "India" : "en_IN",
    "Maldives" : "dv_MV",
    "Turkey" : "tr_TR",
    "Taiwan" : "zh_TW",
    "South Africa" : "en_ZA",
    "Trinidad and Tobago" : "en_TT",
    "Bermuda" : "en_BM",
    "Central African Republic" : "fr_CF",
    "Jamaica" : "en_JM",
    "Peru" : "es_PE",
    "Turkmenistan" : "tk_TM",
    "Germany" : "de_DE",
    "Fiji" : "fj_FJ",
    "Tokelau" : "en_TK",
    "Hong Kong" : "zh_HK",
    "Guinea" : "fr_GN",
    "United States" : "en_US",
    "Chad" : "ar_TD",
    "Somalia" : "so_SO",
    "Thailand" : "th_TH",
    "Equatorial Guinea" : "es_GQ",
    "Kiribati" : "en_KI",
    "Costa Rica" : "es_CR",
    "Vietnam" : "vi_VN",
    "Kuwait" : "ar_KW",
    "Nigeria" : "en_NG",
    "Croatia" : "hr_HR",
    "Sao Tome And Principe" : "pt_ST",
    "Cook Islands" : "en_CK",
    "Sri Lanka" : "si_LK",
    "Uruguay" : "es_UY",
    "United Kingdom" : "en_GB",
    "Samoa" : "en_WS",
    "Palestine" : "ar_PS",
    "Liberia" : "en_LR",
    "Venezuela" : "es_VE",
    "Burkina Faso" : "fr_BF",
    "Swaziland" : "en_SZ",
    "Palau" : "en_PW",
    "Turks And Caicos Islands" : "en_TC",
    "Estonia" : "et_EE",
    "Niue" : "en_NU",
    "Heard Island And McDonald Islands" : "en_HM",
    "Svalbard And Jan Mayen" : "no_SJ",
    "BelgiumDutch" : "nl_BE",
    "SpainSpanish" : "es_ES",
    "Austria" : "de_AT",
    "South Korea" : "ko_KR",
    "Mozambique" : "pt_MZ",
    "El Salvador" : "es_SV",
    "Monaco" : "fr_MC",
    "Guam" : "en_GU",
    "Lesotho" : "en_LS",
    "Tonga" : "to_TO",
    "Western Sahara" : "ar_EH",
    "Hungary" : "hu_HU",
    "land Islands" : "sv_AX",
    "Japan" : "ja_JP",
    "Belarus" : "be_BY",
    "SwitzerlandGerman" : "de_CH",
    "Mauritius" : "en_MU",
    "Bouvet Island" : "no_BV",
    "Norfolk Island" : "en_NF",
    "New Zealand" : "en_NZ",
    "Senegal" : "fr_SN",
    "TimorLeste" : "pt_TL",
    "Macedonia" : "mk_MK",
    "Ethiopia" : "am_ET",
    "Egypt" : "ar_EG",
    "Sierra Leone" : "en_SL",
    "Bolivia" : "es_BO",
    "LuxembourgGerman" : "de_LU",
    "Malta" : "mt_MT",
    "Saudi Arabia" : "ar_SA",
    "Cape Verde" : "pt_CV",
    "South Georgia And The South Sandwich Islands" : "en_GS",
    "Pakistan" : "en_PK",
    "Kosovo" : "en_XK",
    "Gambia" : "en_GM",
    "Ireland" : "en_IE",
    "Qatar" : "ar_QA",
    "Serbia and Montenegro" : "sr_CS",
    "Slovakia" : "sk_SK",
    "France" : "fr_FR",
    "Lithuania" : "lt_LT",
    "Bosnia and Herzegovina" : "bs_BA",
    "Albanian" : "sq_AL",
    "Niger" : "fr_NE",
    "Rwanda" : "rw_RW",
    "Saint Kitts And Nevis" : "en_KN",
    "French Southern Territories" : "fr_TF",
    "Bangladesh" : "bn_BD",
    "Barbados" : "en_BB",
    "Nicaragua" : "es_NI",
    "Norway" : "no_NO",
    "Botswana" : "en_BW",
    "Macao" : "zh_MO",
    "Denmark" : "da_DK",
    "Dominican Republic" : "es_DO",
    "Mexico" : "es_MX",
    "Uganda" : "en_UG",
    "Micronesia" : "en_FM",
    "Suriname" : "nl_SR",
    "Greenland" : "kl_GL",
    "Saint Helena" : "en_SH"
  }
}

List all languages

This API lists the languages that are available for listing in Zoho Desk.

GET /api/v1/languages

OAuth Scope

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/languages
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "languages" : {
    "Italian" : "it_IT",
    "French" : "fr_FR",
    "Russian" : "ru_RU",
    "English (United States)" : "en_US",
    "Chinese" : "zh_CN",
    "Danish" : "da_DK",
    "Spanish" : "es_ES",
    "German" : "de_DE",
    "Japanese" : "ja_JP",
    "Dutch" : "nl_NL",
    "Turkish" : "tr_TR",
    "Portuguese (Brazil)" : "pt_BR"
  }
}

List all time zones

This API lists the time zones that are available for listing in Zoho Desk.

GET /api/v1/timeZones

OAuth Scope

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/timeZones
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Abidjan )",
    "id" : "Africa/Abidjan"
  }, {
    "name" : "( GMT 0:00 ) Ghana Mean Time( Africa/Accra )",
    "id" : "Africa/Accra"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Addis_Ababa )",
    "id" : "Africa/Addis_Ababa"
  }, {
    "name" : "( GMT 0:00 ) Central European Time( Africa/Algiers )",
    "id" : "Africa/Algiers"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Asmara )",
    "id" : "Africa/Asmara"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Asmera )",
    "id" : "Africa/Asmera"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Bamako )",
    "id" : "Africa/Bamako"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Bangui )",
    "id" : "Africa/Bangui"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Banjul )",
    "id" : "Africa/Banjul"
  }, {
    "name" : "( GMT -1:00 ) Greenwich Mean Time( Africa/Bissau )",
    "id" : "Africa/Bissau"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Blantyre )",
    "id" : "Africa/Blantyre"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Brazzaville )",
    "id" : "Africa/Brazzaville"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Bujumbura )",
    "id" : "Africa/Bujumbura"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Africa/Cairo )",
    "id" : "Africa/Cairo"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Africa/Casablanca )",
    "id" : "Africa/Casablanca"
  }, {
    "name" : "( GMT 0:00 ) Central European Summer Time( Africa/Ceuta )",
    "id" : "Africa/Ceuta"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Conakry )",
    "id" : "Africa/Conakry"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Dakar )",
    "id" : "Africa/Dakar"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Dar_es_Salaam )",
    "id" : "Africa/Dar_es_Salaam"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Djibouti )",
    "id" : "Africa/Djibouti"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Douala )",
    "id" : "Africa/Douala"
  }, {
    "name" : "( GMT -1:00 ) Western European Summer Time( Africa/El_Aaiun )",
    "id" : "Africa/El_Aaiun"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Freetown )",
    "id" : "Africa/Freetown"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Gaborone )",
    "id" : "Africa/Gaborone"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Harare )",
    "id" : "Africa/Harare"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Johannesburg )",
    "id" : "Africa/Johannesburg"
  }, {
    "name" : "( GMT 2:00 ) Eastern African Time( Africa/Juba )",
    "id" : "Africa/Juba"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Kampala )",
    "id" : "Africa/Kampala"
  }, {
    "name" : "( GMT 2:00 ) Eastern African Time( Africa/Khartoum )",
    "id" : "Africa/Khartoum"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Kigali )",
    "id" : "Africa/Kigali"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Kinshasa )",
    "id" : "Africa/Kinshasa"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Lagos )",
    "id" : "Africa/Lagos"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Libreville )",
    "id" : "Africa/Libreville"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Lome )",
    "id" : "Africa/Lome"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Luanda )",
    "id" : "Africa/Luanda"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Lubumbashi )",
    "id" : "Africa/Lubumbashi"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Lusaka )",
    "id" : "Africa/Lusaka"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Malabo )",
    "id" : "Africa/Malabo"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( Africa/Maputo )",
    "id" : "Africa/Maputo"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Maseru )",
    "id" : "Africa/Maseru"
  }, {
    "name" : "( GMT 2:00 ) South Africa Standard Time( Africa/Mbabane )",
    "id" : "Africa/Mbabane"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Mogadishu )",
    "id" : "Africa/Mogadishu"
  }, {
    "name" : "( GMT 0:44 ) Greenwich Mean Time( Africa/Monrovia )",
    "id" : "Africa/Monrovia"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Africa/Nairobi )",
    "id" : "Africa/Nairobi"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Ndjamena )",
    "id" : "Africa/Ndjamena"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Niamey )",
    "id" : "Africa/Niamey"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Nouakchott )",
    "id" : "Africa/Nouakchott"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Ouagadougou )",
    "id" : "Africa/Ouagadougou"
  }, {
    "name" : "( GMT 1:00 ) Western African Time( Africa/Porto-Novo )",
    "id" : "Africa/Porto-Novo"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Sao_Tome )",
    "id" : "Africa/Sao_Tome"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Africa/Timbuktu )",
    "id" : "Africa/Timbuktu"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Africa/Tripoli )",
    "id" : "Africa/Tripoli"
  }, {
    "name" : "( GMT 1:00 ) Central European Time( Africa/Tunis )",
    "id" : "Africa/Tunis"
  }, {
    "name" : "( GMT 2:00 ) Western African Summer Time( Africa/Windhoek )",
    "id" : "Africa/Windhoek"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( America/Adak )",
    "id" : "America/Adak"
  }, {
    "name" : "( GMT -10:00 ) Alaska Daylight Time( America/Anchorage )",
    "id" : "America/Anchorage"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Anguilla )",
    "id" : "America/Anguilla"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Antigua )",
    "id" : "America/Antigua"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Araguaina )",
    "id" : "America/Araguaina"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Buenos_Aires )",
    "id" : "America/Argentina/Buenos_Aires"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Catamarca )",
    "id" : "America/Argentina/Catamarca"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/ComodRivadavia )",
    "id" : "America/Argentina/ComodRivadavia"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Cordoba )",
    "id" : "America/Argentina/Cordoba"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Jujuy )",
    "id" : "America/Argentina/Jujuy"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/La_Rioja )",
    "id" : "America/Argentina/La_Rioja"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Mendoza )",
    "id" : "America/Argentina/Mendoza"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Rio_Gallegos )",
    "id" : "America/Argentina/Rio_Gallegos"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Salta )",
    "id" : "America/Argentina/Salta"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/San_Juan )",
    "id" : "America/Argentina/San_Juan"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/San_Luis )",
    "id" : "America/Argentina/San_Luis"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Tucuman )",
    "id" : "America/Argentina/Tucuman"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Argentina/Ushuaia )",
    "id" : "America/Argentina/Ushuaia"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Aruba )",
    "id" : "America/Aruba"
  }, {
    "name" : "( GMT -4:00 ) Paraguay Summer Time( America/Asuncion )",
    "id" : "America/Asuncion"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Atikokan )",
    "id" : "America/Atikokan"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( America/Atka )",
    "id" : "America/Atka"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Bahia )",
    "id" : "America/Bahia"
  }, {
    "name" : "( GMT -8:00 ) Central Daylight Time( America/Bahia_Banderas )",
    "id" : "America/Bahia_Banderas"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Barbados )",
    "id" : "America/Barbados"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Belem )",
    "id" : "America/Belem"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Belize )",
    "id" : "America/Belize"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Blanc-Sablon )",
    "id" : "America/Blanc-Sablon"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Boa_Vista )",
    "id" : "America/Boa_Vista"
  }, {
    "name" : "( GMT -5:00 ) Colombia Time( America/Bogota )",
    "id" : "America/Bogota"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Boise )",
    "id" : "America/Boise"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Buenos_Aires )",
    "id" : "America/Buenos_Aires"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Cambridge_Bay )",
    "id" : "America/Cambridge_Bay"
  }, {
    "name" : "( GMT -4:00 ) Amazon Summer Time( America/Campo_Grande )",
    "id" : "America/Campo_Grande"
  }, {
    "name" : "( GMT -6:00 ) Eastern Standard Time( America/Cancun )",
    "id" : "America/Cancun"
  }, {
    "name" : "( GMT -4:00 ) Venezuela Time( America/Caracas )",
    "id" : "America/Caracas"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Catamarca )",
    "id" : "America/Catamarca"
  }, {
    "name" : "( GMT -3:00 ) French Guiana Time( America/Cayenne )",
    "id" : "America/Cayenne"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Cayman )",
    "id" : "America/Cayman"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Chicago )",
    "id" : "America/Chicago"
  }, {
    "name" : "( GMT -6:00 ) Mountain Daylight Time( America/Chihuahua )",
    "id" : "America/Chihuahua"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Coral_Harbour )",
    "id" : "America/Coral_Harbour"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Cordoba )",
    "id" : "America/Cordoba"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Costa_Rica )",
    "id" : "America/Costa_Rica"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Creston )",
    "id" : "America/Creston"
  }, {
    "name" : "( GMT -4:00 ) Amazon Summer Time( America/Cuiaba )",
    "id" : "America/Cuiaba"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Curacao )",
    "id" : "America/Curacao"
  }, {
    "name" : "( GMT -3:00 ) Greenwich Mean Time( America/Danmarkshavn )",
    "id" : "America/Danmarkshavn"
  }, {
    "name" : "( GMT -9:00 ) Pacific Daylight Time( America/Dawson )",
    "id" : "America/Dawson"
  }, {
    "name" : "( GMT -8:00 ) Mountain Standard Time( America/Dawson_Creek )",
    "id" : "America/Dawson_Creek"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Denver )",
    "id" : "America/Denver"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Detroit )",
    "id" : "America/Detroit"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Dominica )",
    "id" : "America/Dominica"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Edmonton )",
    "id" : "America/Edmonton"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Eirunepe )",
    "id" : "America/Eirunepe"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/El_Salvador )",
    "id" : "America/El_Salvador"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Ensenada )",
    "id" : "America/Ensenada"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Fort_Nelson )",
    "id" : "America/Fort_Nelson"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Fort_Wayne )",
    "id" : "America/Fort_Wayne"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Fortaleza )",
    "id" : "America/Fortaleza"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Glace_Bay )",
    "id" : "America/Glace_Bay"
  }, {
    "name" : "( GMT -3:00 ) Western Greenland Summer Time( America/Godthab )",
    "id" : "America/Godthab"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Goose_Bay )",
    "id" : "America/Goose_Bay"
  }, {
    "name" : "( GMT -5:00 ) Atlantic Standard Time( America/Grand_Turk )",
    "id" : "America/Grand_Turk"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Grenada )",
    "id" : "America/Grenada"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Guadeloupe )",
    "id" : "America/Guadeloupe"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Guatemala )",
    "id" : "America/Guatemala"
  }, {
    "name" : "( GMT -5:00 ) Ecuador Time( America/Guayaquil )",
    "id" : "America/Guayaquil"
  }, {
    "name" : "( GMT -3:45 ) Guyana Time( America/Guyana )",
    "id" : "America/Guyana"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Halifax )",
    "id" : "America/Halifax"
  }, {
    "name" : "( GMT -5:00 ) Cuba Daylight Time( America/Havana )",
    "id" : "America/Havana"
  }, {
    "name" : "( GMT -8:00 ) Mountain Standard Time( America/Hermosillo )",
    "id" : "America/Hermosillo"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Indianapolis )",
    "id" : "America/Indiana/Indianapolis"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Indiana/Knox )",
    "id" : "America/Indiana/Knox"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Marengo )",
    "id" : "America/Indiana/Marengo"
  }, {
    "name" : "( GMT -6:00 ) Eastern Daylight Time( America/Indiana/Petersburg )",
    "id" : "America/Indiana/Petersburg"
  }, {
    "name" : "( GMT -5:00 ) Central Daylight Time( America/Indiana/Tell_City )",
    "id" : "America/Indiana/Tell_City"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Vevay )",
    "id" : "America/Indiana/Vevay"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Vincennes )",
    "id" : "America/Indiana/Vincennes"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indiana/Winamac )",
    "id" : "America/Indiana/Winamac"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Indianapolis )",
    "id" : "America/Indianapolis"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( America/Inuvik )",
    "id" : "America/Inuvik"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Iqaluit )",
    "id" : "America/Iqaluit"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Jamaica )",
    "id" : "America/Jamaica"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Jujuy )",
    "id" : "America/Jujuy"
  }, {
    "name" : "( GMT -8:00 ) Alaska Daylight Time( America/Juneau )",
    "id" : "America/Juneau"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Kentucky/Louisville )",
    "id" : "America/Kentucky/Louisville"
  }, {
    "name" : "( GMT -6:00 ) Eastern Daylight Time( America/Kentucky/Monticello )",
    "id" : "America/Kentucky/Monticello"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Knox_IN )",
    "id" : "America/Knox_IN"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Kralendijk )",
    "id" : "America/Kralendijk"
  }, {
    "name" : "( GMT -4:00 ) Bolivia Time( America/La_Paz )",
    "id" : "America/La_Paz"
  }, {
    "name" : "( GMT -5:00 ) Peru Time( America/Lima )",
    "id" : "America/Lima"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Los_Angeles )",
    "id" : "America/Los_Angeles"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Louisville )",
    "id" : "America/Louisville"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Lower_Princes )",
    "id" : "America/Lower_Princes"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Maceio )",
    "id" : "America/Maceio"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Managua )",
    "id" : "America/Managua"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Manaus )",
    "id" : "America/Manaus"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Marigot )",
    "id" : "America/Marigot"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Martinique )",
    "id" : "America/Martinique"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Matamoros )",
    "id" : "America/Matamoros"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( America/Mazatlan )",
    "id" : "America/Mazatlan"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Mendoza )",
    "id" : "America/Mendoza"
  }, {
    "name" : "( GMT -5:00 ) Central Daylight Time( America/Menominee )",
    "id" : "America/Menominee"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Merida )",
    "id" : "America/Merida"
  }, {
    "name" : "( GMT -8:00 ) Pacific Standard Time( America/Metlakatla )",
    "id" : "America/Metlakatla"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Mexico_City )",
    "id" : "America/Mexico_City"
  }, {
    "name" : "( GMT -4:00 ) Pierre & Miquelon Daylight Time( America/Miquelon )",
    "id" : "America/Miquelon"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Moncton )",
    "id" : "America/Moncton"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Monterrey )",
    "id" : "America/Monterrey"
  }, {
    "name" : "( GMT -3:00 ) Uruguay Time( America/Montevideo )",
    "id" : "America/Montevideo"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Montreal )",
    "id" : "America/Montreal"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Montserrat )",
    "id" : "America/Montserrat"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Nassau )",
    "id" : "America/Nassau"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/New_York )",
    "id" : "America/New_York"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Nipigon )",
    "id" : "America/Nipigon"
  }, {
    "name" : "( GMT -11:00 ) Alaska Daylight Time( America/Nome )",
    "id" : "America/Nome"
  }, {
    "name" : "( GMT -2:00 ) Fernando de Noronha Time( America/Noronha )",
    "id" : "America/Noronha"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/Beulah )",
    "id" : "America/North_Dakota/Beulah"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/Center )",
    "id" : "America/North_Dakota/Center"
  }, {
    "name" : "( GMT -7:00 ) Central Daylight Time( America/North_Dakota/New_Salem )",
    "id" : "America/North_Dakota/New_Salem"
  }, {
    "name" : "( GMT -6:00 ) Mountain Daylight Time( America/Ojinaga )",
    "id" : "America/Ojinaga"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( America/Panama )",
    "id" : "America/Panama"
  }, {
    "name" : "( GMT -4:00 ) Eastern Daylight Time( America/Pangnirtung )",
    "id" : "America/Pangnirtung"
  }, {
    "name" : "( GMT -3:30 ) Suriname Time( America/Paramaribo )",
    "id" : "America/Paramaribo"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( America/Phoenix )",
    "id" : "America/Phoenix"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Port-au-Prince )",
    "id" : "America/Port-au-Prince"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Port_of_Spain )",
    "id" : "America/Port_of_Spain"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Porto_Acre )",
    "id" : "America/Porto_Acre"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( America/Porto_Velho )",
    "id" : "America/Porto_Velho"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Puerto_Rico )",
    "id" : "America/Puerto_Rico"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Rainy_River )",
    "id" : "America/Rainy_River"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Rankin_Inlet )",
    "id" : "America/Rankin_Inlet"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Time( America/Recife )",
    "id" : "America/Recife"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Regina )",
    "id" : "America/Regina"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Resolute )",
    "id" : "America/Resolute"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( America/Rio_Branco )",
    "id" : "America/Rio_Branco"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( America/Rosario )",
    "id" : "America/Rosario"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Santa_Isabel )",
    "id" : "America/Santa_Isabel"
  }, {
    "name" : "( GMT -4:00 ) Brasilia Time( America/Santarem )",
    "id" : "America/Santarem"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( America/Santiago )",
    "id" : "America/Santiago"
  }, {
    "name" : "( GMT -4:30 ) Atlantic Standard Time( America/Santo_Domingo )",
    "id" : "America/Santo_Domingo"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( America/Sao_Paulo )",
    "id" : "America/Sao_Paulo"
  }, {
    "name" : "( GMT -2:00 ) Eastern Greenland Summer Time( America/Scoresbysund )",
    "id" : "America/Scoresbysund"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Shiprock )",
    "id" : "America/Shiprock"
  }, {
    "name" : "( GMT -8:00 ) Alaska Daylight Time( America/Sitka )",
    "id" : "America/Sitka"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Barthelemy )",
    "id" : "America/St_Barthelemy"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( America/St_Johns )",
    "id" : "America/St_Johns"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Kitts )",
    "id" : "America/St_Kitts"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Lucia )",
    "id" : "America/St_Lucia"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Thomas )",
    "id" : "America/St_Thomas"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/St_Vincent )",
    "id" : "America/St_Vincent"
  }, {
    "name" : "( GMT -7:00 ) Central Standard Time( America/Swift_Current )",
    "id" : "America/Swift_Current"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( America/Tegucigalpa )",
    "id" : "America/Tegucigalpa"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( America/Thule )",
    "id" : "America/Thule"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Thunder_Bay )",
    "id" : "America/Thunder_Bay"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Tijuana )",
    "id" : "America/Tijuana"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( America/Toronto )",
    "id" : "America/Toronto"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Tortola )",
    "id" : "America/Tortola"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Vancouver )",
    "id" : "America/Vancouver"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( America/Virgin )",
    "id" : "America/Virgin"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( America/Whitehorse )",
    "id" : "America/Whitehorse"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( America/Winnipeg )",
    "id" : "America/Winnipeg"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( America/Yakutat )",
    "id" : "America/Yakutat"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( America/Yellowknife )",
    "id" : "America/Yellowknife"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Antarctica/Casey )",
    "id" : "Antarctica/Casey"
  }, {
    "name" : "( GMT 7:00 ) Davis Time( Antarctica/Davis )",
    "id" : "Antarctica/Davis"
  }, {
    "name" : "( GMT 10:00 ) Dumont-d'Urville Time( Antarctica/DumontDUrville )",
    "id" : "Antarctica/DumontDUrville"
  }, {
    "name" : "( GMT 11:00 ) Macquarie Island Standard Time( Antarctica/Macquarie )",
    "id" : "Antarctica/Macquarie"
  }, {
    "name" : "( GMT 6:00 ) Mawson Time( Antarctica/Mawson )",
    "id" : "Antarctica/Mawson"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Antarctica/McMurdo )",
    "id" : "Antarctica/McMurdo"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( Antarctica/Palmer )",
    "id" : "Antarctica/Palmer"
  }, {
    "name" : "( GMT 0:00 ) Rothera Time( Antarctica/Rothera )",
    "id" : "Antarctica/Rothera"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Antarctica/South_Pole )",
    "id" : "Antarctica/South_Pole"
  }, {
    "name" : "( GMT 3:00 ) Syowa Time( Antarctica/Syowa )",
    "id" : "Antarctica/Syowa"
  }, {
    "name" : "( GMT 0:00 ) Central European Summer Time( Antarctica/Troll )",
    "id" : "Antarctica/Troll"
  }, {
    "name" : "( GMT 6:00 ) Vostok Time( Antarctica/Vostok )",
    "id" : "Antarctica/Vostok"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Arctic/Longyearbyen )",
    "id" : "Arctic/Longyearbyen"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Aden )",
    "id" : "Asia/Aden"
  }, {
    "name" : "( GMT 6:00 ) Alma-Ata Time( Asia/Almaty )",
    "id" : "Asia/Almaty"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Amman )",
    "id" : "Asia/Amman"
  }, {
    "name" : "( GMT 13:00 ) Anadyr Time( Asia/Anadyr )",
    "id" : "Asia/Anadyr"
  }, {
    "name" : "( GMT 5:00 ) Aqtau Time( Asia/Aqtau )",
    "id" : "Asia/Aqtau"
  }, {
    "name" : "( GMT 5:00 ) Aqtobe Time( Asia/Aqtobe )",
    "id" : "Asia/Aqtobe"
  }, {
    "name" : "( GMT 5:00 ) Turkmenistan Time( Asia/Ashgabat )",
    "id" : "Asia/Ashgabat"
  }, {
    "name" : "( GMT 5:00 ) Turkmenistan Time( Asia/Ashkhabad )",
    "id" : "Asia/Ashkhabad"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Baghdad )",
    "id" : "Asia/Baghdad"
  }, {
    "name" : "( GMT 4:00 ) Arabia Standard Time( Asia/Bahrain )",
    "id" : "Asia/Bahrain"
  }, {
    "name" : "( GMT 4:00 ) Azerbaijan Summer Time( Asia/Baku )",
    "id" : "Asia/Baku"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Bangkok )",
    "id" : "Asia/Bangkok"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Beirut )",
    "id" : "Asia/Beirut"
  }, {
    "name" : "( GMT 6:00 ) Kirgizstan Time( Asia/Bishkek )",
    "id" : "Asia/Bishkek"
  }, {
    "name" : "( GMT 8:00 ) Brunei Time( Asia/Brunei )",
    "id" : "Asia/Brunei"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Calcutta )",
    "id" : "Asia/Calcutta"
  }, {
    "name" : "( GMT 8:00 ) Irkutsk Time( Asia/Chita )",
    "id" : "Asia/Chita"
  }, {
    "name" : "( GMT 7:00 ) Choibalsan Summer Time( Asia/Choibalsan )",
    "id" : "Asia/Choibalsan"
  }, {
    "name" : "( GMT 7:00 ) China Standard Time( Asia/Chongqing )",
    "id" : "Asia/Chongqing"
  }, {
    "name" : "( GMT 7:00 ) China Standard Time( Asia/Chungking )",
    "id" : "Asia/Chungking"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Colombo )",
    "id" : "Asia/Colombo"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( Asia/Dacca )",
    "id" : "Asia/Dacca"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Damascus )",
    "id" : "Asia/Damascus"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( Asia/Dhaka )",
    "id" : "Asia/Dhaka"
  }, {
    "name" : "( GMT 9:00 ) Timor-Leste Time( Asia/Dili )",
    "id" : "Asia/Dili"
  }, {
    "name" : "( GMT 4:00 ) Gulf Standard Time( Asia/Dubai )",
    "id" : "Asia/Dubai"
  }, {
    "name" : "( GMT 6:00 ) Tajikistan Time( Asia/Dushanbe )",
    "id" : "Asia/Dushanbe"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Gaza )",
    "id" : "Asia/Gaza"
  }, {
    "name" : "( GMT 8:30 ) China Standard Time( Asia/Harbin )",
    "id" : "Asia/Harbin"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Hebron )",
    "id" : "Asia/Hebron"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Ho_Chi_Minh )",
    "id" : "Asia/Ho_Chi_Minh"
  }, {
    "name" : "( GMT 8:00 ) Hong Kong Time( Asia/Hong_Kong )",
    "id" : "Asia/Hong_Kong"
  }, {
    "name" : "( GMT 6:00 ) Hovd Summer Time( Asia/Hovd )",
    "id" : "Asia/Hovd"
  }, {
    "name" : "( GMT 8:00 ) Irkutsk Time( Asia/Irkutsk )",
    "id" : "Asia/Irkutsk"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Istanbul )",
    "id" : "Asia/Istanbul"
  }, {
    "name" : "( GMT 7:00 ) West Indonesia Time( Asia/Jakarta )",
    "id" : "Asia/Jakarta"
  }, {
    "name" : "( GMT 9:00 ) East Indonesia Time( Asia/Jayapura )",
    "id" : "Asia/Jayapura"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Asia/Jerusalem )",
    "id" : "Asia/Jerusalem"
  }, {
    "name" : "( GMT 4:30 ) Afghanistan Time( Asia/Kabul )",
    "id" : "Asia/Kabul"
  }, {
    "name" : "( GMT 12:00 ) Petropavlovsk-Kamchatski Time( Asia/Kamchatka )",
    "id" : "Asia/Kamchatka"
  }, {
    "name" : "( GMT 5:00 ) Pakistan Time( Asia/Karachi )",
    "id" : "Asia/Karachi"
  }, {
    "name" : "( GMT 5:00 ) Xinjiang Standard Time( Asia/Kashgar )",
    "id" : "Asia/Kashgar"
  }, {
    "name" : "( GMT 5:30 ) Nepal Time( Asia/Kathmandu )",
    "id" : "Asia/Kathmandu"
  }, {
    "name" : "( GMT 5:30 ) Nepal Time( Asia/Katmandu )",
    "id" : "Asia/Katmandu"
  }, {
    "name" : "( GMT 9:00 ) Khandyga Time( Asia/Khandyga )",
    "id" : "Asia/Khandyga"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( Asia/Kolkata )",
    "id" : "Asia/Kolkata"
  }, {
    "name" : "( GMT 7:00 ) Krasnoyarsk Time( Asia/Krasnoyarsk )",
    "id" : "Asia/Krasnoyarsk"
  }, {
    "name" : "( GMT 7:30 ) Malaysia Time( Asia/Kuala_Lumpur )",
    "id" : "Asia/Kuala_Lumpur"
  }, {
    "name" : "( GMT 8:00 ) Malaysia Time( Asia/Kuching )",
    "id" : "Asia/Kuching"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Kuwait )",
    "id" : "Asia/Kuwait"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Macao )",
    "id" : "Asia/Macao"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Macau )",
    "id" : "Asia/Macau"
  }, {
    "name" : "( GMT 11:00 ) Magadan Time( Asia/Magadan )",
    "id" : "Asia/Magadan"
  }, {
    "name" : "( GMT 8:00 ) Central Indonesia Time( Asia/Makassar )",
    "id" : "Asia/Makassar"
  }, {
    "name" : "( GMT 8:00 ) Philippines Time( Asia/Manila )",
    "id" : "Asia/Manila"
  }, {
    "name" : "( GMT 4:00 ) Gulf Standard Time( Asia/Muscat )",
    "id" : "Asia/Muscat"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Asia/Nicosia )",
    "id" : "Asia/Nicosia"
  }, {
    "name" : "( GMT 7:00 ) Krasnoyarsk Time( Asia/Novokuznetsk )",
    "id" : "Asia/Novokuznetsk"
  }, {
    "name" : "( GMT 7:00 ) Novosibirsk Time( Asia/Novosibirsk )",
    "id" : "Asia/Novosibirsk"
  }, {
    "name" : "( GMT 6:00 ) Omsk Time( Asia/Omsk )",
    "id" : "Asia/Omsk"
  }, {
    "name" : "( GMT 5:00 ) Oral Time( Asia/Oral )",
    "id" : "Asia/Oral"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Phnom_Penh )",
    "id" : "Asia/Phnom_Penh"
  }, {
    "name" : "( GMT 8:00 ) West Indonesia Time( Asia/Pontianak )",
    "id" : "Asia/Pontianak"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( Asia/Pyongyang )",
    "id" : "Asia/Pyongyang"
  }, {
    "name" : "( GMT 4:00 ) Arabia Standard Time( Asia/Qatar )",
    "id" : "Asia/Qatar"
  }, {
    "name" : "( GMT 5:00 ) Qyzylorda Time( Asia/Qyzylorda )",
    "id" : "Asia/Qyzylorda"
  }, {
    "name" : "( GMT 6:30 ) Myanmar Time( Asia/Rangoon )",
    "id" : "Asia/Rangoon"
  }, {
    "name" : "( GMT 3:00 ) Arabia Standard Time( Asia/Riyadh )",
    "id" : "Asia/Riyadh"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Saigon )",
    "id" : "Asia/Saigon"
  }, {
    "name" : "( GMT 11:00 ) Sakhalin Time( Asia/Sakhalin )",
    "id" : "Asia/Sakhalin"
  }, {
    "name" : "( GMT 5:00 ) Uzbekistan Time( Asia/Samarkand )",
    "id" : "Asia/Samarkand"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( Asia/Seoul )",
    "id" : "Asia/Seoul"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Shanghai )",
    "id" : "Asia/Shanghai"
  }, {
    "name" : "( GMT 7:30 ) Singapore Time( Asia/Singapore )",
    "id" : "Asia/Singapore"
  }, {
    "name" : "( GMT 11:00 ) Srednekolymsk Time( Asia/Srednekolymsk )",
    "id" : "Asia/Srednekolymsk"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( Asia/Taipei )",
    "id" : "Asia/Taipei"
  }, {
    "name" : "( GMT 6:00 ) Uzbekistan Time( Asia/Tashkent )",
    "id" : "Asia/Tashkent"
  }, {
    "name" : "( GMT 4:00 ) Georgia Time( Asia/Tbilisi )",
    "id" : "Asia/Tbilisi"
  }, {
    "name" : "( GMT 3:30 ) Iran Daylight Time( Asia/Tehran )",
    "id" : "Asia/Tehran"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Asia/Tel_Aviv )",
    "id" : "Asia/Tel_Aviv"
  }, {
    "name" : "( GMT 5:30 ) Bhutan Time( Asia/Thimbu )",
    "id" : "Asia/Thimbu"
  }, {
    "name" : "( GMT 5:30 ) Bhutan Time( Asia/Thimphu )",
    "id" : "Asia/Thimphu"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( Asia/Tokyo )",
    "id" : "Asia/Tokyo"
  }, {
    "name" : "( GMT 8:00 ) Central Indonesia Time( Asia/Ujung_Pandang )",
    "id" : "Asia/Ujung_Pandang"
  }, {
    "name" : "( GMT 7:00 ) Ulaanbaatar Summer Time( Asia/Ulaanbaatar )",
    "id" : "Asia/Ulaanbaatar"
  }, {
    "name" : "( GMT 7:00 ) Ulaanbaatar Summer Time( Asia/Ulan_Bator )",
    "id" : "Asia/Ulan_Bator"
  }, {
    "name" : "( GMT 6:00 ) Xinjiang Standard Time( Asia/Urumqi )",
    "id" : "Asia/Urumqi"
  }, {
    "name" : "( GMT 10:00 ) Ust-Nera Time( Asia/Ust-Nera )",
    "id" : "Asia/Ust-Nera"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( Asia/Vientiane )",
    "id" : "Asia/Vientiane"
  }, {
    "name" : "( GMT 10:00 ) Vladivostok Time( Asia/Vladivostok )",
    "id" : "Asia/Vladivostok"
  }, {
    "name" : "( GMT 9:00 ) Yakutsk Time( Asia/Yakutsk )",
    "id" : "Asia/Yakutsk"
  }, {
    "name" : "( GMT 5:00 ) Yekaterinburg Time( Asia/Yekaterinburg )",
    "id" : "Asia/Yekaterinburg"
  }, {
    "name" : "( GMT 4:00 ) Armenia Time( Asia/Yerevan )",
    "id" : "Asia/Yerevan"
  }, {
    "name" : "( GMT -1:00 ) Azores Summer Time( Atlantic/Azores )",
    "id" : "Atlantic/Azores"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( Atlantic/Bermuda )",
    "id" : "Atlantic/Bermuda"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Canary )",
    "id" : "Atlantic/Canary"
  }, {
    "name" : "( GMT -2:00 ) Cape Verde Time( Atlantic/Cape_Verde )",
    "id" : "Atlantic/Cape_Verde"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Faeroe )",
    "id" : "Atlantic/Faeroe"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Faroe )",
    "id" : "Atlantic/Faroe"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Atlantic/Jan_Mayen )",
    "id" : "Atlantic/Jan_Mayen"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( Atlantic/Madeira )",
    "id" : "Atlantic/Madeira"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Atlantic/Reykjavik )",
    "id" : "Atlantic/Reykjavik"
  }, {
    "name" : "( GMT -2:00 ) South Georgia Standard Time( Atlantic/South_Georgia )",
    "id" : "Atlantic/South_Georgia"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Atlantic/St_Helena )",
    "id" : "Atlantic/St_Helena"
  }, {
    "name" : "( GMT -4:00 ) Falkland Is. Time( Atlantic/Stanley )",
    "id" : "Atlantic/Stanley"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/ACT )",
    "id" : "Australia/ACT"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia)( Australia/Adelaide )",
    "id" : "Australia/Adelaide"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Brisbane )",
    "id" : "Australia/Brisbane"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia/New South Wales)( Australia/Broken_Hill )",
    "id" : "Australia/Broken_Hill"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Canberra )",
    "id" : "Australia/Canberra"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Currie )",
    "id" : "Australia/Currie"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( Australia/Darwin )",
    "id" : "Australia/Darwin"
  }, {
    "name" : "( GMT 8:45 ) Australian Central Western Standard Time( Australia/Eucla )",
    "id" : "Australia/Eucla"
  }, {
    "name" : "( GMT 11:00 ) Australian Eastern Daylight Time (Tasmania)( Australia/Hobart )",
    "id" : "Australia/Hobart"
  }, {
    "name" : "( GMT 10:00 ) Lord Howe Daylight Time( Australia/LHI )",
    "id" : "Australia/LHI"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Lindeman )",
    "id" : "Australia/Lindeman"
  }, {
    "name" : "( GMT 10:00 ) Lord Howe Daylight Time( Australia/Lord_Howe )",
    "id" : "Australia/Lord_Howe"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (Victoria)( Australia/Melbourne )",
    "id" : "Australia/Melbourne"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/NSW )",
    "id" : "Australia/NSW"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( Australia/North )",
    "id" : "Australia/North"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Australia/Perth )",
    "id" : "Australia/Perth"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Standard Time (Queensland)( Australia/Queensland )",
    "id" : "Australia/Queensland"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia)( Australia/South )",
    "id" : "Australia/South"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( Australia/Sydney )",
    "id" : "Australia/Sydney"
  }, {
    "name" : "( GMT 11:00 ) Australian Eastern Daylight Time (Tasmania)( Australia/Tasmania )",
    "id" : "Australia/Tasmania"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (Victoria)( Australia/Victoria )",
    "id" : "Australia/Victoria"
  }, {
    "name" : "( GMT 8:00 ) Australian Western Standard Time( Australia/West )",
    "id" : "Australia/West"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Daylight Time (South Australia/New South Wales)( Australia/Yancowinna )",
    "id" : "Australia/Yancowinna"
  }, {
    "name" : "( GMT -5:00 ) Acre Time( Brazil/Acre )",
    "id" : "Brazil/Acre"
  }, {
    "name" : "( GMT -2:00 ) Fernando de Noronha Time( Brazil/DeNoronha )",
    "id" : "Brazil/DeNoronha"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( Brazil/East )",
    "id" : "Brazil/East"
  }, {
    "name" : "( GMT -4:00 ) Amazon Time( Brazil/West )",
    "id" : "Brazil/West"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( CET )",
    "id" : "CET"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( CST6CDT )",
    "id" : "CST6CDT"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( Canada/Atlantic )",
    "id" : "Canada/Atlantic"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( Canada/Central )",
    "id" : "Canada/Central"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( Canada/East-Saskatchewan )",
    "id" : "Canada/East-Saskatchewan"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( Canada/Eastern )",
    "id" : "Canada/Eastern"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( Canada/Mountain )",
    "id" : "Canada/Mountain"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( Canada/Newfoundland )",
    "id" : "Canada/Newfoundland"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Canada/Pacific )",
    "id" : "Canada/Pacific"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( Canada/Saskatchewan )",
    "id" : "Canada/Saskatchewan"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Canada/Yukon )",
    "id" : "Canada/Yukon"
  }, {
    "name" : "( GMT -3:00 ) Chile Time( Chile/Continental )",
    "id" : "Chile/Continental"
  }, {
    "name" : "( GMT -6:00 ) Easter Is. Time( Chile/EasterIsland )",
    "id" : "Chile/EasterIsland"
  }, {
    "name" : "( GMT -5:00 ) Cuba Daylight Time( Cuba )",
    "id" : "Cuba"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( EET )",
    "id" : "EET"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( EST5EDT )",
    "id" : "EST5EDT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Egypt )",
    "id" : "Egypt"
  }, {
    "name" : "( GMT 1:00 ) Irish Summer Time( Eire )",
    "id" : "Eire"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT )",
    "id" : "Etc/GMT"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT+0 )",
    "id" : "Etc/GMT+0"
  }, {
    "name" : "( GMT -1:00 ) GMT-01:00( Etc/GMT+1 )",
    "id" : "Etc/GMT+1"
  }, {
    "name" : "( GMT -10:00 ) GMT-10:00( Etc/GMT+10 )",
    "id" : "Etc/GMT+10"
  }, {
    "name" : "( GMT -11:00 ) GMT-11:00( Etc/GMT+11 )",
    "id" : "Etc/GMT+11"
  }, {
    "name" : "( GMT -12:00 ) GMT-12:00( Etc/GMT+12 )",
    "id" : "Etc/GMT+12"
  }, {
    "name" : "( GMT -2:00 ) GMT-02:00( Etc/GMT+2 )",
    "id" : "Etc/GMT+2"
  }, {
    "name" : "( GMT -3:00 ) GMT-03:00( Etc/GMT+3 )",
    "id" : "Etc/GMT+3"
  }, {
    "name" : "( GMT -4:00 ) GMT-04:00( Etc/GMT+4 )",
    "id" : "Etc/GMT+4"
  }, {
    "name" : "( GMT -5:00 ) GMT-05:00( Etc/GMT+5 )",
    "id" : "Etc/GMT+5"
  }, {
    "name" : "( GMT -6:00 ) GMT-06:00( Etc/GMT+6 )",
    "id" : "Etc/GMT+6"
  }, {
    "name" : "( GMT -7:00 ) GMT-07:00( Etc/GMT+7 )",
    "id" : "Etc/GMT+7"
  }, {
    "name" : "( GMT -8:00 ) GMT-08:00( Etc/GMT+8 )",
    "id" : "Etc/GMT+8"
  }, {
    "name" : "( GMT -9:00 ) GMT-09:00( Etc/GMT+9 )",
    "id" : "Etc/GMT+9"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT-0 )",
    "id" : "Etc/GMT-0"
  }, {
    "name" : "( GMT 1:00 ) GMT+01:00( Etc/GMT-1 )",
    "id" : "Etc/GMT-1"
  }, {
    "name" : "( GMT 10:00 ) GMT+10:00( Etc/GMT-10 )",
    "id" : "Etc/GMT-10"
  }, {
    "name" : "( GMT 11:00 ) GMT+11:00( Etc/GMT-11 )",
    "id" : "Etc/GMT-11"
  }, {
    "name" : "( GMT 12:00 ) GMT+12:00( Etc/GMT-12 )",
    "id" : "Etc/GMT-12"
  }, {
    "name" : "( GMT 13:00 ) GMT+13:00( Etc/GMT-13 )",
    "id" : "Etc/GMT-13"
  }, {
    "name" : "( GMT 14:00 ) GMT+14:00( Etc/GMT-14 )",
    "id" : "Etc/GMT-14"
  }, {
    "name" : "( GMT 2:00 ) GMT+02:00( Etc/GMT-2 )",
    "id" : "Etc/GMT-2"
  }, {
    "name" : "( GMT 3:00 ) GMT+03:00( Etc/GMT-3 )",
    "id" : "Etc/GMT-3"
  }, {
    "name" : "( GMT 4:00 ) GMT+04:00( Etc/GMT-4 )",
    "id" : "Etc/GMT-4"
  }, {
    "name" : "( GMT 5:00 ) GMT+05:00( Etc/GMT-5 )",
    "id" : "Etc/GMT-5"
  }, {
    "name" : "( GMT 6:00 ) GMT+06:00( Etc/GMT-6 )",
    "id" : "Etc/GMT-6"
  }, {
    "name" : "( GMT 7:00 ) GMT+07:00( Etc/GMT-7 )",
    "id" : "Etc/GMT-7"
  }, {
    "name" : "( GMT 8:00 ) GMT+08:00( Etc/GMT-8 )",
    "id" : "Etc/GMT-8"
  }, {
    "name" : "( GMT 9:00 ) GMT+09:00( Etc/GMT-9 )",
    "id" : "Etc/GMT-9"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/GMT0 )",
    "id" : "Etc/GMT0"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Etc/Greenwich )",
    "id" : "Etc/Greenwich"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/UCT )",
    "id" : "Etc/UCT"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/UTC )",
    "id" : "Etc/UTC"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/Universal )",
    "id" : "Etc/Universal"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Etc/Zulu )",
    "id" : "Etc/Zulu"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Amsterdam )",
    "id" : "Europe/Amsterdam"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Andorra )",
    "id" : "Europe/Andorra"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Athens )",
    "id" : "Europe/Athens"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Belfast )",
    "id" : "Europe/Belfast"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Belgrade )",
    "id" : "Europe/Belgrade"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Berlin )",
    "id" : "Europe/Berlin"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Bratislava )",
    "id" : "Europe/Bratislava"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Brussels )",
    "id" : "Europe/Brussels"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Bucharest )",
    "id" : "Europe/Bucharest"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Budapest )",
    "id" : "Europe/Budapest"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Busingen )",
    "id" : "Europe/Busingen"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Chisinau )",
    "id" : "Europe/Chisinau"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Copenhagen )",
    "id" : "Europe/Copenhagen"
  }, {
    "name" : "( GMT 1:00 ) Irish Summer Time( Europe/Dublin )",
    "id" : "Europe/Dublin"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Gibraltar )",
    "id" : "Europe/Gibraltar"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Guernsey )",
    "id" : "Europe/Guernsey"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Helsinki )",
    "id" : "Europe/Helsinki"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Isle_of_Man )",
    "id" : "Europe/Isle_of_Man"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Istanbul )",
    "id" : "Europe/Istanbul"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/Jersey )",
    "id" : "Europe/Jersey"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Time( Europe/Kaliningrad )",
    "id" : "Europe/Kaliningrad"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Kiev )",
    "id" : "Europe/Kiev"
  }, {
    "name" : "( GMT 1:00 ) Western European Summer Time( Europe/Lisbon )",
    "id" : "Europe/Lisbon"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Ljubljana )",
    "id" : "Europe/Ljubljana"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( Europe/London )",
    "id" : "Europe/London"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Luxembourg )",
    "id" : "Europe/Luxembourg"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Madrid )",
    "id" : "Europe/Madrid"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Malta )",
    "id" : "Europe/Malta"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Mariehamn )",
    "id" : "Europe/Mariehamn"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Minsk )",
    "id" : "Europe/Minsk"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Monaco )",
    "id" : "Europe/Monaco"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Moscow )",
    "id" : "Europe/Moscow"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Nicosia )",
    "id" : "Europe/Nicosia"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Oslo )",
    "id" : "Europe/Oslo"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Paris )",
    "id" : "Europe/Paris"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Podgorica )",
    "id" : "Europe/Podgorica"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Prague )",
    "id" : "Europe/Prague"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Riga )",
    "id" : "Europe/Riga"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Rome )",
    "id" : "Europe/Rome"
  }, {
    "name" : "( GMT 4:00 ) Samara Time( Europe/Samara )",
    "id" : "Europe/Samara"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/San_Marino )",
    "id" : "Europe/San_Marino"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Sarajevo )",
    "id" : "Europe/Sarajevo"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( Europe/Simferopol )",
    "id" : "Europe/Simferopol"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Skopje )",
    "id" : "Europe/Skopje"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Europe/Sofia )",
    "id" : "Europe/Sofia"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Stockholm )",
    "id" : "Europe/Stockholm"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Tallinn )",
    "id" : "Europe/Tallinn"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Tirane )",
    "id" : "Europe/Tirane"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Tiraspol )",
    "id" : "Europe/Tiraspol"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Uzhgorod )",
    "id" : "Europe/Uzhgorod"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vaduz )",
    "id" : "Europe/Vaduz"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vatican )",
    "id" : "Europe/Vatican"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Vienna )",
    "id" : "Europe/Vienna"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Vilnius )",
    "id" : "Europe/Vilnius"
  }, {
    "name" : "( GMT 4:00 ) Moscow Standard Time( Europe/Volgograd )",
    "id" : "Europe/Volgograd"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Warsaw )",
    "id" : "Europe/Warsaw"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Zagreb )",
    "id" : "Europe/Zagreb"
  }, {
    "name" : "( GMT 3:00 ) Eastern European Summer Time( Europe/Zaporozhye )",
    "id" : "Europe/Zaporozhye"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Europe/Zurich )",
    "id" : "Europe/Zurich"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( GB )",
    "id" : "GB"
  }, {
    "name" : "( GMT 1:00 ) British Summer Time( GB-Eire )",
    "id" : "GB-Eire"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
    "id" : "GMT"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT0 )",
    "id" : "GMT0"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Greenwich )",
    "id" : "Greenwich"
  }, {
    "name" : "( GMT 8:00 ) Hong Kong Time( Hongkong )",
    "id" : "Hongkong"
  }, {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( Iceland )",
    "id" : "Iceland"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Antananarivo )",
    "id" : "Indian/Antananarivo"
  }, {
    "name" : "( GMT 5:00 ) Indian Ocean Territory Time( Indian/Chagos )",
    "id" : "Indian/Chagos"
  }, {
    "name" : "( GMT 7:00 ) Christmas Island Time( Indian/Christmas )",
    "id" : "Indian/Christmas"
  }, {
    "name" : "( GMT 6:30 ) Cocos Islands Time( Indian/Cocos )",
    "id" : "Indian/Cocos"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Comoro )",
    "id" : "Indian/Comoro"
  }, {
    "name" : "( GMT 5:00 ) French Southern & Antarctic Lands Time( Indian/Kerguelen )",
    "id" : "Indian/Kerguelen"
  }, {
    "name" : "( GMT 4:00 ) Seychelles Time( Indian/Mahe )",
    "id" : "Indian/Mahe"
  }, {
    "name" : "( GMT 5:00 ) Maldives Time( Indian/Maldives )",
    "id" : "Indian/Maldives"
  }, {
    "name" : "( GMT 4:00 ) Mauritius Time( Indian/Mauritius )",
    "id" : "Indian/Mauritius"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( Indian/Mayotte )",
    "id" : "Indian/Mayotte"
  }, {
    "name" : "( GMT 4:00 ) Reunion Time( Indian/Reunion )",
    "id" : "Indian/Reunion"
  }, {
    "name" : "( GMT 3:30 ) Iran Daylight Time( Iran )",
    "id" : "Iran"
  }, {
    "name" : "( GMT 2:00 ) Israel Daylight Time( Israel )",
    "id" : "Israel"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( Jamaica )",
    "id" : "Jamaica"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( Japan )",
    "id" : "Japan"
  }, {
    "name" : "( GMT -12:00 ) Marshall Islands Time( Kwajalein )",
    "id" : "Kwajalein"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( Libya )",
    "id" : "Libya"
  }, {
    "name" : "( GMT 1:00 ) Middle Europe Summer Time( MET )",
    "id" : "MET"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( MST7MDT )",
    "id" : "MST7MDT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( Mexico/BajaNorte )",
    "id" : "Mexico/BajaNorte"
  }, {
    "name" : "( GMT -8:00 ) Mountain Daylight Time( Mexico/BajaSur )",
    "id" : "Mexico/BajaSur"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( Mexico/General )",
    "id" : "Mexico/General"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( NZ )",
    "id" : "NZ"
  }, {
    "name" : "( GMT 12:45 ) Chatham Daylight Time( NZ-CHAT )",
    "id" : "NZ-CHAT"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( Navajo )",
    "id" : "Navajo"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( PRC )",
    "id" : "PRC"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( PST8PDT )",
    "id" : "PST8PDT"
  }, {
    "name" : "( GMT -11:00 ) West Samoa Daylight Time( Pacific/Apia )",
    "id" : "Pacific/Apia"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( Pacific/Auckland )",
    "id" : "Pacific/Auckland"
  }, {
    "name" : "( GMT 11:00 ) Bougainville Standard Time( Pacific/Bougainville )",
    "id" : "Pacific/Bougainville"
  }, {
    "name" : "( GMT 12:45 ) Chatham Daylight Time( Pacific/Chatham )",
    "id" : "Pacific/Chatham"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Chuuk )",
    "id" : "Pacific/Chuuk"
  }, {
    "name" : "( GMT -6:00 ) Easter Is. Time( Pacific/Easter )",
    "id" : "Pacific/Easter"
  }, {
    "name" : "( GMT 11:00 ) Vanuatu Time( Pacific/Efate )",
    "id" : "Pacific/Efate"
  }, {
    "name" : "( GMT -12:00 ) Phoenix Is. Time( Pacific/Enderbury )",
    "id" : "Pacific/Enderbury"
  }, {
    "name" : "( GMT -10:00 ) Tokelau Time( Pacific/Fakaofo )",
    "id" : "Pacific/Fakaofo"
  }, {
    "name" : "( GMT 12:00 ) Fiji Summer Time( Pacific/Fiji )",
    "id" : "Pacific/Fiji"
  }, {
    "name" : "( GMT 12:00 ) Tuvalu Time( Pacific/Funafuti )",
    "id" : "Pacific/Funafuti"
  }, {
    "name" : "( GMT -5:00 ) Galapagos Time( Pacific/Galapagos )",
    "id" : "Pacific/Galapagos"
  }, {
    "name" : "( GMT -9:00 ) Gambier Time( Pacific/Gambier )",
    "id" : "Pacific/Gambier"
  }, {
    "name" : "( GMT 11:00 ) Solomon Is. Time( Pacific/Guadalcanal )",
    "id" : "Pacific/Guadalcanal"
  }, {
    "name" : "( GMT 10:00 ) Chamorro Standard Time( Pacific/Guam )",
    "id" : "Pacific/Guam"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( Pacific/Honolulu )",
    "id" : "Pacific/Honolulu"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( Pacific/Johnston )",
    "id" : "Pacific/Johnston"
  }, {
    "name" : "( GMT -10:40 ) Line Is. Time( Pacific/Kiritimati )",
    "id" : "Pacific/Kiritimati"
  }, {
    "name" : "( GMT 12:00 ) Kosrae Time( Pacific/Kosrae )",
    "id" : "Pacific/Kosrae"
  }, {
    "name" : "( GMT -12:00 ) Marshall Islands Time( Pacific/Kwajalein )",
    "id" : "Pacific/Kwajalein"
  }, {
    "name" : "( GMT 12:00 ) Marshall Islands Time( Pacific/Majuro )",
    "id" : "Pacific/Majuro"
  }, {
    "name" : "( GMT -9:30 ) Marquesas Time( Pacific/Marquesas )",
    "id" : "Pacific/Marquesas"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Midway )",
    "id" : "Pacific/Midway"
  }, {
    "name" : "( GMT 11:30 ) Nauru Time( Pacific/Nauru )",
    "id" : "Pacific/Nauru"
  }, {
    "name" : "( GMT -11:30 ) Niue Time( Pacific/Niue )",
    "id" : "Pacific/Niue"
  }, {
    "name" : "( GMT 11:30 ) Norfolk Time( Pacific/Norfolk )",
    "id" : "Pacific/Norfolk"
  }, {
    "name" : "( GMT 11:00 ) New Caledonia Time( Pacific/Noumea )",
    "id" : "Pacific/Noumea"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Pago_Pago )",
    "id" : "Pacific/Pago_Pago"
  }, {
    "name" : "( GMT 9:00 ) Palau Time( Pacific/Palau )",
    "id" : "Pacific/Palau"
  }, {
    "name" : "( GMT -8:30 ) Pitcairn Standard Time( Pacific/Pitcairn )",
    "id" : "Pacific/Pitcairn"
  }, {
    "name" : "( GMT 11:00 ) Pohnpei Time( Pacific/Pohnpei )",
    "id" : "Pacific/Pohnpei"
  }, {
    "name" : "( GMT 11:00 ) Pohnpei Time( Pacific/Ponape )",
    "id" : "Pacific/Ponape"
  }, {
    "name" : "( GMT 10:00 ) Papua New Guinea Time( Pacific/Port_Moresby )",
    "id" : "Pacific/Port_Moresby"
  }, {
    "name" : "( GMT -10:30 ) Cook Is. Time( Pacific/Rarotonga )",
    "id" : "Pacific/Rarotonga"
  }, {
    "name" : "( GMT 10:00 ) Chamorro Standard Time( Pacific/Saipan )",
    "id" : "Pacific/Saipan"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( Pacific/Samoa )",
    "id" : "Pacific/Samoa"
  }, {
    "name" : "( GMT -10:00 ) Tahiti Time( Pacific/Tahiti )",
    "id" : "Pacific/Tahiti"
  }, {
    "name" : "( GMT 12:00 ) Gilbert Is. Time( Pacific/Tarawa )",
    "id" : "Pacific/Tarawa"
  }, {
    "name" : "( GMT 13:00 ) Tonga Time( Pacific/Tongatapu )",
    "id" : "Pacific/Tongatapu"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Truk )",
    "id" : "Pacific/Truk"
  }, {
    "name" : "( GMT 12:00 ) Wake Time( Pacific/Wake )",
    "id" : "Pacific/Wake"
  }, {
    "name" : "( GMT 12:00 ) Wallis & Futuna Time( Pacific/Wallis )",
    "id" : "Pacific/Wallis"
  }, {
    "name" : "( GMT 10:00 ) Chuuk Time( Pacific/Yap )",
    "id" : "Pacific/Yap"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( Poland )",
    "id" : "Poland"
  }, {
    "name" : "( GMT 1:00 ) Western European Summer Time( Portugal )",
    "id" : "Portugal"
  }, {
    "name" : "( GMT 9:00 ) Korea Standard Time( ROK )",
    "id" : "ROK"
  }, {
    "name" : "( GMT 7:30 ) Singapore Time( Singapore )",
    "id" : "Singapore"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( SystemV/AST4 )",
    "id" : "SystemV/AST4"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Daylight Time( SystemV/AST4ADT )",
    "id" : "SystemV/AST4ADT"
  }, {
    "name" : "( GMT -6:00 ) Central Standard Time( SystemV/CST6 )",
    "id" : "SystemV/CST6"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( SystemV/CST6CDT )",
    "id" : "SystemV/CST6CDT"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( SystemV/EST5 )",
    "id" : "SystemV/EST5"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( SystemV/EST5EDT )",
    "id" : "SystemV/EST5EDT"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( SystemV/HST10 )",
    "id" : "SystemV/HST10"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( SystemV/MST7 )",
    "id" : "SystemV/MST7"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( SystemV/MST7MDT )",
    "id" : "SystemV/MST7MDT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Standard Time( SystemV/PST8 )",
    "id" : "SystemV/PST8"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( SystemV/PST8PDT )",
    "id" : "SystemV/PST8PDT"
  }, {
    "name" : "( GMT -9:00 ) Alaska Standard Time( SystemV/YST9 )",
    "id" : "SystemV/YST9"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( SystemV/YST9YDT )",
    "id" : "SystemV/YST9YDT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Summer Time( Turkey )",
    "id" : "Turkey"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( UCT )",
    "id" : "UCT"
  }, {
    "name" : "( GMT -10:00 ) Alaska Daylight Time( US/Alaska )",
    "id" : "US/Alaska"
  }, {
    "name" : "( GMT -11:00 ) Hawaii Daylight Time( US/Aleutian )",
    "id" : "US/Aleutian"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( US/Arizona )",
    "id" : "US/Arizona"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( US/Central )",
    "id" : "US/Central"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/East-Indiana )",
    "id" : "US/East-Indiana"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/Eastern )",
    "id" : "US/Eastern"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( US/Hawaii )",
    "id" : "US/Hawaii"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( US/Indiana-Starke )",
    "id" : "US/Indiana-Starke"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( US/Michigan )",
    "id" : "US/Michigan"
  }, {
    "name" : "( GMT -7:00 ) Mountain Daylight Time( US/Mountain )",
    "id" : "US/Mountain"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( US/Pacific )",
    "id" : "US/Pacific"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( US/Pacific-New )",
    "id" : "US/Pacific-New"
  }, {
    "name" : "( GMT -11:00 ) Samoa Standard Time( US/Samoa )",
    "id" : "US/Samoa"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( UTC )",
    "id" : "UTC"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Universal )",
    "id" : "Universal"
  }, {
    "name" : "( GMT 3:00 ) Moscow Standard Time( W-SU )",
    "id" : "W-SU"
  }, {
    "name" : "( GMT 0:00 ) Western European Summer Time( WET )",
    "id" : "WET"
  }, {
    "name" : "( GMT 0:00 ) Coordinated Universal Time( Zulu )",
    "id" : "Zulu"
  }, {
    "name" : "( GMT -5:00 ) Eastern Standard Time( EST )",
    "id" : "EST"
  }, {
    "name" : "( GMT -10:00 ) Hawaii Standard Time( HST )",
    "id" : "HST"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( MST )",
    "id" : "MST"
  }, {
    "name" : "( GMT 9:30 ) Australian Central Standard Time (Northern Territory)( ACT )",
    "id" : "ACT"
  }, {
    "name" : "( GMT 10:00 ) Australian Eastern Daylight Time (New South Wales)( AET )",
    "id" : "AET"
  }, {
    "name" : "( GMT -3:00 ) Argentine Time( AGT )",
    "id" : "AGT"
  }, {
    "name" : "( GMT 2:00 ) Eastern European Time( ART )",
    "id" : "ART"
  }, {
    "name" : "( GMT -9:00 ) Alaska Daylight Time( AST )",
    "id" : "AST"
  }, {
    "name" : "( GMT -3:00 ) Brasilia Summer Time( BET )",
    "id" : "BET"
  }, {
    "name" : "( GMT 6:00 ) Bangladesh Time( BST )",
    "id" : "BST"
  }, {
    "name" : "( GMT 2:00 ) Central African Time( CAT )",
    "id" : "CAT"
  }, {
    "name" : "( GMT -3:30 ) Newfoundland Daylight Time( CNT )",
    "id" : "CNT"
  }, {
    "name" : "( GMT -6:00 ) Central Daylight Time( CST )",
    "id" : "CST"
  }, {
    "name" : "( GMT 8:00 ) China Standard Time( CTT )",
    "id" : "CTT"
  }, {
    "name" : "( GMT 3:00 ) Eastern African Time( EAT )",
    "id" : "EAT"
  }, {
    "name" : "( GMT 1:00 ) Central European Summer Time( ECT )",
    "id" : "ECT"
  }, {
    "name" : "( GMT -5:00 ) Eastern Daylight Time( IET )",
    "id" : "IET"
  }, {
    "name" : "( GMT 5:30 ) India Standard Time( IST )",
    "id" : "IST"
  }, {
    "name" : "( GMT 9:00 ) Japan Standard Time( JST )",
    "id" : "JST"
  }, {
    "name" : "( GMT 13:00 ) West Samoa Daylight Time( MIT )",
    "id" : "MIT"
  }, {
    "name" : "( GMT 4:00 ) Armenia Time( NET )",
    "id" : "NET"
  }, {
    "name" : "( GMT 12:00 ) New Zealand Daylight Time( NST )",
    "id" : "NST"
  }, {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  }, {
    "name" : "( GMT -7:00 ) Mountain Standard Time( PNT )",
    "id" : "PNT"
  }, {
    "name" : "( GMT -4:00 ) Atlantic Standard Time( PRT )",
    "id" : "PRT"
  }, {
    "name" : "( GMT -8:00 ) Pacific Daylight Time( PST )",
    "id" : "PST"
  }, {
    "name" : "( GMT 11:00 ) Solomon Is. Time( SST )",
    "id" : "SST"
  }, {
    "name" : "( GMT 7:00 ) Indochina Time( VST )",
    "id" : "VST"
  } ]
}

Agent Signatures

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.

ATTRIBUTES

Attribute Name
Data Type
Description
isActive

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.

agentId 

deprecated

long

ID of the agent. This key is deprecated, Please use id key instead of this

id

long

ID of the agent

defaultSignature

string

Default signature of the agent

customizedSignatures

list

Department-specific, customized signatures of the agent

Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  }, {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>User Onboarding</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div></div><div><br /></div></div>",
    "departmentId" : 4000000027042
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}


Get signatures of agent

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

GET /api/v1/agents/{agent_id}/signatures

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000012902/signatures
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  }, {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>User Onboarding</b><br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div></div><div><br /></div></div>",
    "departmentId" : 4000000027042
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Update signatures of agent

This API updates the existing signatures of an agent.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
isActive

boolean

optional

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.

defaultSignature

string

optional,
max chars : 65000

Default signature of the agent

customizedSignatures

list

optional

Department-specific, customized signatures of the agent

PATCH /api/v1/agents/{agent_id}/signatures

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/agents/4000000012902/signatures
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>"
}'

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div><b>Sales &amp; Marketing</b><br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Update customized signatures of agent

This API updates the customized signatures of an agent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

required

ID of the department in which the signature exists

signature

string

required,
max chars : 65000

Signature of the agent in that department

POST /api/v1/agents/{agent_id}/updateCustomizedSignature

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/4000000012902/updateCustomizedSignature
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div>Sales &amp; Marketing<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
  "departmentId" : 4000000015063
}'

Response Example

{
  "customizedSignatures" : [ {
    "signature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>Manager</b><br /></div><div>Sales &amp; Marketing<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div><div><div><br /></div></div><div><br /></div></div><div><br /></div></div><div><br /></div></div>",
    "departmentId" : 4000000015063
  } ],
  "agentId" : 4000000012902,
  "defaultSignature" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Bonnie Runolfsson<br /></div><div><b>@Surface Sureve Inc.</b><br /></div></div></div></div></div><div><br /></div></div>",
  "id" : "4000000012902",
  "isActive" : true
}

Businesshours

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

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the business hours set

status

String

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

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

holidayListId 

deprecated

long

ID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours

holidayListIds
see documentation

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

timeZoneId

string

ID of the time zone to associate with the business hours set

businessTimes

list

Business hours for the week

Example

{
  "modifiedTime" : "2018-12-03T07:16:59.198Z",
  "holidayLists" : [ {
    "name" : "Recurring Holiday With Christmas and NewYear",
    "id" : "4000000658002",
    "status" : "ACTIVE"
  }, {
    "name" : "2024 Fixed Holiday Jan 3rd and 4th and Feb 2",
    "id" : "4000000658020",
    "status" : "ACTIVE"
  } ],
  "createdBy" : "4000000016079",
  "associatedHolidayList" : {
    "holidayListStatus" : "INACTIVE",
    "holidayListId" : "4000000105030",
    "holidayListName" : "General HolidayList"
  },
  "name" : "UK Shift BusinessHours",
  "businessTimes" : [ {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "09:00",
    "endTime" : "18:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
    "id" : "GMT"
  },
  "createdTime" : "2018-11-28T11:25:45.082Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000101009",
  "type" : "CUSTOM",
  "status" : "INACTIVE"
}


Create business hours set

This API creates a business hours set in your help desk portal

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the business hours set

status

String

required

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

String

required

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

holidayListId 
deprecated

long

optional

ID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours

holidayListIds
see documentation

list

optional

ID(s) of the holiday lists to associate with business hours. Note: A maximum of 2 holiday lists can be associated with business hours

timeZoneId

string

optional,
max chars : 100

ID of the time zone to associate with the business hours set

businessTimes

list

optional

Business hours for the week

POST /api/v1/businessHours

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/businessHours
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "timeZoneId" : "PLT",
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  } ],
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T07:18:39.796Z",
  "holidayLists" : [ ],
  "createdBy" : "4000000016079",
  "associatedHolidayList" : null,
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Get business hours set

This API fetches the details of a business hours set configured in your help desk portal

Credit: 1 credit/call

GET /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/businessHours/4000000186010
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-12-10T07:18:39.796Z",
  "holidayLists" : [ ],
  "createdBy" : "4000000016079",
  "associatedHolidayList" : null,
  "name" : "BusinssHour Pakistan Shift",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Update business hours set

TThis API updates the details of a business hours set configured in your help desk portal

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the business hours set

status

String

optional

Activation status of the business hours set. Values allowed are ACTIVE and INACTIVE

type

String

optional

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

holidayListId 
deprecated

long

optional

ID of the holiday list, Alert: Use holidayListIds to associate holidays with business hours

holidayListIds
see documentation

list

optional

ID(s) of the holiday lists to associate with business hours. Note: A maximum of 2 holiday lists can be associated with business hours

timeZoneId

string

optional,
max chars : 100

ID of the time zone to associate with the business hours set

businessTimes

list

optional

Business hours for the week

PATCH /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/businessHours/6000000045001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "holidayListIds" : [ "4000000105030" ]
}'

Response Example

{
  "modifiedTime" : "2018-12-10T09:46:28.750Z",
  "holidayLists" : [ {
    "name" : "General HolidayList",
    "id" : "4000000105030",
    "status" : "INACTIVE"
  } ],
  "createdBy" : "4000000016079",
  "associatedHolidayList" : {
    "holidayListStatus" : "INACTIVE",
    "holidayListId" : "4000000105030",
    "holidayListName" : "General HolidayList"
  },
  "name" : "BusinssHour Pakistan Shift-with Holidays",
  "businessTimes" : [ {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "MONDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "TUESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "WEDNESDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "THURSDAY"
  }, {
    "startTime" : "10:00",
    "endTime" : "16:00",
    "day" : "FRIDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SATURDAY"
  }, {
    "startTime" : "00:00",
    "endTime" : "00:00",
    "day" : "SUNDAY"
  } ],
  "timeZone" : {
    "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
    "id" : "PLT"
  },
  "createdTime" : "2018-12-10T07:18:39.796Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000186010",
  "type" : "SPECIFIC",
  "status" : "ACTIVE"
}

Delete business hours set

This API deletes a business hours set from your help desk portal

Credit: 1 credit/call

DELETE /api/v1/businessHours/{businessHourId}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/businessHours/6000000033001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List business hour sets

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the business hour sets must be listed

limit

integer

optional,
range : 1-50

Number of business hour sets to list

status

String

optional

Activation status of the business hour sets. Values allowed are ACTIVE and INACTIVE

businessHourIds

list

optional

The IDs of the BusinessHours to list separated by commas. You can pass upto 50 IDs.

GET /api/v1/businessHours

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/businessHours
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-12-10T07:09:51.265Z",
    "holidayLists" : [ ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "BusinssHour Pak Shift",
    "businessTimes" : [ {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "10:00",
      "endTime" : "16:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 5:00 ) Pakistan Time( PLT )",
      "id" : "PLT"
    },
    "createdTime" : "2018-12-10T07:09:51.265Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000185071",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T10:44:24.258Z",
    "holidayLists" : [ ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "Specific BH",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101003",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T06:48:44.595Z",
    "holidayLists" : [ {
      "name" : "Overlapping Holidays",
      "id" : "4000000117001",
      "status" : "INACTIVE"
    } ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000117001",
      "holidayListName" : "Overlapping Holidays"
    },
    "name" : "24X7 BusinessHour",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000103001",
    "type" : "24X7",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "holidayLists" : [ ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : null,
    "name" : "Indian Shift 2",
    "businessTimes" : [ {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T12:36:11.781Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000104068",
    "type" : "SPECIFIC",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "holidayLists" : [ {
      "name" : "General HolidayList",
      "id" : "4000000105030",
      "status" : "INACTIVE"
    } ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000105030",
      "holidayListName" : "General HolidayList"
    },
    "name" : "UK 24X7 Shift",
    "businessTimes" : [ {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "MONDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "TUESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "THURSDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "FRIDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "23:59",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101005",
    "type" : "24X7",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:59.198Z",
    "holidayLists" : [ {
      "name" : "General HolidayList",
      "id" : "4000000105030",
      "status" : "INACTIVE"
    } ],
    "createdBy" : "4000000016079",
    "associatedHolidayList" : {
      "holidayListStatus" : "INACTIVE",
      "holidayListId" : "4000000105030",
      "holidayListName" : "General HolidayList"
    },
    "name" : "UK Shift",
    "businessTimes" : [ {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "MONDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "TUESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "WEDNESDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "THURSDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "FRIDAY"
    }, {
      "startTime" : "09:00",
      "endTime" : "18:00",
      "day" : "SATURDAY"
    }, {
      "startTime" : "00:00",
      "endTime" : "00:00",
      "day" : "SUNDAY"
    } ],
    "timeZone" : {
      "name" : "( GMT 0:00 ) Greenwich Mean Time( GMT )",
      "id" : "GMT"
    },
    "createdTime" : "2018-11-28T11:25:45.082Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000101009",
    "type" : "CUSTOM",
    "status" : "INACTIVE"
  } ]
}

List associated automation rules

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the rules must be listed

limit

integer

optional,
range : 1-50

Number of rules to list

GET /api/v1/businessHours/{businessHourId}/relatedRules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/businessHours/10000000317019/relatedRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ruleType" : "SUPERVISE",
    "ruleName" : "TBA1",
    "ruleId" : "6000000019012"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Priority-based SLAs",
    "ruleId" : "6000000013508"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Bronze SLAs",
    "ruleId" : "6000000013514"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Default Blueprint",
    "ruleId" : "6000000016083"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "BH BP",
    "ruleId" : "6000000018143"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Third Bp",
    "ruleId" : "6000000023018"
  } ]
}

Blueprints

Blueprints define the entire business process model that ensures your data is streamlined and adhere to your team's work style

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the blueprint

description

String

Description of blueprint

active

Boolean

Active Status of blueprint

dynamicTransOwnerType

String

Dynamic Trans Owner type

module

String

Module of the Blueprint

departmentId

Long

Department of the Blueprint

layoutId

Long

Layout of Blueprint

type

String

Type of blueprint

fieldId

Long

Field mapped for Blueprint

criteria

list

The criteria details for the blueprint

chartData

object

Blueprint Chart Data

Example

{
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "stateName" : "Closed",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Escalated",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Open",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "name" : "Private Threading Handling",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS/CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "REPLY/BUG/COMMENT/RESOLUTION/APPROVAL/ATTACHMENT",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL/SURVEY_GOOD/SURVEY_AVG/SURVEY_BAD",
      "reply" : "REPLY_ALL/REPLY_PRIVATE/REPLY_PUBLIC"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "connections" : [ {
    "fromState" : "Escalated",
    "toState" : "Closed",
    "transition" : [ "Common Handling" ]
  }, {
    "fromState" : "Escalated",
    "toState" : "Closed",
    "transition" : [ "Common Handling" ]
  } ],
  "fieldId" : 4000000000377,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "type" : "START/INTERMEDIATE/END"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "type" : "END"
  } ]
}


Get Blueprint Details

To get a specific blueprint details

Credit: 1 credit/call

GET /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/blueprints/4000000019017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "isDraft" : false,
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

List all blueprints in a department

To get all blueprints in a specific department

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Department for which the blueprints are listed

module

String

required

module of the blueprints to be listed

status

String

optional

To get blueprints by status, allowed values are ACTIVE ,INACTIVE and DRAFT

GET /api/v1/blueprints

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/blueprints?departmentId=4000000007245
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-05-04 08:07:57.0",
    "orderNumber" : "3",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "isDraft" : false,
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "Issue fixed",
      "id" : "1000000309105"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Open",
      "id" : 1000000309101
    }, {
      "name" : "Closed",
      "id" : 1000000309119
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Automate QA process",
    "createdTime" : "2018-05-02 13:39:30.0",
    "id" : "1000000309097",
    "connections" : [ {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000309101"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000309119"
      },
      "transitions" : [ {
        "name" : "Issue fixed",
        "id" : "1000000309105"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-04-24 05:53:28.0",
    "orderNumber" : "4",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "isDraft" : true,
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "before",
      "id" : "1000000232199"
    }, {
      "name" : "after",
      "id" : "1000000232197"
    }, {
      "name" : "during",
      "id" : "1000000232201"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Closed",
      "id" : 1000000232189
    }, {
      "name" : "On Hold",
      "id" : 1000000232191
    }, {
      "name" : "Open",
      "id" : 1000000232193
    }, {
      "name" : "Escalated",
      "id" : 1000000232195
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "AUtomate HR process",
    "createdTime" : "2018-04-10 15:43:54.0",
    "id" : "1000000232187",
    "connections" : [ {
      "fromState" : {
        "name" : "On Hold",
        "id" : "1000000232191"
      },
      "toState" : {
        "name" : "Escalated",
        "id" : "1000000232195"
      },
      "transitions" : [ {
        "name" : "before",
        "id" : "1000000232199"
      } ]
    }, {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000232193"
      },
      "toState" : {
        "name" : "On Hold",
        "id" : "1000000232191"
      },
      "transitions" : [ {
        "name" : "after",
        "id" : "1000000232197"
      } ]
    }, {
      "fromState" : {
        "name" : "Escalated",
        "id" : "1000000232195"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000232189"
      },
      "transitions" : [ {
        "name" : "during",
        "id" : "1000000232201"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-04-03 13:34:08.0",
    "orderNumber" : "5",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "isDraft" : false,
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "to onhold",
      "id" : "1000000173011"
    }, {
      "name" : "To close",
      "id" : "1000000173009"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Closed",
      "id" : 1000000173003
    }, {
      "name" : "Open",
      "id" : 1000000173005
    }, {
      "name" : "On Hold",
      "id" : 1000000173007
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Shipping process",
    "createdTime" : "2018-03-28 12:29:11.0",
    "id" : "1000000173001",
    "connections" : [ {
      "fromState" : {
        "name" : "Open",
        "id" : "1000000173005"
      },
      "toState" : {
        "name" : "On Hold",
        "id" : "1000000173007"
      },
      "transitions" : [ {
        "name" : "to onhold",
        "id" : "1000000173011"
      } ]
    }, {
      "fromState" : {
        "name" : "On Hold",
        "id" : "1000000173007"
      },
      "toState" : {
        "name" : "Closed",
        "id" : "1000000173003"
      },
      "transitions" : [ {
        "name" : "To close",
        "id" : "1000000173009"
      } ]
    } ],
    "fieldId" : "1000000000506"
  }, {
    "modifiedTime" : "2018-05-03 13:18:24.0",
    "orderNumber" : "5",
    "createdUserZUID" : "5263696",
    "departmentId" : "1000000010712",
    "module" : "tickets",
    "isDraft" : false,
    "description" : "",
    "modifiedUserZUID" : "5263696",
    "active" : true,
    "type" : "NON_CONTINUOUS",
    "transitions" : [ {
      "name" : "t1",
      "id" : "1000000313281"
    } ],
    "layoutId" : "1000000011200",
    "states" : [ {
      "name" : "Approval 2",
      "id" : 1000000313277
    }, {
      "name" : "Approval 2 approved",
      "id" : 1000000313279
    } ],
    "i18nFieldLabel" : "Status",
    "fieldLabel" : "Status",
    "name" : "Ticket Support process",
    "createdTime" : "2018-05-03 13:18:24.0",
    "id" : "1000000313275",
    "connections" : [ {
      "fromState" : {
        "name" : "Approval 2 approved",
        "id" : "1000000313279"
      },
      "toState" : {
        "name" : "Approval 2",
        "id" : "1000000313277"
      },
      "transitions" : [ {
        "name" : "t1",
        "id" : "1000000313281"
      } ]
    } ],
    "fieldId" : "1000000000506"
  } ]
}

Create Blueprint

To create a blueprint

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the blueprint

description

String

optional

Description of blueprint

active

Boolean

optional

Active Status of blueprint

dynamicTransOwnerType

String

optional

Dynamic Trans Owner type

module

String

required

Module of the Blueprint

departmentId

Long

required

Department of the Blueprint

layoutId

Long

required

Layout of Blueprint

type

String

required

Type of blueprint

fieldId

Long

required

Field mapped for Blueprint

criteria

list

optional

The criteria details for the blueprint

chartData

object

required

Blueprint Chart Data

states

list

required

State Details

transitions

list

required

Transition Details

connections

list

required

Transition Connections

POST /api/v1/blueprints

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/blueprints
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "stateName" : "Closed",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Escalated",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "stateName" : "Open",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "name" : "Private Threading Handling",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        }
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "during" : [ {
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ 4000000307007 ]
      },
      "task" : {
        "ids" : [ 4000000307007 ]
      },
      "customFunction" : {
        "ids" : [ 4000000307007 ]
      },
      "alert" : {
        "ids" : [ 4000000307007 ]
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "connections" : [ {
    "fromState" : "Open",
    "toState" : "Escalated",
    "transition" : [ "Common Handling" ]
  }, {
    "fromState" : "Escalated",
    "toState" : "Closed",
    "transition" : [ "Common Handling" ]
  } ],
  "fieldId" : 4000000000377,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "type" : "END"
  } ]
}'

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "fieldModule" : "tickets",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "fieldModule" : "tickets",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

Update a blueprint

To update an existing blueprint

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the blueprint

description

String

optional

Description of blueprint

active

Boolean

optional

Active Status of blueprint

dynamicTransOwnerType

String

optional

Dynamic Trans Owner type

module

String

optional

Module of the Blueprint

departmentId

Long

optional

Department of the Blueprint

layoutId

Long

optional

Layout of Blueprint

type

String

optional

Type of blueprint

fieldId

Long

optional

Field mapped for Blueprint

criteria

list

optional

The criteria details for the blueprint

chartData

object

optional

Blueprint Chart Data

states

list

optional

State Details

transitions

list

optional

Transition Details

connections

list

optional

Transition Connections

PATCH /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/blueprints/4000000019017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "type" : "NON_CONTINUOUS"
}'

Response Example

{
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is open",
      "fieldName" : "Status",
      "value" : [ "${OPEN}" ]
    } ],
    "pattern" : "(1)"
  },
  "departmentId" : "4000000007235",
  "module" : "Cases",
  "description" : "Automates Private Threading Handling",
  "type" : "NON_CONTINUOUS",
  "transitions" : [ {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Feedbacks need to be monitored",
    "description" : "Lack of instruments to repair",
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : false
  }, {
    "isAutoTransition" : false,
    "before" : {
      "accessors" : {
        "actionId" : 4000000007723,
        "owners" : {
          "agentIds" : [ 4000000009158 ],
          "otherRecpts" : [ "RECORD_OWNER" ],
          "teamIds" : [ 4000000009158 ]
        },
        "sharedDeptAccessors" : [ {
          "accessors" : {
            "agentIds" : [ 4000000009158 ],
            "teamIds" : [ 4000000009158 ]
          },
          "deptId" : 4000000009158,
          "sharingType" : "READ_ONLY"
        } ]
      },
      "criteriaDetails" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "actionId" : 4000000007723
      }
    },
    "name" : "Common Handling",
    "description" : "Its common transition",
    "commonStates" : [ "Open" ],
    "id" : 4000000007723,
    "during" : [ {
      "actionId" : 4000000007723,
      "message" : "Add comment here"
    }, {
      "fieldUpdates" : {
        "criteria" : {
          "fieldConditions" : [ {
            "condition" : "is open",
            "fieldName" : "Status",
            "value" : [ "${OPEN}" ]
          } ],
          "pattern" : "(1)"
        },
        "fieldId" : 4000000009158,
        "errorMsg" : "Enter a valid Priority"
      },
      "actionId" : 4000000007723,
      "isMandatory" : true
    }, {
      "otherActions" : "BUG",
      "actionId" : 4000000007723,
      "isMandatory" : false
    }, {
      "otherActions" : "COMMENT",
      "actionId" : 4000000007723,
      "isMandatory" : true
    } ],
    "after" : {
      "fieldUpdate" : {
        "ids" : [ {
          "name" : "Update Sensitive fields",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "task" : {
        "ids" : [ {
          "name" : "Create followup task",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "customFunction" : {
        "ids" : [ {
          "name" : "Update Associated time entries",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      },
      "alert" : {
        "ids" : [ {
          "name" : "Trigger Closed Alert",
          "id" : 4000000007723
        } ],
        "actionId" : 4000000007723
      }
    },
    "autoTransitionActions" : {
      "feedback" : "SURVEY_ALL",
      "reply" : "REPLY_ALL"
    },
    "isCommonTransition" : true
  } ],
  "layoutId" : 4000000007723,
  "states" : [ {
    "timeInMins" : 90,
    "escalations" : [ {
      "escalationRecipients" : {
        "agentIds" : [ 4000000009158 ],
        "otherRecpts" : [ "RECORD_OWNER" ]
      },
      "templateId" : 4000000007355,
      "escalationLevel" : 1,
      "whenToEscalate" : 15
    } ],
    "transitionsOrder" : [ "Common Handling", "Feedbacks need to be monitored" ],
    "businessHrId" : 4000000007355,
    "name" : "Open",
    "id" : 4000000007723,
    "type" : "START"
  }, {
    "timeInMins" : 30,
    "name" : "Escalated",
    "id" : 4000000007723,
    "type" : "INTERMEDIATE"
  }, {
    "timeInMins" : 30,
    "name" : "Closed",
    "id" : 4000000007723,
    "type" : "END"
  } ],
  "chartData" : {
    "canvasPosition" : {
      "top" : -29,
      "left" : -127
    },
    "connectionDetails" : [ {
      "toUuid" : "Closed2",
      "transName" : "Check3",
      "isCommTrans" : true,
      "fromUuid" : "Escalated1",
      "usedStates" : [ "On Hold", "Open" ],
      "isAuto" : false
    }, {
      "toUuid" : "Closed3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "OnHold2",
      "isAuto" : false
    }, {
      "toUuid" : "OnHold3",
      "transName" : "Check3",
      "isCommTrans" : false,
      "fromUuid" : "Open2",
      "isAuto" : false
    } ],
    "stateDetails" : [ {
      "lastModifiedStateName" : "Closed",
      "stateName" : "Closed",
      "displayName" : "Closed",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Escalated",
      "stateName" : "Escalated",
      "displayName" : "Escalated",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    }, {
      "lastModifiedStateName" : "Open",
      "stateName" : "Open",
      "displayName" : "Open",
      "stateId" : "4000000007723",
      "position" : {
        "top" : 316,
        "left" : 225
      }
    } ]
  },
  "name" : "Private Threading Handling",
  "id" : "4000000007723",
  "connections" : [ {
    "fromState" : {
      "name" : "Open",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  }, {
    "fromState" : {
      "name" : "Escalated",
      "id" : 4000000324027
    },
    "toState" : {
      "name" : "Closed",
      "id" : 4000000324027
    },
    "transition" : [ {
      "name" : "Feedbacks need to be monitored",
      "id" : 4000000324027
    } ]
  } ],
  "fieldId" : 4000000000377
}

Delete Blueprint

To delete a specific blueprint

Credit: 1 credit/call

DELETE /api/v1/blueprints/{blueprint_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://support.zoho.com/api/v1/blueprints/4000000019017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Reorder blueprints

To reorder blueprints in a specific department

Credit: 1 credit/2 records

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department for which blueprints have to be reordered

module

String

required

module for which blueprints have to be reordered

Attributes

Param Name
Data Type
Description
ids

list

required

Blueprint Ids

POST /api/v1/blueprints/reorder

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/blueprints/reorder?departmentId=4000000007245
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'[ "4000000019017", "4000000019019", "4000000019023", "4000000019021" ]'

Response Example

200

Get Applied Blueprint details of ticket for an user

To get the applied blueprint details of a ticket

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Meta information related to the transition owners. Values allowed are: transitionOwnerAgents, transitionOwnerTeams, transitionOwnerDept to include agents,teams,department under owners. You can pass multiple values by separating them with commas in the API request.

GET /api/v1/tickets/{ticket_id}/blueprint

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/tickets/4000000159817/blueprint
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "name" : "Automate QA Process",
  "id" : 1000000087001,
  "state" : {
    "dueDate" : "2018-02-27T20:49:00.000Z",
    "id" : "1000000087003",
    "type" : "START"
  },
  "transitions" : [ {
    "fromState" : "Open",
    "toState" : "Escalated",
    "criteria" : {
      "fieldConditions" : [ {
        "condition" : "is open",
        "fieldName" : "Status",
        "value" : [ "${OPEN}" ]
      } ],
      "pattern" : "(1)"
    },
    "name" : "Escalate to developers",
    "owners" : [ {
      "agentIds" : [ "1000000012635" ],
      "teams" : [ {
        "name" : "Sales Representatives",
        "id" : "1000000012435"
      } ],
      "departmentId" : "1000000010712",
      "department" : {
        "name" : "Zylker",
        "id" : "1000000010712"
      },
      "teamIds" : [ "1000000012435" ],
      "agents" : [ {
        "photoURL" : "https://desk.zoho.com/api/v1/agent/1000000012635/photo",
        "firstName" : "Lucas",
        "lastName" : "Carol",
        "id" : "1000000012635",
        "email" : "carol@zylker.com"
      } ]
    } ],
    "id" : "1000000087011",
    "canUserPerformTransition" : true,
    "isCriteriaSatisfied" : true,
    "draftDetails" : {
      "totalNoOfDraftActions" : "12",
      "totalNoOfActions" : "24",
      "draftBy" : {
        "name" : "Sandeep Ghemire",
        "id" : "8000000000053"
      },
      "draftAt" : "2020-11-13 16:05:31.0"
    }
  } ]
}

Get During transition form

To get During transition form details for the given transition

Credit: 1 credit/call

GET /api/v1/tickets/{ticket_id}/transitions/{transitionId}/form

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/tickets/4000000159817/transitions/4000000152217/form
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "formActions" : [ {
    "actionType" : "FIELD_UPDATE",
    "draftContent" : {
      "FIELD_UPDATE" : {
        "status" : "Open_july"
      }
    },
    "fieldDetails" : {
      "displayLabel" : "Status",
      "allowedValues" : [ "Open", "Open_july", "On Hold", "Escalated", "Closed1", "Closed", "newDeptClosed" ],
      "isCustomField" : false,
      "defaultValue" : "Open",
      "isSystemMandatory" : true,
      "type" : "Picklist",
      "restoreOnReplyValues" : [ "Open_july", "newDeptClosed", "Escalated", "On Hold", "Closed", "Closed1", "Open" ],
      "name" : "status",
      "sortBy" : "userDefined",
      "id" : "4000000000367",
      "isRemovable" : false,
      "maxLength" : 120,
      "isMandatory" : true
    },
    "isMandatory" : true
  }, {
    "actionType" : "MESSAGE",
    "content" : "Post your reply here"
  }, {
    "actionType" : "REPLY",
    "draftContent" : {
      "REPLY" : {
        "cc" : "blueprintbranchdept@zylker.com,BlueprintBranchDept<blueprintbranchdept@zylker.com>",
        "inReplyToThreadId" : "38512000003329195",
        "bcc" : "",
        "attachments" : [ {
          "size" : "1822318",
          "name" : "Screenshot 2020-12-09 at 5.44.34 PM.png",
          "fileId" : "aaa0b3eec64915077fe3f38a1de2ad14f290eefb25930d93"
        } ],
        "channel" : "EMAIL",
        "to" : "carol@zylker.com",
        "isPrivate" : false,
        "fromEmailAddress" : "BlueprintBranchDept<blueprintbranchdept@zylker.com>",
        "contentType" : "",
        "content" : "<div style='font-size:13.0px;font-family: Arial , Helvetica , Verdana , sans-serif;'><div>Hellei</div><div>---- On &nbsp;Tue, 8 Dec 2020 10:49:54 +0530<b>&nbsp;BlueprintBranchDept&lt;blueprintbranchdept@zylker.com&gt;&nbsp;</b> wrote ---- <br></div><div title=\"beforequote:::\"><br></div><div><blockquote style=\"border-left: 1px dotted #e5e5e5;margin-left:5px;padding-left: 5px;\"><div style=\"padding-top: 10px;\"><div><div style=\"font-size :  13px; font-family :  Arial,  Helvetica,  Verdana,  sans-serif; \"><div>Hello buddy&nbsp;<br></div><div title=\"beforequote:::\"><br></div><div><br></div></div></div><blockquote style=\"border-left :  1px dotted rgb(229, 229, 229); margin-left :  5px; padding-left :  5px; \"><div style=\"padding-top :  10px; \"><br></div></blockquote></div></blockquote></div><div><br></div></div>"
      }
    },
    "isMandatory" : true
  }, {
    "actionType" : "COMMENT",
    "draftContent" : {
      "COMMENT" : {
        "isPublicComment" : false,
        "content" : "Comment is to test transition Draft",
        "uploads" : [ 1000000096035 ]
      }
    },
    "isMandatory" : false
  }, {
    "actionType" : "RESOLUTION",
    "draftContent" : {
      "RESOLUTION" : {
        "toNotifyContactForResolution" : true,
        "content" : "This ticket has to be solved"
      }
    },
    "isMandatory" : true
  }, {
    "actionType" : "APPROVAL",
    "draftContent" : {
      "APPROVAL" : {
        "subject" : "Hello Approvers",
        "description" : "Hello Approvers  ,do approve it",
        "approvers" : [ {
          "approverId" : 8000000000053,
          "approverName" : "Sandeep Ghemire"
        }, {
          "approverId" : 8000000057263,
          "approverName" : "Subodh Ghemire"
        } ]
      }
    },
    "isMandatory" : true
  }, {
    "actionType" : "BUG",
    "isMandatory" : false
  }, {
    "actionType" : "ATTACHMENTS",
    "draftContent" : {
      "ATTACHMENT" : {
        "uploads" : [ {
          "isPublic" : false,
          "id" : "38512000003341108"
        } ]
      }
    },
    "isMandatory" : true
  } ],
  "transitionId" : "4000000152217",
  "continuousTransitions" : [ {
    "transitionId" : "4000000152219",
    "transtionName" : "Close"
  }, {
    "transitionId" : "4000000152221",
    "transtionName" : "Solve"
  } ],
  "isContinuousTransition" : true,
  "draftDetails" : {
    "draftBy" : {
      "name" : "Sandeep Ghemire",
      "id" : "8000000000053"
    },
    "draftAt" : "2020-11-13 16:05:31.0"
  }
}

Revoke Blueprint at Entity Level

To revoke blueprint from an entity

Credit: 1 credit/call

POST /api/v1/tickets/{ticket_id}/revokeBlueprint

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/revokeBlueprint
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "message" : "Blueprint has been revoked from this ticket"
}

Revoke Blueprint from Blueprint Level

To revoke all entities from a particular blueprint

Credit: 500 credits/call

POST /api/v1/blueprints/([0-9]+)/revoke

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/blueprints/4000000159817/revoke
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "message" : "Blueprint revoke scheduled"
}

Validate transition field updates

To validate field updates for the given transition

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
customFields

object

optional

null

cleartextpattern

string

optional,
max chars : 65535

null

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/validateFieldUpdates

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/transitions/4000000152217/validateFieldUpdates
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "customFields" : {
    "customEmail" : "zdesk@zylker.com"
  },
  "channel" : "Facebook",
  "priority" : "Medium",
  "assigneeId" : 1000000012635
}'

Response Example

{
  "invalidFieldUpdates" : [ {
    "fieldName" : "priority",
    "fieldId" : 4000000159817,
    "errorMsg" : "Priority can't be high"
  }, {
    "fieldName" : "customEmail",
    "fieldId" : 4000000159819,
    "errorMsg" : "Email is invalid"
  } ]
}

Perform transition

To perform transition for an entity

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
APPROVAL

JSONObject

optional

Approval details

RESOLUTION

JSONObject

optional

Resolution details

ATTACHMENT

JSONObject

optional

Attachment Details

REPLY

JSONObject

optional

Reply Content details

COMMENT

JSONObject

optional

Comment Details

SHARING

JSONObject

optional

Sharing Details

FIELD_UPDATE

JSONObject

optional

Fields To Update

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/perform

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159817/transitions/4000000152217/perform
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ATTACHMENT" : {
    "uploads" : [ {
      "isPublic" : false,
      "id" : 1000000096035
    } ]
  },
  "FIELD_UPDATE" : {
    "channel" : "Facebook"
  },
  "RESOLUTION" : {
    "toNotifyContactForResolution" : true,
    "content" : "This ticket has to be solved"
  },
  "APPROVAL" : {
    "approverIds" : [ 1000000012635 ],
    "subject" : "Has to be sent for approval"
  },
  "REPLY" : {
    "channel" : "EMAIL",
    "to" : "carol@zylker.com",
    "isPrivate" : false,
    "fromEmailAddress" : "support@zylker.com",
    "contentType" : "plainText",
    "content" : "Hi I m Nancy replying.. ",
    "isForward" : false,
    "uploads" : [ 1000000096035 ]
  },
  "COMMENT" : {
    "isPublicComment" : false,
    "content" : "Comment is to test blueprint",
    "uploads" : [ 1000000096035 ]
  }
}'

Response Example

{
  "message" : "Transition has been completed"
}

Delete the during actions transition draft

To delete the during actions transition draft

Credit: 1 credit/call

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/discardDraft

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159823/transitions/4000000152297/discardDraft
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Save the during actions transition draft

To save the during actions transition draft

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
APPROVAL

JSONObject

optional

Drafted Approval details

RESOLUTION

JSONObject

optional

Drafted Resolution details

ATTACHMENT

JSONObject

optional

Drafted Attachment Details

REPLY

JSONObject

optional

Drafted Reply Content details

COMMENT

JSONObject

optional

Drafted Comment Details

SHARING

JSONObject

optional

Sharing Details

FIELD_UPDATE

JSONObject

optional

Drafted Fields To Update

POST /api/v1/tickets/{ticket_id}/transitions/{transitionId}/saveDraft

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/tickets/4000000159823/transitions/4000000152297/saveDraft
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ATTACHMENT" : {
    "uploads" : [ {
      "isPublic" : false,
      "id" : 1000000096035
    } ]
  },
  "FIELD_UPDATE" : {
    "customFields" : {
      "cf_cffdate_time" : "2020-11-23T06:30:00.000Z",
      "cf_cfphone" : "9999456789",
      "cf_cfinteger" : "19",
      "cf_cfemail" : "carol@zylker.com",
      "cf_cfpicklist" : "Option 1",
      "cf_cffdate" : "2020-11-25",
      "cf_cfpercent" : "32",
      "cf_cfmultiselect" : ";Option 1",
      "cf_cfcheckbox" : true,
      "cf_cfsingle_line" : "Hi Sandeep here!",
      "cf_cfcurrency" : "134",
      "cf_cfmulti_line" : "adad\nasdd",
      "cf_cfdecimal" : "23.0",
      "cf_cfurl" : "www.desk.zoho.com"
    },
    "channel" : "Email"
  },
  "RESOLUTION" : {
    "toNotifyContactForResolution" : true,
    "content" : "This ticket has to be solved"
  },
  "APPROVAL" : {
    "approverIds" : [ 1000000012635 ],
    "subject" : "Has to be sent for approval"
  },
  "REPLY" : {
    "channel" : "EMAIL",
    "to" : "carol@zylker.com",
    "isPrivate" : false,
    "fromEmailAddress" : "support@zylker.com",
    "contentType" : "plainText",
    "content" : "Hi Sandeep here!",
    "isForward" : false,
    "uploads" : [ 1000000096035 ]
  },
  "COMMENT" : {
    "isPublicComment" : false,
    "content" : "Comment is to test transition Draft",
    "uploads" : [ 1000000096035 ]
  }
}'

Response Example

{
  "draftBy" : {
    "name" : "Sandeep Ghemire",
    "id" : "8000000000053"
  },
  "draftAt" : "2020-11-13 16:18:40.0"
}

Get attachment of a transition draft

View a specific attachment added to a transition draft.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
inline

boolean

optional

Whether the display is to be inline

GET /api/v1/tickets/{ticket_id}/transitions/{transitionId}/attachments/{attachmentId}/content

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/tickets/4000000159823/transitions/4000000152297/attachments/4000000152208/content
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Delete attachment of a transition draft

Delete a specific attachment added to a transition draft.

Credit: 1 credit/call

DELETE /api/v1/tickets/{ticket_id}/transitions/{transition_id}/attachments/{attachment_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000159823/transitions/4000000152297/attachments/4000000152207
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Dashboards

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.

Get created tickets count

This API fetches the number of tickets created in a particular duration.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/createdTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/createdTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Get on hold tickets count

This API fetches the number of tickets that are in the on hold status.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/onholdTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/onholdTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Get closed tickets count

This API fetches the number of tickets that are resolved.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/solvedTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/solvedTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=channel
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "Feedback Widget",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Email",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Web",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "Phone",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Forums",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Chat",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Twitter",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "Facebook",
    "referenceValue" : null
  } ],
  "avg" : "0.12",
  "groupedBy" : "channel"
}

Get unresolved tickets count

This API fetches the number of tickets that have remained unresolved over a particular period.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the ticket count according to a particular attribute.This value can be date channel agent

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/backlogTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/backlogTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=agent
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "102",
  "ticketCount" : [ {
    "count" : "54",
    "value" : "Unassigned",
    "referenceValue" : null
  }, {
    "count" : "48",
    "value" : "Priyanka",
    "referenceValue" : "4000000012629"
  } ],
  "avg" : "51.0"
}

List resolution times

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

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups stats according to a specific attribute: date, channel, agent, or hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/ticketsResolutionTime

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/ticketsResolutionTime?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=agent
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalAvgAgentTime" : "41:50 hrs",
  "timeData" : [ {
    "avgSystemTime" : "41:50 hrs",
    "ticketCount" : "1",
    "avgAgentTime" : "41:50 hrs",
    "value" : "Priyanka",
    "referenceValue" : "4000000012629"
  } ],
  "totalTicketCount" : "1",
  "totalAvgSystemTime" : "41:50 hrs",
  "groupedBy" : "agent"
}

List response times

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

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups stats according to a specific attribute: date, channel, agent, or hour

isFirstResponse

boolean

required

Key that specifies if the response is the first response to the customer question

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/responseTime

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/responseTime?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=CUSTOM_IN_DATE&startDate=01-04-2018&endDate=10-04-2018&groupBy=channel
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalAvgAgentTime" : "41:50 hrs",
  "timeData" : [ {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Feedback Widget",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Email",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Web",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "41:50 hrs",
    "avgAgentTime" : "41:50 hrs",
    "responseCount" : "1",
    "value" : "Phone",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Forums",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Chat",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Twitter",
    "referenceValue" : null
  }, {
    "avgSystemTime" : "00:00 hrs",
    "avgAgentTime" : "00:00 hrs",
    "responseCount" : "0",
    "value" : "Facebook",
    "referenceValue" : null
  } ],
  "totalAvgSystemTime" : "41:50 hrs",
  "groupedBy" : "channel",
  "totalResponseCount" : "1"
}

Get total response count

This API fetches the total number of responses sent/made by your agents.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/responseCount

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/responseCount?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "avg" : "0.0",
  "groupedBy" : "date",
  "totalResponseCount" : "0",
  "responseCount" : [ {
    "count" : "0",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-08",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-09",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-10",
    "referenceValue" : null
  } ]
}

Get reopened tickets count

This API fetches the number of tickets that were reopened in your help desk portal.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
groupBy

string

required,
max chars : 100

Key that groups the thread count according to a particular attribute.This value can be date channel agent | hour

departmentId

long

optional

ID(s) of the department(s) from which the stats must be fetched

agentId

long

optional

ID(s) of the agent(s) whose stats must be fetched

teamId

long

optional

ID(s) of the team(s) from which the stats must be fetched

duration

String

required

Predefined time range from which the stats must be fetched

startDate

string

optional,
max chars : 100

Starting date for defining custom time range

endDate

string

optional,
max chars : 100

Ending date for defining custom time range

channel

string

optional,
max chars : 120

Channel through which the tickets were received

GET /api/v1/dashboards/reopenedTickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET http://support.zoho.com/api/v1/dashboards/reopenedTickets?departmentId=4000000010712&agentId=5000000010712,5000000010713&duration=LAST_7_DAYS&groupBy=date
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "totalTicketCount" : "1",
  "avg" : "0.1",
  "ticketCount" : [ {
    "count" : "0",
    "value" : "2018-04-01",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-02",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-03",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-04",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-05",
    "referenceValue" : null
  }, {
    "count" : "1",
    "value" : "2018-04-06",
    "referenceValue" : null
  }, {
    "count" : "0",
    "value" : "2018-04-07",
    "referenceValue" : null
  } ],
  "groupedBy" : "date"
}

Domain Mapping

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.

ATTRIBUTES

Attribute Name
Data Type
Description
domain

string

Address of the domain

isVerified

boolean

Key that denotes if the domain is verified

isApplied

boolean

Key that denotes if the domain is applied to the portal

zdSecurityCode

string

Zoho Desk domain security code to add in the domain service provider's CNAME

verifiedTime

timestamp

Time of verifying the domain

appliedTime

timestamp

Time of applying the domain to the portal

verifiedBy

long

ID of user who verified the domain

appliedBy

long

ID of user who applied the domain to the portal

sslStatus

string

SSL status of the domain

sslRequestStatus

string

SSL request status of the domain if SSL certificate is requested for the domain

sslRequestedBy

long

ID of user who requested for the SSL certificate for the domain

sslRequestedTime

timestamp

Time of requesting the SSL certificate for the domain

Example

{
  "appliedTime" : null,
  "sslRequestStatus" : null,
  "sslRequestedBy" : null,
  "isVerified" : false,
  "sslStatus" : "NO_SSL",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : "zdc3b95061484994060a401652cb2a45b2",
  "sslRequestedTime" : null,
  "isApplied" : false,
  "appliedBy" : null,
  "verifiedBy" : null,
  "verifiedTime" : null
}


Add domain

This API adds a domain to your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
domain

string

required,
max chars : 46

Address of the domain

POST /api/v1/domains

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/domains
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : null,
  "sslRequestStatus" : null,
  "sslRequestedBy" : null,
  "isVerified" : false,
  "sslStatus" : "NO_SSL",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : "zdc3b95061484994060a401652cb2a45b2",
  "sslRequestedTime" : null,
  "isApplied" : false,
  "appliedBy" : null,
  "verifiedBy" : null,
  "verifiedTime" : null
}

Verify domain

This API verifies a domain in your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
domain

string

required,
max chars : 100

Domain to be verified.

method

string

required,
max chars : 100

Domain verification method. CNAME or HTML.

POST /api/v1/domains/verify

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/domains/verify
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "method" : "CNAME",
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : null,
  "sslRequestStatus" : null,
  "sslRequestedBy" : null,
  "isVerified" : true,
  "sslStatus" : "NO_SSL",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : null,
  "sslRequestedTime" : null,
  "isApplied" : false,
  "appliedBy" : null,
  "verifiedBy" : "8000000012800",
  "verifiedTime" : "2018-06-03T11:21:07.912Z"
}

Apply domain

This API maps a domain to the default portal in your help desk.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
domain

string

required,
max chars : 46

Address of the domain

POST /api/v1/domains/apply

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/domains/apply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "domain" : "support.zylker.com"
}'

Response Example

{
  "appliedTime" : "2018-06-03T11:25:07.897Z",
  "sslRequestStatus" : null,
  "sslRequestedBy" : "8000000012800",
  "isVerified" : true,
  "sslStatus" : "VALID",
  "domain" : "support.zylker.com",
  "zdSecurityCode" : null,
  "sslRequestedTime" : "2018-06-03T11:25:07.897Z",
  "isApplied" : true,
  "appliedBy" : "8000000012800",
  "verifiedBy" : "8000000012800",
  "verifiedTime" : "2018-06-03T11:21:07.912Z"
}

Reset current domain

This API resets the current domain of the default portal in your help desk.

Credit: 1 credit/call

POST /api/v1/domains/reset

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/domains/reset
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List domains

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

Query Params

Param Name
Data Type
Description
isVerified

boolean

optional

Key that filters domains based on their verification status

isApplied

boolean

optional

Key that filters domains based on their application status in the help desk

GET /api/v1/domains

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/domains?isVerified=true&isApplied=false
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "supportportal.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.912Z"
  }, {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "customers.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.654Z"
  }, {
    "appliedTime" : null,
    "sslRequestStatus" : null,
    "sslRequestedBy" : null,
    "isVerified" : true,
    "sslStatus" : "NO_SSL",
    "domain" : "partners.zylker.com",
    "zdSecurityCode" : null,
    "sslRequestedTime" : null,
    "isApplied" : false,
    "appliedBy" : null,
    "verifiedBy" : "8000000012800",
    "verifiedTime" : "2018-06-03T11:21:07.912Z"
  } ]
}

Community

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

{ }


Like topic

This API enables users to like a topic.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/like

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/like?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unlike topic

This API enables users to unlike a topic.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/unlike

OAuth Scope

Desk.forums.UPDATE , Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/unlike?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Follow topic

This API enables users to follow a topic.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/follow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/follow?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unfollow topic

This API enables users to unfollow a topic.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/unfollow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/unfollow?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Lock topic

This API helps lock a forum topic, so that further user actions are restricted.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/lock

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/lock?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unlock topic

This API helps unlock a forum topic, so that further user actions can be performed.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/unlock

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/unlock?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Moderate topic

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

POST /api/v1/communityTopics/{id}/moderate

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/moderate?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unmoderate topic

This API helps unmoderate a forum topic, which means user comments are published without reviewing.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/unmoderate

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/unmoderate?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Trash topic

This API moves a forum topic to trash of your help desk portal.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/moveToTrash?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Move topic

This API moves a forum topic from one community category to another.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
categoryId

long

required

ID of the community category

POST /api/v1/communityTopics/{id}/move

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/move?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "categoryId" : "1000000012755"
}'

Response Example

204

Associate tags to topic

This API associates quick access/reference tags to a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
tags

list

required

Tag phrases

POST /api/v1/communityTopics/{id}/associateTags

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/associateTags?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

[ {
  "name" : "tag1",
  "permalink" : "tag1"
}, {
  "name" : "tag2",
  "permalink" : "tag2"
} ]

Dissociate tags from topic

This API removes quick access/reference tags from a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
tags

list

required

Tag phrases

POST /api/v1/communityTopics/{id}/dissociateTags

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/dissociateTags?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

204

List topic followers

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

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed.

limit

int

required,
default : 10,
range : 1-100

Number of users to list

userType

string

optional,
max chars : 100

Filters based on the type of the user who follows it. The allowed values are AGENT or END_USER.

GET /api/v1/communityTopics/{id}/followers

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/followers?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

List topic participants

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

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 10,
range : 1-100

Number of users to list

userType

string

optional,
max chars : 100

Filters based on the type of the user who participated in it. The allowed values are AGENT or END_USER.

GET /api/v1/communityTopics/{id}/participants

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/participants?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

List topic voters

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

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 10,
range : 1-100

Number of users to list

userType

string

optional,
max chars : 100

Filters based on the type of the user who voted for it. The allowed values are AGENT or END_USER.

GET /api/v1/communityTopics/{id}/voters

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/voters?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

List forum topics

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

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the topics must be listed

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-50

Number of topics to list

isSticky

boolean

optional

Key that defines whether the topics to list must be sticky posts or not

unreplied

boolean

optional

Key that defines whether the topics to list must contain comments or not

type

String

optional

Type of topics to list. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

tagName

String

optional

Tag by which topics must be filtered

label

String

optional

Status 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.

sortBy

String

required,
default : modifiedTime

sort topics list by createdtime or modified time

isAscending

boolean

required,
default : false

sort topics list in ascending or decending order

startTime

date

optional

Starting time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

GET /api/v1/communityTopics

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : null,
      "type" : "AGENT"
    },
    "latestCommentTime" : "2018-10-16T09:42:12.716Z",
    "subject" : "Topic 2",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "isVoted" : true,
    "type" : "QUESTION",
    "latestCommenter" : null,
    "isSticky" : false,
    "commentCount" : "0",
    "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-2",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "latestCommentTime" : "2018-10-16T09:41:46.621Z",
    "subject" : "Topic 1",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "isVoted" : true,
    "type" : "QUESTION",
    "latestCommenter" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT"
    },
    "isSticky" : false,
    "commentCount" : "2",
    "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

Get topic

This API fetches a forum topic from the user community.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the topics. Values allowed are: seo, featuredImage and participantsCount.

GET /api/v1/communityTopics/{id}

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "type" : "QUESTION",
  "isSticky" : false,
  "bestCommentId" : null,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isTicketCreated" : false,
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "isFollowing" : false,
  "viewsCount" : "246",
  "label" : "NOSTATUS",
  "isVoted" : true,
  "commentCount" : "2",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "followersCount" : "0",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED"
}

Add topic

This API helps add a forum topic in the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

mailTo

JSONArray

optional

Email IDs to which the topic must be sent after publishing

seo

JSONObject

optional

The list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title

featuredImage

JSONObject

optional

Specifies the id of the uploaded image to display as a featured image.

POST /api/v1/communityTopics

OAuth Scope

Desk.community.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "featuredImage" : {
    "imageId" : "1000000061105"
  },
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "mailTo" : [ "carol@zylker.com" ],
  "type" : "QUESTION",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isTicketCreated" : false,
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "isFollowing" : false,
  "label" : "NOSTATUS",
  "isVoted" : true,
  "commentCount" : "2",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "followersCount" : "0",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED"
}

Update topic

This API helps update a published forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

String

optional

Title of the topic

content

String

optional

Body content of the topic

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

type

String

optional

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

label

String

optional

Status 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.

notifyMentions

boolean

optional,
default : false

whether to notify mentioned user while updateing content.

categoryId

long

optional

ID of the community category in which the topic must be posted

tags

JSONArray

optional

Tag phrases

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

seo

JSONObject

optional

The list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title

featuredImage

JSONObject

optional

Specifies the id of the uploaded image to display as a featured image.

PATCH /api/v1/communityTopics/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "featuredImage" : {
    "imageId" : "1000000061105"
  },
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>"
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isTicketCreated" : false,
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : null,
    "type" : "AGENT"
  },
  "isFollowing" : false,
  "label" : "NOSTATUS",
  "isVoted" : true,
  "commentCount" : "2",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "followersCount" : "0",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED"
}

Add comment

This API helps add a comment to a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

required,
max chars : 50000

Content of the comment

attachmentIds

JSONArray

optional

IDs of files to attach to the comment

POST /api/v1/communityTopics/{id}/comments

OAuth Scope

Desk.community.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Comment 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/comments/4000000019029/attachments/4000000019027/content?orgId=123456"
  } ],
  "replies" : [ ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "id" : "4000000019029",
  "content" : "Comment 1",
  "status" : "PUBLISHED"
}

Add reply

This API helps add a reply to a comment on a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

required,
max chars : 50000

Content of the reply

attachmentIds

JSONArray

optional

IDs of files to attach to the reply

POST /api/v1/communityTopics/{id}/comments/{id}/replies

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Reply 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/replies/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "parentCommentId" : "4000000019029",
  "id" : "4000000019031",
  "content" : "Reply 1",
  "status" : "PUBLISHED"
}

Update comment

This API helps update a published comment.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 50000

Content of the comment/reply

attachmentIds

JSONArray

optional

Ids of the attachments added for this topic

isBestComment

boolean

optional

Key that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.

notifyMentions

boolean

optional,
default : false

whether to notify mentioned user while updateing content.

PATCH /api/v1/communityTopics/{id}/comments/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Comment updated 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/comments/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "replies" : [ ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "id" : "4000000019031",
  "content" : "Comment updated 1",
  "status" : "PUBLISHED"
}

Update reply

This API helps update a published reply.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
content

string

optional,
max chars : 50000

Content of the comment/reply

attachmentIds

JSONArray

optional

Ids of the attachments added for this topic

isBestComment

boolean

optional

Key that defines whether the comment is the best comment recorded on the topic. A topic can have only on best comment.

notifyMentions

boolean

optional,
default : false

whether to notify mentioned user while updateing content.

PATCH /api/v1/communityTopics/{id}/comments/{id}/replies/{id}

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "attachmentIds" : [ "4000000019027" ],
  "content" : "Reply updated 1"
}'

Response Example

{
  "modifiedTime" : "2018-10-16T10:21:00.386Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    }
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/replies/4000000019031/attachments/4000000019027/content?orgId=123456"
  } ],
  "createdTime" : "2018-10-16T10:21:00.386Z",
  "parentCommentId" : "4000000019029",
  "id" : "4000000019031",
  "content" : "Reply updated 1",
  "status" : "PUBLISHED"
}

List topic comments

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

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 10,
range : 1-25

The end limit to list the comments

latestCommentsFirst

boolean

optional,
default : false

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).

startTime

date

optional

Starting 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 "

endTime

date

optional

Ending 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 "

GET /api/v1/communityTopics/{id}/comments

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-10-16T10:29:15.219Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ {
      "size" : "1166",
      "name" : "download (1).png",
      "id" : "4000000019033",
      "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019013/attachments/4000000019033/content?orgId=123456"
    } ],
    "replies" : [ ],
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "id" : "4000000019013",
    "content" : "<div>comment 1<br /></div>",
    "status" : "PUBLISHED"
  }, {
    "modifiedTime" : "2018-10-16T10:28:59.495Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ ],
    "replies" : [ {
      "modifiedTime" : "2018-10-16T10:22:46.893Z",
      "creator" : {
        "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
        "name" : "user 1",
        "id" : "7000000015971",
        "label" : {
          "preferences" : {
            "shape" : "RECTANGLE",
            "bgColor" : "#23F123",
            "textColor" : "#2CA123"
          },
          "name" : "Admin",
          "id" : "6000000158001",
          "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
        }
      },
      "attachments" : [ ],
      "createdTime" : "2018-10-16T10:22:46.893Z",
      "parentCommentId" : "4000000019029",
      "id" : "4000000019031",
      "content" : "test 3",
      "status" : "PUBLISHED"
    } ],
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "id" : "4000000019029",
    "content" : "<div>comment 3</div>",
    "status" : "PUBLISHED"
  } ]
}

Get topic comment

This API fetches a comment received on a topic.

Credit: 1 credit/call

GET /api/v1/communityTopics/{id}/comments/([0-9]+)

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-10-16T10:29:15.219Z",
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    }
  },
  "attachments" : [ {
    "size" : "1166",
    "name" : "download (1).png",
    "id" : "4000000019033",
    "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019013/attachments/4000000019033/content?orgId=123456"
  } ],
  "replies" : [ {
    "modifiedTime" : "2018-10-16T10:34:34.114Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      }
    },
    "attachments" : [ {
      "size" : "1166",
      "name" : "download (1).png",
      "id" : "4000000019037",
      "href" : "https://desk.zoho.com/api/v1/topics/4000000019003/comments/4000000019035/attachments/4000000019037/content?orgId=123456"
    } ],
    "createdTime" : "2018-10-16T10:34:20.858Z",
    "parentCommentId" : "4000000019013",
    "id" : "4000000019035",
    "content" : "<div>test 3<br /></div>",
    "status" : "PUBLISHED"
  } ],
  "createdTime" : "2018-10-16T09:41:40.077Z",
  "id" : "4000000019013",
  "content" : "<div>comment 1<br /></div>",
  "status" : "PUBLISHED"
}

Trash comment

This API deletes a comment from a topic.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/comments/{id}/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/moveToTrash?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Trash reply

This API deletes a reply to a topic comment.

Credit: 1 credit/call

POST /api/v1/communityTopics/{id}/comments/{id}/replies/{id}/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/replies/{id}/moveToTrash?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Add attachment

This API uploads files to the storage space allocated for the community module.

Credit: 1 credit/call

File Params

file

Content-Type:multipart/form-data

File to upload

Attributes

Param Name
Data Type
Description
source

string

required,
max chars : 100

Source of attaching Doc
zohodocs

gdrive

dropbox

box

skydrive

evernote

office365

workdrive

id

string

required,
max chars : 300

Id of the attaching Doc

name

string

required,
max chars : 300

Name of the attaching Doc

isPublic

boolean

optional

Public/Private of the attaching Doc

type

string

optional,
max chars : 300

DocType of the attaching Doc
file

presentation

pdf

document

spreadsheet

filePath

string

optional,
max chars : 300

File path of the attaching Doc (For Dropbox)

accountId

string

optional,
max chars : 300

Account Id of the Dropbox

mimeType

string

optional,
max chars : 300

Mime Type for Google Drive

POST /api/v1/communityAttachments

OAuth Scope

Desk.community.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityAttachments?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "size" : "1024",
  "name" : "attachment.jpeg",
  "id" : "1004"
}

Get unassociated attachment

Unassociated attachments are those attachments uploaded to a community topic or comment that is not yet published or saved as a draft. This API fetches an unassociated attachment from the user community.

Credit: 1 credit/call

GET /api/v1/communityAttachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityAttachments/{id}/content?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get topic attachment

This API fetches a file attachment from a topic.

Credit: 1 credit/call

GET /api/v1/communityTopics/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/attachments/{id}/content?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get comment attachment

This API fetches a file attachment from a topic comment.

Credit: 1 credit/call

GET /api/v1/communityTopics/{id}/comments/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/attachments/{id}/content?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get reply attachment

This API fetches a file attachment from a reply to a topic comment.

Credit: 1 credit/call

GET /api/v1/communityTopics/{id}/replies/{id}/attachments/{id}/content

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/replies/{id}/attachments/{id}/content?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Report topic as spam

This API marks a forum topic as spam.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
reason

String

required

Reason for marking the topic as spam

POST /api/v1/communityTopics/{id}/markSpam

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/markSpam?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reason" : "Reason for marking a topic as spam"
}'

Response Example

204

Report multiple topics as spam

This API marks multiple forum topics as spam.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

IDs of the topics that must be marked as spam

reason

String

required

Reason for marking the topic as spam

POST /api/v1/community/markAllTopicsAsSpam

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/community/markAllTopicsAsSpam?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reason" : "Reason for marking a topic as spam",
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "UNAUTHORIZED",
      "httpCode" : "401"
    }
  } ]
}

Report topic comment as spam

This API marks a comment on a forum topic as spam.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
reason

String

required

Reason for marking the topic as spam

POST /api/v1/communityTopics/{id}/comments/{id}/markSpam

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/{id}/comments/{id}/markSpam?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reason" : "Reason for marking a topic as spam"
}'

Response Example

204

Report multiple comments as spam

This API marks multiple comments on a forum topic as spam.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
commentIds

JSONArray

required

IDs of the comments that must be marked as spam

reason

String

required

Reason for marking the comment as spam

POST /api/v1/community/markAllCommentsAsSpam

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/community/markAllCommentsAsSpam?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "reason" : "Reason for marking a topic's comment as spam",
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : {
      "errorCode" : "SUCCESS",
      "httpCode" : "200"
    }
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "UNAUTHORIZED",
      "httpCode" : "401"
    }
  } ]
}

Lock category or forum

This API locks a community category or forum and restricts posting access to users.

Credit: 1 credit/call

POST /api/v1/communityCategory/([0-9]+)/lock

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/lock?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Enable category or forum

This API enables a community category or forum and provides posting access to users.

Credit: 1 credit/call

POST /api/v1/communityCategory/([0-9]+)/enable

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/enable?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Disable category or forum

This API disables a community category or forum and restricts posting access to users.

Credit: 1 credit/call

POST /api/v1/communityCategory/([0-9]+)/disable

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/disable?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Follow a category or forum

This API helps users to follow a community category or forum.

Credit: 1 credit/call

POST /api/v1/communityCategory/([0-9]+)/follow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/follow?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unfollow a category or forum

This API helps end-users unfollow a community category or forum.

Credit: 1 credit/call

POST /api/v1/communityCategory/([0-9]+)/unfollow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/unfollow?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Delete forum

This API deletes a forum from a community category. Keep in mind that only empty forums can be deleted.

Credit: 1 credit/call

DELETE /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.community.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Sort categories

This API sorts community categories in a particular order.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
categoryIds

JSONArray

required

IDs of the community categories that must be sorted

POST /api/v1/communityCategory/sort

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/sort?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "categoryIds" : [ "20628000000020011", "20628000000020012", "20628000000020013", "20628000000020014", "20628000000020015" ]
}'

Response Example

204

Sort forums

This API sorts forums in a particular order.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
categoryIds

JSONArray

required

IDs of the forums that must be sorted

POST /api/v1/communityCategory/([0-9]+)/sort

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/sort?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "categoryIds" : [ "20628000000020011", "20628000000020012", "20628000000020013", "20628000000020014", "20628000000020015" ]
}'

Response Example

204

Get category or forum

This API fetches the details of a community category or forum.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the category or forum. Values allowed are: postCount, followersCount, and commentCount.

GET /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "isFollowing" : "true",
  "visibility" : "ALL_USERS",
  "departmentId" : "20628000000020011",
  "description" : "description",
  "canAutoConvertTicket" : true,
  "childs" : [ {
    "isFollowing" : false,
    "visibility" : "ALL_USERS",
    "departmentId" : null,
    "description" : "forum 1",
    "canAutoConvertTicket" : null,
    "commentCount" : "491",
    "associatedDepartmentIds" : [ "20628000000020011" ],
    "photoUrl" : null,
    "view" : {
      "groupIds" : [ ],
      "permission" : "ALL_USERS"
    },
    "post" : {
      "groupIds" : [ ],
      "permission" : "ALL_USERS"
    },
    "permissions" : [ "POST", "RESPOND" ],
    "moderation" : null,
    "name" : "forum",
    "deparmentIdForTicketCreation" : "20628000000020011",
    "postCount" : "246",
    "parentCategoryId" : "4000000003037",
    "id" : "4000000012009",
    "position" : "1",
    "followersCount" : "38",
    "permalink" : "forum-43",
    "respond" : {
      "groupIds" : [ ],
      "permission" : "ALL_USERS"
    },
    "child" : [ ],
    "moderators" : [ ],
    "status" : "ENABLED"
  } ],
  "commentCount" : "491",
  "associatedDepartmentIds" : [ "20628000000020011" ],
  "photoUrl" : null,
  "view" : {
    "groupIds" : [ ],
    "permission" : "ALL_USERS"
  },
  "post" : {
    "groupIds" : [ ],
    "permission" : "ALL_USERS"
  },
  "permissions" : [ "POST", "RESPOND" ],
  "moderation" : "NONE",
  "name" : "new dep",
  "deparmentIdForTicketCreation" : "20628000000020011",
  "postCount" : "246",
  "parentCategoryId" : "null",
  "id" : "20628000000020011",
  "position" : "1",
  "followersCount" : "38",
  "permalink" : "new-dep",
  "respond" : {
    "groupIds" : [ ],
    "permission" : "ALL_USERS"
  },
  "status" : "ENABLED",
  "moderators" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "type" : "AGENT"
  } ]
}

Add forum

This API adds a forum in a community category.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the forum

parentCategoryId

long

optional

ID of the community category under which the forum must be added

description

String

optional

A brief description of the community category or forum

visibility

String

optional

Visibility setting of the community category or forum. Values allowed are: ALL, LOGGED_IN_USERS, GROUPS and MODERATORS.

post

JSONObject

optional

Post permission setting of the community category or forum.

respond

JSONObject

optional

Respond permission setting of the community category or forum.

moderators

JSONArray

optional

Agents who moderate the community category or forum

groupIds

JSONArray

optional

Group Ids to associate

moderation

String

optional

Moderation setting for the community category or forum. Values allowed are: NONE (no moderation), ALL_POSTS (all posts of category will be moderated) and FIRST_POST (only the first forum post of users will be moderated).

canAutoConvertTicket

boolean

optional

Key that defines whether topics posted in the forum must be automatically converted into tickets or not

associatedDepartmentIds

JSONArray

optional

IDs of the deparments to be associated with category

deparmentIdForTicketCreation

long

optional

ID of the deparment in which the ticket must be created

logoId

long

optional

ID of the uploaded community category logo

POST /api/v1/communityCategory

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityCategory?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "visibility" : "GROUPS",
  "description" : "forum 1",
  "canAutoConvertTicket" : "true",
  "associatedDepartmentIds" : [ "20628000000020011" ],
  "post" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "moderation" : "FIRST_POST",
  "groupIds" : [ "700000001671" ],
  "name" : "forum",
  "deparmentIdForTicketCreation" : "20628000000020011",
  "parentCategoryId" : "4000000003037",
  "respond" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "logoId" : "4000000012019",
  "moderators" : [ "7000000015971" ]
}'

Response Example

{
  "isFollowing" : false,
  "visibility" : "GROUPS",
  "departmentId" : "20628000000020011",
  "groups" : [ "700000001671" ],
  "description" : "forum 1",
  "canAutoConvertTicket" : "true",
  "associatedDepartmentIds" : [ "20628000000020011" ],
  "photoUrl" : "https://desk.zoho.com/api/v1/communityCategory/4000000012009/logo/4000000012019?orgId=1234567",
  "post" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "permissions" : [ "POST", "RESPOND" ],
  "moderation" : "FIRST_POST",
  "name" : "forum",
  "deparmentIdForTicketCreation" : "20628000000020011",
  "parentCategoryId" : "4000000003037",
  "id" : "4000000012009",
  "position" : "1",
  "permalink" : "forum-1",
  "respond" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "child" : [ ],
  "moderators" : [ ],
  "status" : "ENABLED"
}

List categories

This API lists a particular number of community categories.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the categories. Values allowed are: postCount, followersCount, and commentCount.

departmentId

long

optional

ID of the department for which the categories to be filtered.

GET /api/v1/communityCategory

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "categories" : [ {
    "isFollowing" : true,
    "visibility" : "LOGGED_IN_USERS",
    "departmentId" : "2000000012968",
    "description" : "category",
    "canAutoConvertTicket" : false,
    "photoUrl" : null,
    "permissions" : [ "POST", "RESPOND" ],
    "moderation" : "NONE",
    "name" : "category",
    "parentCategoryId" : null,
    "id" : "4000000000017",
    "position" : "1",
    "permalink" : "category",
    "child" : [ {
      "isFollowing" : false,
      "visibility" : null,
      "departmentId" : null,
      "description" : "Forum 1",
      "canAutoConvertTicket" : null,
      "photoUrl" : null,
      "permissions" : [ "POST", "RESPOND" ],
      "moderation" : null,
      "name" : "forum 1",
      "parentCategoryId" : "4000000000017",
      "id" : "4000000000033",
      "position" : "1",
      "permalink" : "forum-1",
      "child" : [ ],
      "moderators" : [ ],
      "status" : "ENABLED"
    } ],
    "moderators" : [ {
      "photoUrl" : null,
      "name" : "User 1",
      "id" : "2000000016079",
      "type" : "AGENT"
    } ],
    "status" : "ENABLED"
  }, {
    "isFollowing" : false,
    "visibility" : "LOGGED_IN_USERS",
    "departmentId" : null,
    "description" : "",
    "canAutoConvertTicket" : true,
    "photoUrl" : null,
    "permissions" : [ "POST", "RESPOND" ],
    "moderation" : "FIRST_POST",
    "name" : "Dep 2",
    "parentCategoryId" : null,
    "id" : "4000000002005",
    "position" : "2",
    "permalink" : "dep-2",
    "child" : [ ],
    "moderators" : [ ],
    "status" : "ENABLED"
  } ]
}

Update category or forum

This API updates the details of a category or forum.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the community category or forum

description

String

optional

A brief description of the community category or forum

visibility

String

optional

Visibility setting of the community category or forum. Values allowed are: ALL, LOGGED_IN_USERS, GROUPS , AGENTS and MODERATORS.

post

JSONObject

optional

Post permission setting of the community category or forum.

respond

JSONObject

optional

Respond permission setting of the community category or forum.

moderators

JSONArray

optional

Agents who moderate the community category or forum

groupIds

JSONArray

optional

Group Ids to associate

moderation

String

optional

Moderation setting for the community category or forum. Values allowed are: NONE (no moderation), ALL_POSTS (all posts of category will be moderated) and FIRST_POST (only the first forum post of users will be moderated).

canAutoConvertTicket

boolean

optional

Key that defines whether topics posted in the forum must be automatically converted into tickets or not

associatedDepartmentIds

JSONArray

optional

IDs of the deparments to be associated with category

deparmentIdForTicketCreation

long

optional

ID of the deparment in which the ticket must be created

logoId

long

optional

ID of the uploaded community category logo

PATCH /api/v1/communityCategory/([0-9]+)

OAuth Scope

Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityCategory/([0-9]+)?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "visibility" : "GROUPS",
  "post" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "moderation" : "FIRST_POST",
  "groupIds" : [ "700000001671" ],
  "name" : "new dep updated",
  "deparmentIdForTicketCreation" : "20628000000020011",
  "description" : "description",
  "canAutoConvertTicket" : "true",
  "respond" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "logoId" : "4000000012019",
  "moderators" : [ "7000000015971" ],
  "associatedDepartmentIds" : [ "20628000000020011" ]
}'

Response Example

{
  "isFollowing" : "false",
  "visibility" : "GROUP",
  "departmentId" : "20628000000020011",
  "description" : "description",
  "groups" : [ {
    "name" : "group - 1",
    "id" : "700000001671"
  } ],
  "canAutoConvertTicket" : true,
  "childs" : [ ],
  "associatedDepartmentIds" : [ "20628000000020011" ],
  "photoUrl" : "https://desk.zoho.com/api/v1/communityCategory/4000000012009/logo/4000000012019?orgId=1234567",
  "post" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "permissions" : [ "POST", "RESPOND" ],
  "moderation" : "FIRST_POST",
  "name" : "new dep updated",
  "deparmentIdForTicketCreation" : "20628000000020011",
  "parentCategoryId" : "null",
  "id" : "20628000000020011",
  "position" : "1",
  "permalink" : "new-dep-updated-permalink",
  "respond" : {
    "groupIds" : [ "20628000000020011" ],
    "permission" : "GROUPS"
  },
  "status" : "ENABLED",
  "moderators" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015971",
    "type" : "AGENT"
  } ]
}

List followers of category or forum

This API lists a particular number of users who follow a community category or forum, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 10,
range : 1-100

Number of users to list

userType

string

optional,
max chars : 100

to filter agent and end user

GET /api/v1/communityCategory/([0-9]+)/followers

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityCategory/([0-9]+)/followers?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 2",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT"
  } ]
}

Get topic types

This API fetches the topic types defined in the user community of your help desk portal.

Credit: 1 credit/call

GET /api/v1/communityTopicTypes

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopicTypes?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "defaultTopicType" : "QUESTION",
  "enabledTopicTypes" : [ "DISCUSSION", "ANNOUNCEMENT", "QUESTION" ],
  "disabledTopicTypes" : [ "IDEA", "PROBLEM" ]
}

Update topic type preferences

This API helps set the default topic type and enable/disable other topic types in the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
defaultTopicType

String

optional

Topic type to set as the default option in the user community. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

enabledTopicTypes

JSONArray

optional

Topic types to enable in the user community. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

PATCH /api/v1/communityTopicTypes

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityTopicTypes?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "defaultTopicType" : "QUESTION",
  "enabledTopicTypes" : [ "DISCUSSION", "ANNOUNCEMENT", "QUESTION" ]
}'

Response Example

204

Disable topic type

This API helps to disable topic types in the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
changeExisitingTopicToType

String

required

Topic type that should be applied to existing topics mapped to the disabled type. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

type

String

required

Topic type that must be disabled. Values allowed are: DISCUSSION, IDEA, PROBLEM, and QUESTION.

POST /api/v1/communityTopicTypes/disable

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopicTypes/disable?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "changeExisitingTopicToType" : "PROBLEM",
  "type" : "QUESTION"
}'

Response Example

204

Get community preferences

This API fetches the settings defined for the user community in your help desk portal.

Credit: 1 credit/call

GET /api/v1/communityPreferences

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityPreferences?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "landingPage" : "ALL_CATEGORY"
}

Set community preferences

This API helps define the settings for the user community in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
landingPage

String

required

Key that determines the content to display on the home page of the user community. Values allowed are: ALLCATEGORIES (all community categories are displayed), and RECENTPOSTS (only the latest topics in the community are displayed).

POST /api/v1/communityPreferences

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityPreferences?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "landingPage" : "ALL_CATEGORY"
}'

Response Example

204

Update user status in community

This API updates the moderation status of end-users in the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
isModerated

boolean

optional

Key that defines whether the user is moderated or not

PATCH /api/v1/communityUsers/([0-9]+)

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/communityUsers/7000000015971?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isModerated" : "true"
}'

Response Example

204

Follow user

This API helps to follow users.

Credit: 1 credit/call

POST /api/v1/communityUsers/([0-9]+)/follow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/7000000015971/follow?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Unfollow user

This API helps to unfollow users.

Credit: 1 credit/call

POST /api/v1/communityUsers/([0-9]+)/unfollow

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/7000000015971/unfollow?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Approve topics

This API helps to approve topics and publish them on the forum.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

A list of Community topic IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityTopics/approve

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/approve?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Restore trashed topics

This API restores topics from trash.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

A list of Community topic IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityTopics/restore

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/restore?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : "null"
  } ]
}

Trash unmoderated topics

This API trashes forum topics that are yet to be moderated for publishing.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

A list of Community topic IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityTopics/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/moveToTrash?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Permanently delete topics

This API permanently deletes forum topics from the trash.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

A list of Community topic IDs. A maximum of 50 IDs is allowed.

DELETE /api/v1/communityTopics

OAuth Scope

Desk.community.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/communityTopics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : "null"
  } ]
}

Unmoderate topics

This API unmoderate the moderated forum topics.The comments that are posted during moderation will be displayed to all users without under going any review.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
topicIds

JSONArray

required

A list of Community topic IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityTopics/unmoderate

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/unmoderate?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "topicIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Approve comments

This API approves comments that are pending moderation.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
commentIds

JSONArray

required

A list of Community comment IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityComments/approve

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/approve?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Restore trashed comments

This API restores comments that were trashed from forum topics.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
commentIds

JSONArray

required

A list of Community comment IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityComments/restore

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/restore?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Trash unmoderated comments

This API trashes comments that are yet to be approved for publishing on a forum topic.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
commentIds

JSONArray

required

A list of Community comment IDs. A maximum of 50 IDs is allowed.

POST /api/v1/communityComments/moveToTrash

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityComments/moveToTrash?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Permanently delete comments

This API permanently deletes comments from the trash of your help desk portal.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
commentIds

JSONArray

required

A list of Community comment IDs. A maximum of 50 IDs is allowed.

DELETE /api/v1/communityComments

OAuth Scope

Desk.community.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/communityComments?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "commentIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

List moderated users

This API lists a particular number of moderated end-users, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the users must be listed

limit

int

required,
default : 25,
range : 1-50

Number of users to list

GET /api/v1/communityModeratedUsers

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityModeratedUsers?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "id" : "7000000015971",
    "type" : "AGENT",
    "status" : "ACTIVE"
  }, {
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015974/photo?orgId=123456",
      "name" : "user 4",
      "id" : "7000000015974",
      "type" : "AGENT"
    },
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "id" : "7000000015972",
    "type" : "AGENT"
  } ]
}

Unmoderate users

This API disables moderation for end-users in the user community.

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
userIds

JSONArray

required

IDs of the users for whom moderation must be disabled

POST /api/v1/communityUsers/unmoderate

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityUsers/unmoderate?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "103417000000528003", "103417000000528006", "103417000000528008" ]
}'

Response Example

{
  "results" : [ {
    "success" : "true",
    "id" : "103417000000528003",
    "errors" : "null"
  }, {
    "success" : "true",
    "id" : "103417000000528006",
    "errors" : "null"
  }, {
    "success" : "false",
    "id" : "103417000000528008",
    "errors" : {
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

List followers of user

This API lists followers of 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

Query Params

Param Name
Data Type
Description
from

int

required,
default : 1,
range : >=1

Index number, starting from which the followers must be listed

limit

int

required,
default : 10,
range : 1-25

Number of followers to list

GET /api/v1/communityUsers/{id}/followers

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015971/followers?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT",
    "status" : "ACTIVE"
  }, {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
    "name" : "user 3",
    "id" : "7000000015972",
    "label" : {
      "preferences" : {
        "shape" : "RECTANGLE",
        "bgColor" : "#23F123",
        "textColor" : "#2CA123"
      },
      "name" : "Admin",
      "id" : "6000000158001",
      "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
    },
    "type" : "AGENT",
    "status" : "DISABLED"
  } ]
}

Get user details

This API fetches the details of an user from the community.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the user. Value allowed is stats.

GET /api/v1/communityUsers/{id}

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015971?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
  "stats" : {
    "postCount" : "35",
    "topicTypeWiseCount" : {
      "ANNOUNCEMENT" : "3",
      "IDEA" : "10",
      "DISCUSSION" : "0",
      "PROBLEM" : "2",
      "QUESTION" : "20"
    },
    "followersCount" : "1",
    "commentCount" : "24"
  },
  "name" : "user 1",
  "isModerated" : true,
  "id" : "7000000015971",
  "type" : "AGENT",
  "status" : "ACTIVE"
}

List topics by user

This API lists a particular number of topics by 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

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-25

Number of topics to list

type

String

optional

Type of topics. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

startTime

date

optional

Starting time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range in which the topics should have been created. The value must be expressed according to the GMT time zone.

GET /api/v1/communityUsers/([0-9]+)/topics

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityUsers/7000000015972/topics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "latestCommentTime" : "2018-10-16T10:42:12.716Z",
    "subject" : "Topic 2",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "type" : "QUESTION",
    "latestCommenter" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015172/photo?orgId=123456",
      "name" : "user 3",
      "id" : "7000000015172",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "commentCount" : "1",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "latestCommentTime" : "2018-10-16T09:41:33.202Z",
    "subject" : "Topic 1",
    "likeCount" : "1",
    "label" : "NOSTATUS",
    "type" : "QUESTION",
    "latestCommenter" : null,
    "commentCount" : "0",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

List comments by user

This API lists a particular number of comments by 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

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the comments must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 25,
range : 1-25

Number of comments to list

startTime

date

optional

Starting time of the time range in which the comments should have been created. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range in which the comments should have been created. The value must be expressed according to the GMT time zone.

GET /api/v1/communityUsers/([0-9]+)/comments

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/7000000015971/comments?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "Comment 1",
    "topicPeramlink" : "zoho-desk-api",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "AGENT"
    },
    "topicId" : "4000000019013",
    "subject" : "Zoho Desk API",
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "parentCommentId" : "4000000019012",
    "id" : "4000000019013",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED",
    "topicType" : "PROBLEM"
  }, {
    "summary" : "Comment 2",
    "topicPeramlink" : "zoho-desk-api-features",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "topicId" : "4000000019013",
    "subject" : "Zoho Desk API Features",
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "parentCommentId" : null,
    "id" : "4000000019029",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED",
    "topicType" : "PROBLEM"
  } ]
}

List topics pending moderation

This API lists a particular number of forum topics that are pending moderation, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 10,
range : 1-50

Number of topics to list

status

String

required

Moderation status of the topics. Values allowed are: AWAITINGAPPROVAL, SPAM, and TRASHED.

GET /api/v1/communityModeration/topics

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityModeration/topics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "label" : null,
      "type" : "AGENT"
    },
    "trashedBy" : null,
    "subject" : "Topic 2",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "type" : "QUESTION",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "AWAITINGAPPROVAL"
  }, {
    "summary" : "Topic 1 dscription",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "trashedBy" : null,
    "subject" : "Topic 1",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "type" : "QUESTION",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "AWAITINGAPPROVAL"
  } ]
}

List comments pending moderation

This API lists a particular number of comments that are pending moderation, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the comments must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the comments must be listed

limit

int

required,
default : 25,
range : 1-50

Number of comments to list

status

String

required

Moderation status of the comments. Values allowed are: AWAITINGAPPROVAL, SPAM, and TRASHED.

GET /api/v1/communityModeration/comments

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/{id}/comments?orgId=1233456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "Comment 1",
    "topicPeramlink" : "zoho-desk-api",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "topicId" : "4000000019013",
    "trashedBy" : null,
    "subject" : "Zoho Desk API",
    "createdTime" : "2018-10-16T09:41:40.077Z",
    "id" : "4000000019013",
    "categoryId" : "4000000019012",
    "status" : "AWAITINGAPPROVAL"
  }, {
    "summary" : "Comment 2",
    "topicPeramlink" : "zoho-desk-api-features",
    "modifiedTime" : "2018-10-16T10:28:59.495Z",
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 1",
      "id" : "7000000015971",
      "label" : {
        "preferences" : {
          "shape" : "RECTANGLE",
          "bgColor" : "#23F123",
          "textColor" : "#2CA123"
        },
        "name" : "Admin",
        "id" : "6000000158001",
        "logoUrl" : "https://desk.zoho.com/portal/api/publicImages/6000000158231?orgId=14132"
      },
      "type" : "END_USER"
    },
    "topicId" : "4000000019013",
    "trashedBy" : null,
    "subject" : "Zoho Desk API Features",
    "createdTime" : "2018-10-16T10:21:00.386Z",
    "id" : "4000000019029",
    "categoryId" : "4000000019012",
    "status" : "AWAITINGAPPROVAL"
  } ]
}

Draft topic

This API saves a draft of a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Types of Topics. The allowed values are:ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

seo

JSONObject

optional

The list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title

featuredImage

JSONObject

optional

Specifies the id of the uploaded image to display as a featured image.

POST /api/v1/communityTopics/saveDraft

OAuth Scope

Desk.community.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/saveDraft?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "featuredImage" : {
    "imageId" : "1000000061105"
  },
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "categoryId" : "4000000000017",
  "notifyMe" : true,
  "status" : "DRAFT"
}

Update Drafted Topic

This API helps update the draft of a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Types of Topics. The allowed values are:ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

seo

JSONObject

optional

The list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title

featuredImage

JSONObject

optional

Specifies the id of the uploaded image to display as a featured image.

PUT /api/v1/communityTopics/([0-9]+)/updateDraft

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/updateDraft?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "featuredImage" : {
    "imageId" : "1000000061105"
  },
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "type" : "QUESTION",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "categoryId" : "4000000000017",
  "notifyMe" : true,
  "status" : "DRAFT"
}

Publish topic draft

This API publishes the draft of a forum topic.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
subject

String

required

Title of the topic

permalink

String

optional

permalink of the topic to be created

content

String

required

Body content of the topic

type

String

required

Type of topic. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

categoryId

long

required

ID of the community category in which the topic must be posted

isSticky

boolean

optional

Key that defines whether the topic must be pinned to the topics list page or not

notifyMe

boolean

optional

Key that defines whether the creator of the topic must be notified about further user actions on the topic or not

attachmentIds

JSONArray

optional

IDs of files to attach to the topic

tags

JSONArray

optional

Tag phrases

mailTo

JSONArray

optional

Email IDs to which the topic must be sent after publishing

seo

JSONObject

optional

The list below includes the SEO meta tags to describe your page to appear in the search engine results. keywords, useTitleAsPageTitle, description, title

featuredImage

JSONObject

optional

Specifies the id of the uploaded image to display as a featured image.

POST /api/v1/communityTopics/([0-9]+)/publishDraft

OAuth Scope

Desk.community.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/publishDraft?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "featuredImage" : {
    "imageId" : "1000000061105"
  },
  "subject" : "Topic 1",
  "attachmentIds" : [ "4000000019027" ],
  "mailTo" : [ "carol@zylker.com" ],
  "type" : "QUESTION",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isSticky" : "false",
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "categoryId" : "4000000000017",
  "notifyMe" : "false",
  "tags" : [ "tag1", "tag2" ]
}'

Response Example

{
  "attachments" : [ {
    "size" : "1166",
    "name" : "download.png",
    "id" : "4000000019027",
    "href" : "https://desk.zoho.com/api/v1/communityTopics/4000000019003/attachments/4000000019027/content?orgId=123456"
  } ],
  "subject" : "Topic 1",
  "isModerated" : false,
  "likeCount" : "1",
  "type" : "QUESTION",
  "isSticky" : false,
  "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, Verdana, sans-serif\"><div>Topic 1 dscription<br /></div></div>",
  "bestCommentId" : null,
  "isLocked" : false,
  "createdTime" : "2018-10-16T09:41:33.202Z",
  "tag" : [ {
    "name" : "tag1",
    "permalink" : "tag1"
  }, {
    "name" : "tag2",
    "permalink" : "tag2"
  } ],
  "id" : "4000000019003",
  "viewCount" : "1",
  "seo" : {
    "keywords" : "seo,search",
    "useTitleAsPageTitle" : "true",
    "description" : "seo description",
    "title" : "seo title"
  },
  "isTicketCreated" : false,
  "creator" : {
    "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
    "name" : "user 1",
    "id" : "7000000015971",
    "type" : "AGENT"
  },
  "isFollowing" : false,
  "label" : "NOSTATUS",
  "isVoted" : true,
  "commentCount" : "2",
  "featuredImage" : {
    "imageId" : "1000000061105",
    "size" : "2048",
    "imageUrl" : "https://desk.zoho.com/portal/api/publicImages/42065000003493086?portalId=edbsnfb8166209e6d0025b777b9d90768028d52a6ee08bbb27b1e0f251800c89a48d9",
    "name" : "social_image.jpg"
  },
  "portalUrl" : "https://desk.zoho.com/portal/portalname/community/topictopic-1",
  "followersCount" : "0",
  "permalink" : "topic-1",
  "categoryId" : "4000000000017",
  "status" : "PUBLISHED",
  "notifyMe" : false
}

Delete topic draft

This API deletes a topic draft from the user community.

Credit: 1 credit/call

DELETE /api/v1/communityTopics/([0-9]+)/deleteDraft

OAuth Scope

Desk.community.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/communityTopics/([0-9]+)/deleteDraft?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get moderation stats

This API fetches statistics related to topic/comment moderation in the user community.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category for which the statistics must be fetched

GET /api/v1/communityModeration/counts

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityModeration/counts?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "awaitingApproval" : {
    "comments" : "35",
    "topic" : "25"
  },
  "moderated" : {
    "topic" : "25"
  },
  "spam" : {
    "comments" : "35",
    "topic" : "25"
  },
  "trash" : {
    "comments" : "35",
    "topic" : "25"
  }
}

List moderated topics

This API lists a particular number of moderated topics, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the topics must be fetched

from

int

required,
default : 1,
range : >=1

Index number, starting from which the topics must be listed

limit

int

required,
default : 25,
range : 1-50

Number of topics to list

GET /api/v1/communityModeratedTopics

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityModeratedTopics?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "topic 2's description",
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "subject" : "Topic 2",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "createdTime" : "2018-10-16T09:42:12.716Z",
    "id" : "4000000019017",
    "type" : "QUESTION",
    "permalink" : "topic-2",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  }, {
    "summary" : "Topic 1 dscription",
    "moderatedBy" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015972/photo?orgId=123456",
      "name" : "user 2",
      "id" : "7000000015972",
      "type" : "AGENT",
      "status" : "ACTIVE"
    },
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/portalUser/7000000015971/photo?orgId=123456",
      "name" : "user2",
      "id" : "7000000015972",
      "type" : "END_USER"
    },
    "subject" : "Topic 1",
    "moderatedOn" : "2018-10-16T09:42:12.716Z",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000019003",
    "type" : "QUESTION",
    "permalink" : "topic-1",
    "categoryId" : "4000000000017",
    "status" : "PUBLISHED"
  } ]
}

Check Permalink Availability

API to check whether the given permalink is available

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
permalink

String

required

Permalink for which the availablilty need to be checked

GET /api/v1/communityTopics/permalink/availability

OAuth Scope

Desk.community.GET

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/permalink/availability?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "available" : "true"
}

Topic voters trend

To get trend of voters of a topic

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
startTime

date

optional

Starting time of the time range for which the statistics should be fetched. The value must be expressed according to the GMT time zone.

endTime

date

optional

Ending time of the time range for which the statistics should be fetched. The value must be expressed according to the GMT time zone.

GET /api/v1/communityTopics/([0-9]+)/voters/trend

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/4000000124009/voters/trend?orgId=123456
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "topicVoterTrend" : [ {
    "date" : "May-2023",
    "count" : "0"
  }, {
    "date" : "Jun-2023",
    "count" : "0"
  }, {
    "date" : "Jul-2023",
    "count" : "0"
  }, {
    "date" : "Aug-2023",
    "count" : "0"
  }, {
    "date" : "Sep-2023",
    "count" : "1"
  } ]
}

List all Drafted Topics

This API List all Drafted Topics of the current User

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
categoryId

long

optional

ID of the community category from which the topics must be fetched

type

String

optional

Types of Topics. The allowed values are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

from

int

required,
default : 1,
range : >=0

Index from which list is retrieved and it starts from 1

limit

int

required,
default : 10,
range : 1-100

limit for listing draftedTopics

sortBy

String

required,
default : modifiedTime

sort topics list by createdtime or modified time

isAscending

boolean

required,
default : false

sort topics list in ascending or decending order

GET /api/v1/communityMyDraftedTopics

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/allCommunityCategory?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "alex carry",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "subject" : "How to change language in moblie?",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000168087",
    "type" : "QUESTION",
    "categoryId" : "7000000018007"
  }, {
    "creator" : {
      "photoUrl" : "https://desk.zoho.com/api/v1/agents/7000000015971/photo?orgId=123456",
      "name" : "john peter",
      "id" : "7000000015972",
      "type" : "AGENT"
    },
    "subject" : "How to delete draft posts?",
    "createdTime" : "2018-10-16T09:41:33.202Z",
    "id" : "4000000168087",
    "type" : "QUESTION",
    "categoryId" : "7000000018007"
  } ]
}

Get Topics Views Count

This API fetches the total count of the topics based on the selected view.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

ID of a view for which you need to get the count

categoryId

long

optional

ID of the community category from which the topics must be listed

type

String

optional

Type of topics to list. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

tagName

String

optional

Tag by which topics must be filtered

label

String

optional

Status 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.

GET /api/v1/communityTopics/count

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityTopics/count?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

Get Comments Views Count

This API fetches the total count of the comments based on the selected view.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
viewId

long

required

ID of a view for which you need to get the count

categoryId

long

optional

ID of the community category from which the topics must be listed

type

String

optional

Type of topics to list. Values allowed are: ANNOUNCEMENT, DISCUSSION, IDEA, PROBLEM, and QUESTION.

GET /api/v1/communityComments/count

OAuth Scope

Desk.community.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/communityComments/count?orgId=1234567
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : "10"
}

EmailTemplates

Templates provide the data needed to construct the modules

Example

{
  "replyToAddr" : null,
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "templateName" : "Acknowledge contact on receiving a new ticket",
  "recordType" : "tickets",
  "subject" : "[##${Cases.Request Id}##] Your ticket has been created",
  "departmentId" : "1892000000639717",
  "templateId" : "1892000000639801",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>Your ticket has been created with the ticket ID  ${Cases.Request Id} and subject  \"${Cases.Subject}\"<br> <br>Someone from our customer service team will review it and respond shortly.<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "category" : "DEFAULT_TEMPLATE",
  "fromId" : null,
  "contentType" : "richtext",
  "folderId" : "4000000007021"
}


Add Template

Add a new Template

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
templateName

string

required,
max chars : 250

The name of the Template

subject

string

required,
max chars : 1000

The Subject of the template

recordType

string

required,
max chars : 100

The recordType of the template can be contacts, accounts, tickets, products, tasks

departmentId

long

required

The department of the template

folderId

long

required

The folder of the template

fromId

string

required,
max chars : 100

The from email of the template

replyTo

string

optional,
max chars : 100

The reply to mail id

body

string

optional,
max chars : 64000

the body of the template

contentType

string

required,
max chars : 100

content type of the template

attachmentIds

list

optional

List of file attachments in the template

POST /api/v1/templates

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/templates
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "templateName" : "new Template",
  "subject" : "My Template Subject",
  "recordType" : "tickets",
  "departmentId" : "4000000007039",
  "attachmentIds" : [ 1892000000132047 ],
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>Your ticket has been created with the ticket ID  ${Cases.Request Id} and subject  \"${Cases.Subject}\"<br> <br>Someone from our customer service team will review it and respond shortly.<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "fromId" : "support@@zylker.com",
  "contentType" : "richtext",
  "folderId" : "4000000007021"
}'

Response Example

{
  "attachments" : [ {
    "size" : "8842",
    "name" : "rick.jpeg",
    "id" : "1892000000132047"
  } ],
  "recordType" : "tickets",
  "subject" : "My Template Subject",
  "departmentId" : "4000000007039",
  "templateId" : "4000000040001",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>Your ticket has been created with the ticket ID  ${Cases.Request Id} and subject  \"${Cases.Subject}\"<br> <br>Someone from our customer service team will review it and respond shortly.<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "fromId" : "newportal<support@zylker.com>",
  "folderId" : "4000000007021",
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "new Template",
  "category" : "CUSTOM_TEMPLATE",
  "contentType" : "richtext"
}

View Template

View a particular Template

Credit: 1 credit/call

GET /api/v1/templates/{template_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/templates/1892000000639846
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "attachments" : [ {
    "size" : "8842",
    "name" : "rick.jpeg",
    "id" : "1892000000132047"
  } ],
  "recordType" : "tickets",
  "subject" : "##${Cases.Request Id}##] ${Cases.Recent Comment By} has edited a comment in the ticket",
  "departmentId" : "1892000000639717",
  "templateId" : "1892000000639846",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">${Cases.Recent Comment By} has edited a comment in the ticket, #${Cases.Request Id} ${Cases.Subject}.<br> <br>${Cases.Recent Comment}<br><br>${Cases.SUPPORT_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "fromId" : null,
  "folderId" : "4000000007021",
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "1892000000639789"
  },
  "replyToAddr" : null,
  "templateName" : "Notify agent when a comment is edited",
  "category" : "CUSTOM_TEMPLATE",
  "contentType" : "richtext"
}

Update Template

Update an existing Template

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
templateName

string

optional,
max chars : 250

The name of the Template

subject

string

optional,
max chars : 1000

The Subject of the template

recordType

string

optional,
max chars : 100

The recordType of the template can be contacts, accounts, tickets, products, tasks

departmentId

long

optional

The department of the template

folderId

long

optional

The folder of the template

fromId

string

optional,
max chars : 100

The from email of the template

replyTo

string

optional,
max chars : 100

The reply to mail id

body

string

optional,
max chars : 64000

the body of the template

contentType

string

optional,
max chars : 100

content type of the template

attachmentIds

list

optional

List of file attachments in the template

PATCH /api/v1/templates/{template_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://support.zoho.com/api/v1/templates/4000000040001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "templateName" : "new Template",
  "subject" : "My New Template",
  "recordType" : "tickets"
}'

Response Example

{
  "attachments" : [ {
    "size" : "8842",
    "name" : "rick.jpeg",
    "id" : "1892000000132047"
  } ],
  "recordType" : "tickets",
  "subject" : "My New Template",
  "departmentId" : "4000000007039",
  "templateId" : "4000000040001",
  "body" : null,
  "fromId" : "newportal<support@zylker.com>",
  "folderId" : "4000000007021",
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "new Template",
  "category" : "CUSTOM_TEMPLATE",
  "contentType" : "richtext"
}

Delete Template

Delete a Template

Credit: 1 credit/call

DELETE /api/v1/templates/{template_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://support.zoho.com/api/v1/templates/4000000042009
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Listing Templates

List all Templates

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
departmentId

long

required

the corresponding department to be fetched

module

string

optional,
max chars : 100

The name of the module

from

integer

required,
default : 1,
range : 1-1000

from index, DEFAULT 1

limit

integer

required,
default : 1000,
range : 1-1000

number of templates to be retrieved Range 1-1000, DEFAULT 1000

searchStr

string

optional,
max chars : 100

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

folderId

long

optional

the corresponding folder to be fetched

GET /api/v1/templates

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/templates?departmentId=4000000007043&module=tickets?searchStr=*com*&from=1&limit=5
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "Notify contact when a comment is added",
  "recordType" : "tickets",
  "subject" : "[##${Cases.Request Id}##] ${Cases.Recent Comment By} has commented to your ticket",
  "departmentId" : "4000000007043",
  "templateId" : "4000000007111",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>${Cases.Recent Comment By} has left the following comment on your ticket, #${Cases.Request Id} ${Cases.Subject}.<br> <br>${Cases.Recent Comment}<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "category" : "DEFAULT_TEMPLATE",
  "fromId" : null,
  "contentType" : "richtext",
  "folderId" : "4000000007021"
}, {
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "Notify contact when a comment is edited",
  "recordType" : "tickets",
  "subject" : "[##${Cases.Request Id}##] ${Cases.Recent Comment By} has updated comment in your ticket",
  "departmentId" : "4000000007043",
  "templateId" : "4000000007113",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>${Cases.Recent Comment By} has updated the following comment in your ticket, #${Cases.Request Id} ${Cases.Subject}.<br> <br>${Cases.Recent Comment}<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "category" : "DEFAULT_TEMPLATE",
  "fromId" : null,
  "contentType" : "richtext",
  "folderId" : "4000000007021"
}, {
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "Notify contact when a comment is deleted",
  "recordType" : "tickets",
  "subject" : "[##${Cases.Request Id}##] ${Cases.Recent Comment By} has deleted comment in your ticket",
  "departmentId" : "4000000007043",
  "templateId" : "4000000007115",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">Dear ${Cases.Contact Name},<br> <br>${Cases.Recent Comment By} has deleted the following comment in your ticket, #${Cases.Request Id} ${Cases.Subject}.<br> <br>${Cases.Recent Comment}<br> <br>Regards,<br>${Organization.Organization Name} Support Team.<br><br>${Cases.CUSTOMER_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "category" : "DEFAULT_TEMPLATE",
  "fromId" : null,
  "contentType" : "richtext",
  "folderId" : "4000000007021"
}, {
  "folder" : {
    "folderName" : "Agent Notifications",
    "folderId" : "4000000007021"
  },
  "replyToAddr" : null,
  "templateName" : "Notify agent when a comment is deleted",
  "recordType" : "tickets",
  "subject" : "[##${Cases.Request Id}##] ${Cases.Recent Comment By} has deleted a comment in the ticket",
  "departmentId" : "4000000007043",
  "templateId" : "4000000007135",
  "body" : "<table align=\"center\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0px; background: rgb(242, 242, 242);\" width=\"100%\"><tbody><tr><td style=\"padding: 30.0px 20.0px;\" valign=\"top\"><table cellpadding=\"0\" cellspacing=\"0\" style=\"margin: 0.0px auto;\" width=\"90%\"><tbody><tr><td valign=\"top\" style=\"border: 1.0px solid rgb(218, 218, 218); background-color: #ffffff; padding: 30px;\"><div style=\"font-family: lucida grande, lucida sans, lucida sans unicode, arial, helvetica, verdana, sans-serif; font-size: 14px; line-height: 24px; font-weight: normal; color: rgb(34, 34, 34);\">${Cases.Recent Comment By} has deleted the following comment in the ticket, #${Cases.Request Id} ${Cases.Subject}.<br> <br>${Cases.Recent Comment}<br><br><br>${Cases.SUPPORT_PORTAL_BUTTON}</div> </td> </tr> <tr> <td style=\"padding-top: 5.0px;\" valign=\"top\">  </td> </tr> </tbody> </table> </td> </tr> </tbody> </table>",
  "category" : "DEFAULT_TEMPLATE",
  "fromId" : null,
  "contentType" : "richtext",
  "folderId" : "4000000007021"
} ]

Rendering a Template

Render an exisiting Template into reply

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
entityId

long

required

The id of the entity can be contact,ticket or account

Attributes

Param Name
Data Type
Description
source

String

optional

Source from which template content has to be rendered. Values can be TICKET_REPLY , NOTIFICATIONS , AUTOMATION_ALERTS , SLA

POST /api/v1/templates/{template_id}/render

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/templates/4000000042009/render?entityId=4000000032012
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "source" : "TICKET_REPLY"
}'

Response Example

{
  "attachments" : [ {
    "size" : "8842",
    "name" : "ricktwo.jpeg",
    "id" : "4000000132047"
  } ],
  "subject" : "My support Template",
  "body" : "lakshmansupport1lakshmanvignesh<a target=\"_blank\" href=\"https://support.zoho.com/support/lakshmansupport1/ShowHomePage.do#Cases/dv/51123033fe97b2f8922ba57825f2f328\">MEOW Ticket</a> newuser+1105/30/2016 09:57 AMI am containing a content"
}

Fetching placeholders

List the placeholders supported in emailTemplates

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

String

required

To get placeholders for this module.Allowed values are tickets,tasks,contacts,accounts,products,solutions,calls,events

departmentId

Long

required

To get placeholders for this departmentId

GET /api/v1/templates/placeHolders

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/templates/placeHolders?departmentId=4000000042009&module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "supportedPlaceHolders" : [ {
      "i18nFieldLabel" : "Priority",
      "fieldLabel" : "Priority",
      "placeHolder" : "${Cases.Priority}"
    }, {
      "i18nFieldLabel" : "Ticket Owner",
      "fieldLabel" : "Case Owner",
      "placeHolder" : "${Cases.Case Owner}"
    }, {
      "i18nFieldLabel" : "Status",
      "fieldLabel" : "Status",
      "placeHolder" : "${Cases.Status}"
    }, {
      "i18nFieldLabel" : "Contact Name",
      "fieldLabel" : "Contact Name",
      "placeHolder" : "${Cases.Contact Name}"
    }, {
      "i18nFieldLabel" : "Subject",
      "fieldLabel" : "Subject",
      "placeHolder" : "${Cases.Subject}"
    }, {
      "i18nFieldLabel" : "Product Name",
      "fieldLabel" : "Product Name",
      "placeHolder" : "${Cases.Product Name}"
    }, {
      "i18nFieldLabel" : "Product Name",
      "fieldLabel" : "Product Name",
      "placeHolder" : "${Cases.Product Name}"
    }, {
      "i18nFieldLabel" : "Resolution",
      "fieldLabel" : "Resolution",
      "placeHolder" : "${Cases.Resolution}"
    } ],
    "i18nModule" : "Tickets",
    "module" : "Cases"
  }, {
    "supportedPlaceHolders" : [ {
      "i18nFieldLabel" : "First Name",
      "fieldLabel" : "First Name",
      "placeHolder" : "${User.First Name}"
    }, {
      "i18nFieldLabel" : "Last Name",
      "fieldLabel" : "Last Name",
      "placeHolder" : "${User.Last Name}"
    }, {
      "i18nFieldLabel" : "Mobile",
      "fieldLabel" : "Mobile",
      "placeHolder" : "${User.Mobile}"
    } ],
    "i18nModule" : "Agent",
    "module" : "User"
  }, {
    "supportedPlaceHolders" : [ {
      "i18nFieldLabel" : "Organization Name",
      "fieldLabel" : "Organization Name",
      "placeHolder" : "${Organization.Organization Name}"
    }, {
      "i18nFieldLabel" : "Organization Logo",
      "fieldLabel" : "Organization Logo",
      "placeHolder" : "${Organization.Organization Logo}"
    }, {
      "i18nFieldLabel" : "City",
      "fieldLabel" : "City",
      "placeHolder" : "${Organization.City}"
    } ],
    "i18nModule" : "Organization",
    "module" : "Organization"
  } ]
}

Cloning a Email Template Attachments

Cloning an exisiting Template's attachments

Credit: 25 credits/call

POST /api/v1/templates/{template_id}/cloneAttachments

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://support.zoho.com/api/v1/templates/1000000013124/cloneAttachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "size" : "10247",
    "name" : "mortytwo.jpeg",
    "parentAttachmentId" : "1000000211013",
    "href" : "https://support.zoho.com/api/v1/uploads/1000000212005/content",
    "clonedAttachmentId" : "1000000212005"
  }, {
    "size" : "11682",
    "name" : "12img.png",
    "parentAttachmentId" : "1000000211015",
    "href" : "https://support.zoho.com/api/v1/uploads/1000000212007/content",
    "clonedAttachmentId" : "1000000212007"
  } ]
}

TemplateFolders

A pack of Email templates

Example

{
  "folderDesc" : "contains details",
  "modifiedOn" : null,
  "createdBy" : "4000000008688",
  "folderAccessDetails" : {
    "teams" : [ "4000000008908" ],
    "roles" : [ "4000000023688" ],
    "type" : "restrictedAccess",
    "agents" : [ "4000000008688" ]
  },
  "departmentId" : "4000000007039",
  "modifiedBy" : null,
  "folderName" : "New my Folder",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2016-06-02T04:34:42.195Z",
  "templatesCount" : [ {
    "templateType" : "SMS",
    "count" : {
      "tickets" : "19",
      "calls" : "6",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "6",
      "events" : "6",
      "products" : "0"
    }
  }, {
    "templateType" : "Email",
    "count" : {
      "tickets" : "9",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "4000000043001"
}


Adding a Template Folder

Adding a Template Folder

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
folderName

string

required,
max chars : 250

name of the template folder

folderDesc

string

optional,
max chars : 32000

the description of the folder

departmentId

long

required

the id of the department

folderAccessDetails

object

required

the access details of the folder

Post /api/v1/templateFolders

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X Post https://support.zoho.com/api/v1/templateFolders
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "folderDesc" : "contains details",
  "folderAccessDetails" : {
    "type" : "allAgents"
  },
  "departmentId" : "4000000007039",
  "folderName" : "New my Folder"
}'

Response Example

{
  "folderDesc" : "contains details",
  "modifiedOn" : null,
  "createdBy" : "4000000008688",
  "folderAccessDetails" : {
    "type" : "allAgents"
  },
  "departmentId" : "4000000007039",
  "modifiedBy" : null,
  "folderName" : "New my Folder",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2016-06-02T04:34:42.195Z",
  "folderId" : "4000000043001"
}

Getting a single Template Folder

Listing a particular Template Folder

Credit: 1 credit/call

GET /api/v1/templateFolders/{templateFolder_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/templateFolders/1892000000082079
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "type" : "allAgents"
  },
  "departmentId" : "1892000000082069",
  "modifiedBy" : null,
  "folderName" : "Public Email Templates",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "folderId" : "1892000000082079"
}

Updating a Template Folder

Updating a Template Folder

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
folderName

string

optional,
max chars : 250

name of the template folder

folderDesc

string

optional,
max chars : 32000

the description of the folder

departmentId

long

optional

the id of the department

folderAccessDetails

object

optional

the access details of the folder

PATCH /api/v1/templateFolders/{templateFolder_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://support.zoho.com/api/v1/templateFolders/4000000043001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "folderName" : "NEw Folder"
}'

Response Example

{
  "folderDesc" : "contains details",
  "modifiedOn" : "2016-06-02T04:56:34.846Z",
  "createdBy" : "4000000008688",
  "folderAccessDetails" : {
    "type" : "allAgents"
  },
  "departmentId" : "4000000007039",
  "modifiedBy" : "4000000008688",
  "folderName" : "NEw Folder",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2016-06-02T04:34:42.000Z",
  "folderId" : "4000000043001"
}

Delete Template Folder

Delete a Template Folder

Credit: 1 credit/call

DELETE /api/v1/templateFolders/{templateFolder_id}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://support.zoho.com/api/v1/templateFolders/1892000000082079?
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Listing Template Folders

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

the corresponding department to be fetched

from

integer

required,
default : 1,
range : 1-1000

from index, DEFAULT 1

limit

integer

required,
default : 1000,
range : 1-1000

number of folders to be retrieved Range 1-50, DEFAULT 50

include
see documentation

string

optional,
max chars : 100

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.

GET /api/v1/templateFolders

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/templateFolders?departmentId=11000000013068&from=1&limit=100&include=emailTemplatesCount
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "folderDesc" : null,
  "modifiedOn" : "2020-05-03T07:46:46.000Z",
  "createdBy" : "11000000038001",
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "restrictedAccess",
    "rolesAndSubordinates" : null,
    "agents" : [ "11000000038001", "11000000058011" ]
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : "11000000038001",
  "folderName" : "aaaa",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2020-05-02T22:59:52.000Z",
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "1",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000065077"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : "11000000038001",
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "restrictedAccess",
    "rolesAndSubordinates" : null,
    "agents" : [ "11000000016526", "11000000038001" ]
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "accesible by agent1",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2020-05-03T07:09:14.000Z",
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "2",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000070193"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "allAgents",
    "rolesAndSubordinates" : null,
    "agents" : null
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "Agent Notification",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "13",
      "kbCategory" : "10",
      "calls" : "4",
      "solutions" : "0",
      "accounts" : "0",
      "events" : "4",
      "tasks" : "4",
      "contacts" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000013052"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "allAgents",
    "rolesAndSubordinates" : null,
    "agents" : null
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "Contact Notification",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "9",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000013048"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "allAgents",
    "rolesAndSubordinates" : null,
    "agents" : null
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "Public SMS Templates",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "0",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000013046"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "allAgents",
    "rolesAndSubordinates" : null,
    "agents" : null
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "Secondary Contacts Notification",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "8",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000013054"
}, {
  "folderDesc" : null,
  "modifiedOn" : null,
  "createdBy" : null,
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "allAgents",
    "rolesAndSubordinates" : null,
    "agents" : null
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : null,
  "folderName" : "Team Notification",
  "category" : "DEFAULT_FOLDER",
  "createdOn" : null,
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "6",
      "calls" : "3",
      "solutions" : "0",
      "accounts" : "0",
      "events" : "3",
      "tasks" : "3",
      "contacts" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000013050"
}, {
  "folderDesc" : "tset",
  "modifiedOn" : "2020-04-30T13:09:33.000Z",
  "createdBy" : "11000000016526",
  "folderAccessDetails" : {
    "teams" : null,
    "roles" : null,
    "type" : "restrictedAccess",
    "rolesAndSubordinates" : null,
    "agents" : [ "11000000016526", "11000000038001" ]
  },
  "departmentId" : "11000000013068",
  "modifiedBy" : "11000000016526",
  "folderName" : "zzmyfolder",
  "category" : "CUSTOM_FOLDER",
  "createdOn" : "2020-04-30T10:38:15.000Z",
  "templatesCount" : [ {
    "templateType" : "Email",
    "count" : {
      "tickets" : "39",
      "calls" : "0",
      "solutions" : "0",
      "accounts" : "0",
      "contacts" : "0",
      "tasks" : "0",
      "events" : "0",
      "products" : "0"
    }
  } ],
  "folderId" : "11000000057021"
} ]

BugTracker

Bug tracker related REST API's

ATTRIBUTES

Attribute Name
Data Type
Description
description

string

description of bug

title

string

Title of Bug

projectId

long

project Id of bug to file

threadId

long

threadId

reporterEmail

string

Reporter Email

Get Linked Tickets by Bug Id

This API fetches support tickets associated with the Bug Id specified in the API request.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

GET /api/v1/bug/{bugId}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/bug/4000000003023/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

Ticket Count

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

Get ticket count

This API returns the ticket count of your help desk.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID 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. 

assigneeId

long

optional

ID of the agent assigned to resolve the ticket

contactId

long

optional

ID of the contact who raised the ticket

category

String

optional

Category of the ticket

customField1

String

optional

User-defined field in the ticket

customField2

String

optional

User-defined field in the ticket

customField3

String

optional

User-defined field in the ticket

createdTimeRange

timestamp

optional

Key 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

modifiedTimeRange

timestamp

optional

Key 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

GET /api/v1/ticketsCount

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketsCount
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "count" : 200
}

Get ticket count by field

This API returns the ticket count of your help desk, filtered by a specific field.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

ID 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. 

assigneeId

long

optional

ID of the agent assigned to resolve the ticket

contactId

long

optional

ID of the contact who raised the ticket

accountId

long

optional

ID of the account to which the ticket is mapped

category

String

optional

Category of the ticket

customField1

String

optional

User-defined field in the ticket

customField2

String

optional

User-defined field in the ticket

customField3

String

optional

User-defined field in the ticket

createdTimeRange

timestamp

optional

Key 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

modifiedTimeRange

timestamp

optional

Key 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

field

String

required

Field by which the ticket count must be filtered. Values allowed are.
status,

priority,

channel,

statusType,

spam,

escalated,

overDue

GET /api/v1/ticketsCountByFieldValues

OAuth Scope

Desk.search.READ , Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/ticketsCountByFieldValues?field=statusType,status,priority,channel,spam,overDue,escalated
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "overDue" : 2,
  "statusType" : [ {
    "count" : "13",
    "value" : "OPEN"
  }, {
    "count" : "0",
    "value" : "ONHOLD"
  }, {
    "count" : "0",
    "value" : "CLOSED"
  } ],
  "escalated" : 10,
  "channel" : [ {
    "count" : "6",
    "value" : "twitter"
  }, {
    "count" : "3",
    "value" : "forums"
  }, {
    "count" : "2",
    "value" : "chat"
  }, {
    "count" : "2",
    "value" : "web"
  } ],
  "priority" : [ {
    "count" : "8",
    "value" : "high"
  }, {
    "count" : "5",
    "value" : "medium"
  } ],
  "spam" : 10,
  "status" : [ {
    "count" : "9",
    "value" : "open"
  }, {
    "count" : "4",
    "value" : "escalated"
  } ]
}

Jira

Jira, developed by Atlassian, is one of the leading bug-tracking tools in the industry. Jira’s integration with Zoho Desk helps in instantly filing issues in Jira right from a customer support ticket in Desk. These APIs pertain to the integration between these tools.

Example

{
  "issueId" : "10010",
  "issueKey" : "SD-5",
  "componentId" : "[]",
  "reporter" : {
    "name" : "Albertjoseph",
    "key" : "admin"
  },
  "priority" : {
    "name" : "high",
    "id" : "3"
  },
  "transitionInfo" : [ {
    "issueStatusCategory" : "new",
    "issueStatus" : "Backlog",
    "transitionId" : "11"
  }, {
    "issueStatusCategory" : "done",
    "issueStatus" : "Done",
    "transitionId" : "13"
  } ],
  "issueType" : "Task",
  "deskCustomFieldId" : "customField_10366",
  "projectKey" : "SD",
  "mandatoryFields" : [ {
    "type" : "string",
    "value" : "sample",
    "key" : "labels"
  } ],
  "assignee" : {
    "name" : "Albertjoseph",
    "key" : "admin"
  },
  "ticketId" : "15433022532322",
  "issueDescription" : "TEST",
  "issueSummary" : "Boston testing"
}


Get Linked Tickets by Jira Issue Id

This API fetches support tickets associated with the Jira issue specified in the API request.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

long

optional

Start index

limit

long

optional,
range : 1-100

length of the response

GET /api/v1/jiraIssue/{issueId}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/jiraIssue/190176/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "assignee" : {
      "firstName" : "Robert",
      "lastName" : "John"
    },
    "priority" : "High",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "Smith"
    },
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

Badgification

Gamification refers to the concept of applying game-based practices, principles, and incentives for non-game activities in any environment. This is generally done in the form of providing points, virtual badges and trophies, and so on to individuals who show deep involvement in the activity. In Zoho Desk, gamification is currently available in the user community. End-customers who actively participate in community forum discussions receive badges and credits and move up from one level to the next when they fulfill certain conditions. The expected outcome of gamification in this context is more solutions from customers and lesser burden on support agents.

List badges

This API lists a particular number of 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

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

Index number starting from which the badges must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of badges to list

type

string

optional,
max chars : 100

Type of badge: default or custom

GET /api/v1/badges

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/badges
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "name" : "Badge 1",
  "isCustom" : "false",
  "description" : "Best Contributor",
  "levelName" : null,
  "id" : "1",
  "iconUrl" : "https://www.zylker.com/badge1.jpg"
} ]

Add badge

This API adds a badge to your user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the badge

description

string

optional,
max chars : 200

Description of the badge

isCustom

boolean

required

Key that specifies if the badge is user-defined or not

customIconId

int

optional

ID of the file attachment that contains the badge icon

defaultIconId

int

optional

ID of the default icon

POST /api/v1/badges

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/badges
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Badge 1",
  "isCustom" : "true",
  "description" : "Best Contributor",
  "defaultIconId" : "1"
}'

Response Example

{
  "name" : "Badge 1",
  "isCustom" : "true",
  "description" : "Best Contributor",
  "levelName" : null,
  "id" : "1",
  "iconUrl" : "https://www.zylker.com/badge1.jpg"
}

Update badge

This API updates the details of a badge.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the badge

description

string

optional,
max chars : 200

Description of the badge

customIconId

int

optional

ID of the file attachment that contains the badge icon

defaultIconId

int

optional

ID of the default icon

PUT /api/v1/badges/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/badges/3000000000010
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Badge 2",
  "description" : "Top Contributor",
  "customIconId" : "3000000000017"
}'

Response Example

{
  "name" : "Badge 2",
  "isCustom" : "true",
  "description" : "Top Contributor",
  "levelName" : null,
  "id" : "3000000000010",
  "iconUrl" : "https://www.zylker.com/badge2.jpg"
}

Delete badge

This API deletes a badge from the user community.

Credit: 1 credit/call

DELETE /api/v1/badges/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/badges/3000000000010
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List levels

This API lists a particular number of levels, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

Index number, starting from which the levels must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of limits to list

GET /api/v1/levels

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/levels
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000345",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "200",
  "name" : "Level 1",
  "description" : "Beginner",
  "id" : "3000000000335"
} ]

Add level

This API adds a level to the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the level

description

string

optional,
max chars : 200

Description of the level

badgeId

long

optional

ID of the badge to associate with the level

pointsToReach

double

required

Minimum number of credits a user needs to reach the level

POST /api/v1/levels

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/levels
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "pointsToReach" : "200",
  "badgeId" : "3000000000345",
  "name" : "Level 1",
  "description" : "Beginner"
}'

Response Example

{
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000395",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "200",
  "name" : "Level 1",
  "description" : "Beginner",
  "id" : "1"
}

Update level

This API updates the details of a level.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the level

description

string

optional,
max chars : 200

Description of the level

badgeId

long

optional

ID of the badge to associate with the level

pointsToReach

double

required

Minimum number of credits a user needs to reach the level

PUT /api/v1/levels/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/levels/3000000000345
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "pointsToReach" : "300",
  "name" : "Level 2",
  "description" : "Beginner"
}'

Response Example

{
  "badge" : {
    "name" : "Best Contributor",
    "id" : "3000000000356",
    "iconUrl" : "https://www.zylker.com/badge1.jpg"
  },
  "pointsToReach" : "300",
  "name" : "Level2",
  "description" : "Beginner",
  "id" : "3000000000345"
}

Delete level

This API deletes a level from the user community.

Credit: 1 credit/call

DELETE /api/v1/levels/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/levels/3000000000345
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List creditworthy activities

This API lists a particular number of creditworthy activities, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

Index number, starting from which the activities must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of activities to list

type

string

optional,
max chars : 100

Type of creditworthy activity: default of custom

GET /api/v1/credits

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/credits
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "isEnabled" : "true",
  "name" : "Post Idea",
  "isCustom" : "false",
  "description" : "Post an Idea to get 100 points",
  "id" : "3000000000315",
  "points" : "100"
}, {
  "isEnabled" : "true",
  "name" : "Post Question",
  "isCustom" : "false",
  "description" : "Post a Question to get 50 points",
  "id" : "3000000000320",
  "points" : "50"
} ]

Add creditworthy activity

This API adds a creditworthy activity to the user community.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the creditworthy activity

description

string

optional,
max chars : 200

Description of the creditworthy activity

points

double

required

Number of credits associated with the activity

POST /api/v1/credits

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/credits
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Custom Credit",
  "description" : "This is given to the people who have attended Webinar",
  "points" : "100"
}'

Response Example

{
  "isEnabled" : "true",
  "name" : "Custom Credit",
  "isCustom" : "true",
  "description" : "This is given to the people who have attended Webinar",
  "id" : "3000000000343",
  "points" : "100"
}

Update creditworthy activity

This API updates a creditworthy activity.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 200

Name of the creditworthy activity

description

string

optional,
max chars : 200

Description of the creditworthy activity

isEnabled

boolean

optional

Key that specifies if the activity is enabled or not

points

double

required

Number of credits associated with the activity

PUT /api/v1/credits/([0-9]+)

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PUT https://desk.zoho.com/api/v1/credits/3000000000335
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Active User",
  "description" : "This is given to the people who are active",
  "points" : "200"
}'

Response Example

{
  "isEnabled" : "true",
  "name" : "Active User",
  "isCustom" : "true",
  "description" : "This is given to the people who are highly active",
  "id" : "3000000000335",
  "points" : "200"
}

Delete creditworthy activity

This API deletes a creditworthy activity from the user community.

Credit: 1 credit/call

DELETE /api/v1/credits/([0-9]+)

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/credits/3000000000375
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

List credit holders

This API lists a particular number of users with credits, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

Index number, starting from which the users must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/credits/([0-9]+)/users

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/credits/3000000000435/users
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "users" : [ {
    "name" : "Jade Tywin",
    "id" : "3000000000485"
  }, {
    "name" : "Steve",
    "id" : "3000000000487"
  } ]
}

Add credit holders

This API adds the users specified in the request to the credit holders list.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users who must be added as credit holders

POST /api/v1/credits/([0-9]+)/associateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/credits/3000000000300/associateUsers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3000000000985", "3000000000485" ]
}'

Response Example

200

Remove credit holders

This API removes users from the custom holders list.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users who must be added as credit holders

POST /api/v1/credits/([0-9]+)/dissociateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/credits/3000000000300/dissociateUsers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3000000000885", "3000000000495", "3000000000285" ]
}'

Response Example

200

List badge holders

This API lists a particular number of users with badges, based on the limit defined.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

Integer

required,
default : 1,
range : >0

Index number, starting from which the users must be listed

limit

Integer

required,
default : 10,
range : 1-100

Number of users to list

GET /api/v1/badges/([0-9]+)/users

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/badges/3000000000185/users
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "users" : [ {
    "name" : "Jade Tywin",
    "id" : "3000000000455"
  }, {
    "name" : "Steve",
    "id" : "3000000000385"
  } ]
}

Add badge holders

This API adds the users specified in the request to the badge holders list.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users who must be added as badge holders

POST /api/v1/badges/([0-9]+)/associateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/badges/3000000000375/associateUsers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3000000000378", "3000000000395" ]
}'

Response Example

200

Remove badge holders

This API removes users from the badge holders list.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
userIds

list

required

IDs of the users who must be added as badge holders

POST /api/v1/badges/([0-9]+)/dissociateUsers

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/badges/3000000000893/dissociateUsers
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "userIds" : [ "3000000000813", "3000000000193", "3000000000903" ]
}'

Response Example

200

List available icons

This API lists all icons that are not assigned to any badges in the user community.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

GET /api/v1/availableBadgeIcons

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/availableBadgeIcons
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

[ {
  "id" : "3000000000234",
  "iconUrl" : "https://www.zylker.com/pic1.jpg"
}, {
  "id" : "3000000000722",
  "iconUrl" : "https://www.zylker.com/pic2.jpg"
} ]

HolidayList

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.

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the holiday list

holidays

list

Holidays to define in the list

status

String

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds
see documentation

list

IDs of the business hour sets associated with the holiday list

holidayListType

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)

year

Integer

The year the holiday falls in. Note: Required only when the holidayListType is set to YEAR_SPECIFIC

Example

{
  "modifiedTime" : "2018-12-03T07:16:54.223Z",
  "holidayListType" : "YEAR_SPECIFIC",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101005",
    "businessHourName" : "Dual Write OFF 2"
  }, {
    "businessHourStatus" : "INACTIVE",
    "businessHourId" : "4000000101009",
    "businessHourName" : "Dual Write OFF 3 to ON via Update"
  } ],
  "holidays" : [ {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Regional Holidays"
  }, {
    "from" : "12-05",
    "to" : "12-05",
    "holidayName" : "November Holidays"
  } ],
  "createdBy" : "4000000016079",
  "year" : "2024",
  "name" : "General HolidayList",
  "createdTime" : "2018-11-28T13:04:53.327Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000105030",
  "status" : "ACTIVE"
}


Create holiday list

This API creates a holiday list in your help desk portal

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the holiday list

holidays

list

required

Holidays to define in the list

status

String

required

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds
see documentation

list

optional

IDs of the business hour sets associated with the holiday list

holidayListType

String

optional

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)

year

Integer

optional,
range : 2000-2100

The year the holiday falls in. Note: Required only when the holidayListType is set to YEAR_SPECIFIC

POST /api/v1/holidayList

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/holidayList
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "associatedBusinessHourIds" : [ "4000000101003", "4000000101005", "4000000103001" ],
  "holidayListType" : "YEAR_SPECIFIC",
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "year" : "2024",
  "name" : "My Company Holidays",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T10:36:53.136Z",
  "holidayListType" : "YEAR_SPECIFIC",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101005",
    "businessHourName" : "Indian Night Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "year" : "2024",
  "name" : "My Company Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Get holiday list

This API fetches the details of a holiday list configured in your help desk portal

Credit: 1 credit/call

GET /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/holidayList/4000000191371
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-12-10T10:36:53.136Z",
  "holidayListType" : "RECURRING",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101005",
    "businessHourName" : "Indian Night Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "year" : null,
  "name" : "My Company Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Update holiday list

This API updates the details of a holiday list configured in your help desk portal

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the holiday list

holidays

list

optional

Holidays to define in the list

status

String

optional

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

associatedBusinessHourIds
see documentation

list

optional

IDs of the business hour sets associated with the holiday list

PATCH /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/holidayList/6000000045009
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "associatedBusinessHourIds" : [ "4000000101003", "4000000103001" ],
  "name" : "My Holidays"
}'

Response Example

{
  "modifiedTime" : "2018-12-10T10:44:46.247Z",
  "holidayListType" : "RECURRING",
  "associatedBusinessHours" : [ {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000101003",
    "businessHourName" : "UK Day Shift"
  }, {
    "businessHourStatus" : "ACTIVE",
    "businessHourId" : "4000000103001",
    "businessHourName" : "UK Night Shift"
  } ],
  "holidays" : [ {
    "from" : "02-20",
    "to" : "02-21",
    "holidayName" : "Holiday1"
  }, {
    "from" : "03-26",
    "to" : "03-26",
    "holidayName" : "Holiday2"
  }, {
    "from" : "12-24",
    "to" : "12-25",
    "holidayName" : "Christmas Holidays"
  } ],
  "createdBy" : "4000000016079",
  "year" : null,
  "name" : "My Holidays",
  "createdTime" : "2018-12-10T10:36:53.136Z",
  "modifiedBy" : "4000000016079",
  "id" : "4000000191371",
  "status" : "ACTIVE"
}

Delete holiday list

This API deletes a holiday list from your help desk portal

Credit: 1 credit/call

DELETE /api/v1/holidayList/{holidayListId}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/holidayList/4000000191371
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List holiday lists

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the holiday lists must be listed

limit

integer

optional,
range : 1-50

Number of holiday lists to list

status

String

optional

Activation status of the holiday list. Values allowed are ACTIVE and INACTIVE

GET /api/v1/holidayList

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/holidayList
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-12-10T10:48:48.772Z",
    "holidayListType" : "RECURRING",
    "associatedBusinessHours" : [ {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000101003",
      "businessHourName" : "UK Day Shift"
    }, {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000103001",
      "businessHourName" : "UK Night Shift"
    }, {
      "businessHourStatus" : "ACTIVE",
      "businessHourId" : "4000000101005",
      "businessHourName" : "Indian Night Shift"
    } ],
    "createdBy" : "4000000016079",
    "year" : null,
    "name" : "My Company Holidays",
    "createdTime" : "2018-12-10T10:48:48.772Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000191456",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2018-12-10T10:35:36.071Z",
    "holidayListType" : "YEAR_SPECIFIC",
    "associatedBusinessHours" : [ ],
    "createdBy" : "4000000016079",
    "year" : "2024",
    "name" : "My Holidays",
    "createdTime" : "2018-12-10T10:35:36.071Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000191337",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2018-12-04T14:56:17.481Z",
    "holidayListType" : "RECURRING",
    "associatedBusinessHours" : [ ],
    "createdBy" : "4000000016079",
    "year" : null,
    "name" : "Overlapping Holidays",
    "createdTime" : "2018-12-03T13:27:30.454Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000117001",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2018-12-03T07:16:54.223Z",
    "holidayListType" : "YEAR_SPECIFIC",
    "associatedBusinessHours" : [ {
      "businessHourStatus" : "INACTIVE",
      "businessHourId" : "4000000101009",
      "businessHourName" : "Indian Shift"
    } ],
    "createdBy" : "4000000016079",
    "year" : "2026",
    "name" : "General HolidayList",
    "createdTime" : "2018-11-28T13:04:53.327Z",
    "modifiedBy" : "4000000016079",
    "id" : "4000000105030",
    "status" : "ACTIVE"
  } ]
}

Notification

Notifications are automated messages that alert end-users, including contacts and agents, of any support-related activities or updates

ATTRIBUTES

Attribute Name
Data Type
Description
departmentId
see documentation

Long

ID of the department in which the notification is configured

departmentName

String

Name of the department in which the notification is configured

channel

String

Channel through which the ticket was received

ticketNumber

String

Serial number of the ticket in the help desk portal

ticketId

Long

ID of the ticket

subject

String

Subject of the ticket

threadId

Long

ID of the thread

errorMessage

String

Error message in the email delivery failure thread

reason

String

Reason for email delivery failure

assignee

object

Agent assigned to resolve the ticket

requester

object

Details of user who requested for the approval

description

String

Description of the approval

Example

{
  "departmentName" : "Sales",
  "threadId" : "4000002350527",
  "requester" : {
    "firstName" : "",
    "lastName" : "Smith",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
    "id" : "5000000012902",
    "email" : null
  },
  "ticketNumber" : "102",
  "reason" : "452 4.3.1 Temporary System Error",
  "subject" : "zPhone not working",
  "departmentId" : "4000000019077",
  "channel" : "EMAIL",
  "errorMessage" : "Error while processing the request! Unable to send message;",
  "assignee" : {
    "firstName" : "John",
    "lastName" : "Carol",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
    "id" : "1892000000056007",
    "email" : "carol@zylker.com"
  },
  "ticketId" : "4000000014345"
}


List email delivery failure alerts

This API lists the email delivery failure alerts configured in a particular department.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
department

String

required

ID of the department from which the email delivery failure alerts must be fetched. You can pass a specific department ID or allDepartment in the API request.

from

Integer

optional

Index number, starting from which the alerts must be listed

limit

Integer

optional,
range : 1-50

Number of alerts to list

GET /api/v1/emailFailureAlerts

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/emailFailureAlerts?department=1892000000056007&from=1&limit=20
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "departmentName" : "Sales",
    "threadId" : "4000002350527",
    "ticketNumber" : "102",
    "reason" : "452 4.3.1 Temporary System Error",
    "subject" : "zPhone not working",
    "departmentId" : "4000000019077",
    "channel" : "EMAIL",
    "errorMessage" : "Error while processing the request! Unable to send message;",
    "assignee" : {
      "firstName" : "John",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "ticketId" : "4000000014345"
  }, {
    "departmentName" : "Marketing",
    "threadId" : "4000002353427",
    "ticketNumber" : "102",
    "reason" : "Email reply failed from being sent! Momentary issues with the mail server, Try resending this email again.",
    "subject" : "zPhone not working",
    "departmentId" : "4000000019067",
    "channel" : "TWITTER",
    "errorMessage" : "null",
    "assignee" : {
      "firstName" : "John",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "ticketId" : "4000000014335"
  } ]
}

Clear email delivery failure alerts

This API deletes all email delivery failure alerts configured in a particular department.

Credit: 25 credits/call

Query Params

Param Name
Data Type
Description
department

String

required

ID of the department from which the email delivery failure alerts must be deleted. You can pass a specific department ID or allDepartment in the API request

PATCH /api/v1/emailFailureAlerts

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/emailFailureAlerts?department=1892000000056007
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Get my pending approvals

This API lists the pending approvals for a given user

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the pending approvals for a give user must be fetched.

department

String

required

ID of the department from which pending approvals must be fetched. You can pass a specific department ID or allDepartment in the API request.

limit

integer

required,
default : 10,
range : 1-100

Number of pending approvals to list

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: createdTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

GET /api/v1/myPendingApprovals

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/myPendingApprovals?department=1892000000056007&from=10&limit=20
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "myPendingApprovals" : [ {
    "departmentName" : "Sales",
    "requester" : {
      "firstName" : "",
      "lastName" : "Smith",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012902/photo",
      "id" : "5000000012902",
      "email" : null
    },
    "ticketNumber" : "102",
    "subject" : "Sample subject",
    "departmentId" : "4000000019077",
    "createdTime" : "2019-06-21T13:16:14.000Z",
    "description" : "Sample description",
    "id" : "4000002350527",
    "ticketId" : "4000002350527"
  }, {
    "departmentName" : "Marketing",
    "requester" : {
      "firstName" : "",
      "lastName" : "John",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/5000000012932/photo",
      "id" : "5000000012932",
      "email" : null
    },
    "ticketNumber" : "102",
    "subject" : "Sample subject",
    "departmentId" : "4000000019067",
    "createdTime" : "2019-06-21T13:16:14.000Z",
    "description" : "",
    "id" : "4000002350527",
    "ticketId" : "4000000014335"
  } ],
  "assignee" : {
    "firstName" : "John",
    "lastName" : "Carol",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo",
    "id" : "1892000000056007",
    "email" : "carol@zylker.com"
  }
}

Data Sharing Rules

Data sharing rules refer to user permissions related to viewing and/or editing resources in the different modules in Zoho Desk.

ATTRIBUTES

Attribute Name
Data Type
Description
contracts

string

Data sharing rules related to SLA contracts

tickets

string

Data sharing rules related to tickets

contacts

string

Data sharing rules related to contacts

accounts

string

Data sharing rules related to accounts

products

string

Data sharing rules related to products

tasks

string

Data sharing rules related to tasks

calls

string

Data sharing rules related to calls

events

string

Data sharing rules related to events

cm_[a-zA-Z0-9_]+

string

Data sharing rules related to custom module

Example

{
  "tickets" : "public",
  "calls" : "public read only",
  "accounts" : "public read only",
  "contracts" : "private",
  "contacts" : "public",
  "tasks" : "private",
  "events" : "public",
  "products" : "public"
}


Get data sharing rules

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

GET /api/v1/dataSharingRules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/dataSharingRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "tickets" : "public",
  "calls" : "public read only",
  "accounts" : "public read only",
  "contracts" : "private",
  "contacts" : "public",
  "tasks" : "private",
  "events" : "public",
  "products" : "public"
}

Update data sharing rules

This API updates the data sharing rules configured in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
contracts

string

optional,
max chars : 100

Data sharing rules related to SLA contracts

tickets

string

optional,
max chars : 100

Data sharing rules related to tickets

contacts

string

optional,
max chars : 100

Data sharing rules related to contacts

accounts

string

optional,
max chars : 100

Data sharing rules related to accounts

products

string

optional,
max chars : 100

Data sharing rules related to products

tasks

string

optional,
max chars : 100

Data sharing rules related to tasks

calls

string

optional,
max chars : 100

Data sharing rules related to calls

events

string

optional,
max chars : 100

Data sharing rules related to events

cm_[a-zA-Z0-9_]+

string

optional,
max chars : 100

Data sharing rules related to custom module

PATCH /api/v1/dataSharingRules

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/dataSharingRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "tickets" : "public",
  "calls" : "public read only",
  "accounts" : "public read only",
  "contracts" : "private",
  "contacts" : "public",
  "tasks" : "private",
  "events" : "public",
  "products" : "public"
}'

Response Example

204

Finance

Finance related REST API's

Update estimate status

This will update status of estimate.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
status

string

optional,
max chars : 100

status to be updated

PATCH /api/v1/zohoFinance/{financeService}/estimates/{id}

OAuth Scope

Desk.integrations.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/zohoFinance/books/estimates/1332784000000108001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "status" : "draft"
}'

Response Example

204

List invoices

To list invoices.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
deskEntityId

long

optional

To fetch invoice by desk contact or account or ticket id

deskModuleName

String

required

Desk Module Name: Contacts or Cases or Accounts

departmentId

long

optional

Department Id

status

string

optional,
max chars : 100

To fetch invoice by status, Available status are sent, draft, overdue, paid, void, unpaid, partially_paid and viewed

pageNumber

integer

optional

page number

GET /api/v1/zohoFinance/{financeService}/invoices

OAuth Scope

Desk.integrations.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/zohoFinance/books/invoices
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "deskEntityId" : "5000000014010",
  "data" : [ {
    "date" : "2018-09-23",
    "total" : 117,
    "isViewdByClient" : false,
    "totalFormatted" : "AED117.00",
    "invoiceNumber" : "INV-000025",
    "id" : "1332784000000108001",
    "dateFormatted" : "23 Sep 2018",
    "currencyCode" : "AED",
    "statusFormatted" : "Draft",
    "status" : "draft"
  } ],
  "deskModuleName" : "Contacts"
}

Update invoice status

This will update status of invoice.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
status

string

optional,
max chars : 100

status to be updated

PATCH /api/v1/zohoFinance/{financeService}/invoices/{id}

OAuth Scope

Desk.integrations.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/zohoFinance/books/invoices/1332784000000108001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "status" : "draft"
}'

Response Example

204

MarkAllInvoicesSent

This will update status of invoice to sent.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

JSONArray

optional

id of the invoice or estimate

POST /api/v1/zohoFinance/{financeService}/invoices/markAsSent

OAuth Scope

Desk.integrations.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/zohoFinance/books/invoices/markAsSent
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "1332784000000108001", "1332784000000108004", "1332784000000108006" ]
}'

Response Example

204

List estimates

To list estimates.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
deskEntityId

long

optional

To fetch estimates by desk contact or account or ticket id

deskModuleName

String

required

Desk Module Name. allowed modules are Contacts, Cases, Accounts

status

string

optional,
max chars : 100

To fetch estimates by status, Available status are draft, sent, invoiced , accepted, declined and expired

pageNumber

integer

optional

page number

GET /api/v1/zohoFinance/{financeService}/estimates

OAuth Scope

Desk.integrations.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/zohoFinance/books/estimates
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "deskEntityId" : "5000000014010",
  "data" : [ {
    "date" : "2018-09-23",
    "total" : 117,
    "isViewdByClient" : false,
    "estimateNumber" : "INV-000025",
    "totalFormatted" : "AED117.00",
    "id" : "1332784000000108001",
    "dateFormatted" : "23 Sep 2018",
    "currencyCode" : "AED",
    "statusFormatted" : "Draft",
    "status" : "draft"
  } ],
  "deskModuleName" : "Contacts"
}

Get tickets for invoices

To get associated tickets for invoice id.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

GET /api/v1/finance/invoices/{id}/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/finance/invoices/7388387778738/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "123",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : "2018-06-21T16:16:16.000Z",
    "id" : "104202000003153007",
    "assignee" : {
      "firstName" : "Robert",
      "lastName" : "John"
    },
    "priority" : "High",
    "status" : "Open",
    "commentCount" : "5"
  }, {
    "ticketNumber" : "456",
    "subject" : "Problem while reset password.",
    "dueDate" : "2018-07-21T16:16:16.000Z",
    "id" : "104202000003153015",
    "assignee" : {
      "firstName" : "Steve",
      "lastName" : "Smith"
    },
    "priority" : "High",
    "status" : "Closed",
    "commentCount" : "3"
  } ]
}

agentAvailability

Agent availability refers to your support agents' presence for responding to customers.

Update Agent Availability Configuration

This API updates the agent availability setting configured in your help desk portal.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
treatIdleAgentsAsOffline

boolean

optional

Key that specifies if idle agents should be marked as offline after a particular duration.

agentIdleTime

int

optional,
range : 1-540

Duration after which idle agents should be marked as offline. The value can range from 1 to 540.

POST /api/v1/agentAvailabilityConfig

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agentAvailabilityConfig
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentIdleTime" : "30",
  "treatIdleAgentsAsOffline" : true
}'

Response Example

204

Get Agent Availability Configuration

This API fetches the agent availability setting configured in your help desk portal.

Credit: 1 credit/call

GET /api/v1/agentAvailabilityConfig

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agentAvailabilityConfig
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "agentIdleTime" : "30",
  "treatIdleAgentsAsOffline" : true
}

Get Current Availability

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 50,
range : 1-50

Number of agents to list. The default and the maximum value allowed is 50.

from

integer

required,
default : 0,
range : 1-5999

Index number, starting from which the agents must be fetched. The default value is 0 and the maximum value allowed is 5999.

GET api/v1/agentAvailability

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agentAvailability?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "OFFLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "OFFLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "OFFLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

Get Online Agents

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 20,
range : 1-6000

Number of agents to list. The default value is 20 and the maximum value allowed is 6000.

GET api/v1/onlineAgents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/onlineAgents?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "ONLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "ONLINE",
    "status" : "ONLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

Get Offline Agents

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

ID of the department from which the availability details should be fetched. To include all accessible departments, pass the value of this key as -1.

include

String

optional

Key that includes additional, channel-specific information. Values allowed are: mailStatus, phoneStatus, phoneMode, chatStatus, and presenceStatus.

limit

integer

required,
default : 20,
range : 1-6000

Number of agents to list. The default value is 20 and the maximum value allowed is 6000.

GET api/v1/offlineAgents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/offlineAgents?orgId=2389290&departmentid=892000000008634&include=mailStatus,phoneStatus,chatStatus,phoneMode,presenceStatus
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "chatStatus" : "ONLINE",
    "agentId" : "892000000008734",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "OFFLINE",
    "status" : "OFFLINE"
  }, {
    "chatStatus" : "ONLINE",
    "agentId" : "8920000000056010",
    "phoneMode" : "WEB",
    "phoneStatus" : "ONLINE",
    "mailStatus" : "OFFLINE",
    "presenceStatus" : "OFFLINE",
    "status" : "OFFLINE"
  } ],
  "totalAgentsCount" : "2",
  "hasMore" : false
}

AutomationFeatureCount

A Common API to get various limits for Automation Features.

Example

{
  "featureName" : "workflows",
  "maxTotalCount" : "40",
  "maxActiveCount" : "20",
  "usedCountInfo" : {
    "usedTotalCount" : "3",
    "usedActiveCount" : "2"
  }
}


Get Automation Feature Count

This API is used to Get Automation Feature Limits, For BusinessHours and HoldiayList, There are no mandatory params, For Workflows valid and mandatory params are module and departmentId, Valid module param values for Workflows are tickets,contacts,contracts,accounts,tasks,products,timeEntry. For Skills and SkillTye departmentId is mandatory param

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Department Id

module

String

optional

Module, allowed values tickets,contacts,contracts,accounts,tasks,products,timeEntry,events,calls,customModule

feature

String

required

Feature, allowed values businesshours,holidaylist,Skills,SkillType,workflows,blueprints,automationAlerts,fieldUpdates,automationTasks,customFunctions

GET /api/v1/automationFeatureCount

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/automationFeatureCount?departmentId=1000000013248&module=tickets&feature=workflows
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "featureName" : "workflows",
  "maxTotalCount" : "40",
  "maxActiveCount" : "20",
  "usedCountInfo" : {
    "usedTotalCount" : "3",
    "usedActiveCount" : "2"
  }
}

Skills

Skills, They are area of expertises which can be mapped with Tickets and Agents

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the skill

description

String

description of the skill

status

String

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

ID of the Skill Type

criteria

list

The criteria details for the skill

agentIds

list

IDs of the agents mapped with the skill

Example

{
  "modifiedTime" : "2020-07-23T13:03:12.994Z",
  "agentIds" : [ "1000000000059" ],
  "skillType" : {
    "skillTypeId" : "1000000173001",
    "skillTypeName" : "Country"
  },
  "orderId" : "2",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "Russia" ],
      "condition" : "is",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "Russia" ]
    }, {
      "displayValue" : [ "987532114" ],
      "condition" : "is",
      "fieldName" : "Phone",
      "fieldModule" : "tickets",
      "value" : [ "987532114" ]
    } ],
    "pattern" : "(1or2)"
  },
  "departmentId" : "1000000013248",
  "description" : "Country is Russia",
  "skillTypeId" : "1000000173001",
  "createdBy" : "1000000000059",
  "name" : "Russia",
  "createdTime" : "2020-07-23T13:03:12.994Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173047",
  "status" : "ACTIVE"
}


Create skill

This API Creates a skill

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the skill

description

String

optional

description of the skill

status

String

required

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

required

ID of the Skill Type

criteria

list

required

The criteria details for the skill

agentIds

list

optional

IDs of the agents mapped with the skill

POST /api/v1/skills

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/skills
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skillTypeId" : "1000000173001",
  "criteria" : {
    "fieldConditions" : [ {
      "condition" : "is",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "India" ]
    }, {
      "condition" : "is",
      "fieldName" : "Phone",
      "fieldModule" : "tickets",
      "value" : [ "987532114" ]
    } ],
    "pattern" : "(1or2)"
  },
  "name" : "India",
  "description" : "Country is India",
  "status" : "ACTIVE"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:44:42.574Z",
  "agentIds" : [ ],
  "skillType" : {
    "skillTypeId" : "1000000173001",
    "skillTypeName" : "Country"
  },
  "orderId" : "1",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "India" ],
      "condition" : "is",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "India" ]
    }, {
      "displayValue" : [ "987532114" ],
      "condition" : "is",
      "fieldName" : "Phone",
      "fieldModule" : "tickets",
      "value" : [ "987532114" ]
    } ],
    "pattern" : "(1or2)"
  },
  "departmentId" : "1000000013248",
  "description" : "Country is India",
  "skillTypeId" : "1000000173001",
  "createdBy" : "1000000000059",
  "name" : "India",
  "createdTime" : "2020-07-23T12:44:42.574Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173029",
  "status" : "ACTIVE"
}

View skill

This API Gets the details of a skill

Credit: 1 credit/call

GET /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skills/1000000173145
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-23T13:08:36.093Z",
  "agentIds" : [ "1000000000059" ],
  "skillType" : {
    "skillTypeId" : "1000000173013",
    "skillTypeName" : "Language"
  },
  "orderId" : "5",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "Malayalam" ],
      "condition" : "contains",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "Malayalam" ]
    } ],
    "pattern" : "1"
  },
  "departmentId" : "1000000013248",
  "description" : "Language is Malayalam",
  "skillTypeId" : "1000000173013",
  "createdBy" : "1000000000059",
  "name" : "Malayalam",
  "createdTime" : "2020-07-23T13:08:36.093Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173145",
  "status" : "ACTIVE"
}

Update skill

This API Updates a skill

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the skill

description

String

optional

description of the skill

status

String

optional

Values allowed are ACTIVE and INACTIVE

skillTypeId

long

optional

ID of the Skill Type

criteria

list

optional

The criteria details for the skill

agentIds

list

optional

IDs of the agents mapped with the skill

PATCH /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/skills/1000000173145
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Malayalam",
  "description" : "Malayali"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T13:08:36.093Z",
  "agentIds" : [ "1000000000059" ],
  "skillType" : {
    "skillTypeId" : "1000000173013",
    "skillTypeName" : "Language"
  },
  "orderId" : "5",
  "criteria" : {
    "fieldConditions" : [ {
      "displayValue" : [ "Malayalam" ],
      "condition" : "contains",
      "fieldName" : "Subject",
      "fieldModule" : "tickets",
      "value" : [ "Malayalam" ]
    } ],
    "pattern" : "1"
  },
  "departmentId" : "1000000013248",
  "description" : "Malayali",
  "skillTypeId" : "1000000173013",
  "createdBy" : "1000000000059",
  "name" : "Malayalam",
  "createdTime" : "2020-07-23T13:08:36.093Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173145",
  "status" : "ACTIVE"
}

Delete skill

This API deletes a skill from your help desk portal

Credit: 1 credit/call

DELETE /api/v1/skills/{skillId}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/skills/6000000033001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List all skills

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department Id

from

integer

optional

Index number, starting from which the skills must be listed

limit

integer

optional,
range : 1-100

Number of skill to list, allowed minimum value 1, maximum value 100,default is 100

status

String

optional

Active inactive filter for Skills. Values allowed are ACTIVE and INACTIVE

searchString

String

optional

Search string, Used to filter skills by name starting with this string

skillTypeId

long

optional

Skill Type Id, to Filter Skills by SkillType

skillIds

long

optional

The IDs of the skills to list separated by commas. You can pass upto 50 IDs.

GET /api/v1/skills

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skills?departmentId=1000000013248
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-07-23T12:44:42.574Z",
    "agentIds" : [ ],
    "skillType" : {
      "skillTypeId" : "1000000173001",
      "skillTypeName" : "Country"
    },
    "orderId" : "1",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "India" ],
        "condition" : "is",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "India" ]
      }, {
        "displayValue" : [ "987532114" ],
        "condition" : "is",
        "fieldName" : "Phone",
        "fieldModule" : "tickets",
        "value" : [ "987532114" ]
      } ],
      "pattern" : "(1or2)"
    },
    "departmentId" : "1000000013248",
    "description" : "Country is India",
    "skillTypeId" : "1000000173001",
    "createdBy" : "1000000000059",
    "name" : "India",
    "createdTime" : "2020-07-23T12:44:42.574Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173029",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:03:12.994Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173001",
      "skillTypeName" : "Country"
    },
    "orderId" : "2",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Russia" ],
        "condition" : "is",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Russia" ]
      }, {
        "displayValue" : [ "987532114" ],
        "condition" : "is",
        "fieldName" : "Phone",
        "fieldModule" : "tickets",
        "value" : [ "987532114" ]
      } ],
      "pattern" : "(1or2)"
    },
    "departmentId" : "1000000013248",
    "description" : "Country is Russia",
    "skillTypeId" : "1000000173001",
    "createdBy" : "1000000000059",
    "name" : "Russia",
    "createdTime" : "2020-07-23T13:03:12.994Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173047",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:07:51.838Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "3",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "English" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "English" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Language is English",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "English",
    "createdTime" : "2020-07-23T13:07:51.838Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173097",
    "status" : "ACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:08:16.891Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "4",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Tamil" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Tamil" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Language is Tamil",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "Tamil",
    "createdTime" : "2020-07-23T13:08:16.891Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173121",
    "status" : "INACTIVE"
  }, {
    "modifiedTime" : "2020-07-23T13:08:36.093Z",
    "agentIds" : [ "1000000000059" ],
    "skillType" : {
      "skillTypeId" : "1000000173013",
      "skillTypeName" : "Language"
    },
    "orderId" : "5",
    "criteria" : {
      "fieldConditions" : [ {
        "displayValue" : [ "Malayalam" ],
        "condition" : "contains",
        "fieldName" : "Subject",
        "fieldModule" : "tickets",
        "value" : [ "Malayalam" ]
      } ],
      "pattern" : "1"
    },
    "departmentId" : "1000000013248",
    "description" : "Malayali",
    "skillTypeId" : "1000000173013",
    "createdBy" : "1000000000059",
    "name" : "Malayalam",
    "createdTime" : "2020-07-23T13:08:36.093Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173145",
    "status" : "ACTIVE"
  } ]
}

List associated automation rules

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the related rules must be listed

limit

integer

optional,
range : 1-100

Number of rules to list, allowed minimum value 1, maximum value 100,default is 100

GET /api/v1/skills/{skillId}/relatedRules

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skills/10000000317019/relatedRules
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ruleType" : "SUPERVISE",
    "ruleName" : "TBA1",
    "ruleId" : "6000000019012"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Priority-based SLAs",
    "ruleId" : "6000000013508"
  }, {
    "ruleType" : "SLA",
    "ruleName" : "Bronze SLAs",
    "ruleId" : "6000000013514"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Default Blueprint",
    "ruleId" : "6000000016083"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "BH BP",
    "ruleId" : "6000000018143"
  }, {
    "ruleType" : "BLUEPRINT",
    "ruleName" : "Third Bp",
    "ruleId" : "6000000023018"
  } ]
}

Reorder Skills in a Department

This API lists reorders Skills in a Department

Credit: 1 credit/2 records

Attributes

Param Name
Data Type
Description
skillIds

JSONArray

required

List of skill ids to reorder

departmentId

long

required

department of the skills to be reordered

POST /api/v1/skills/order

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/skills/order
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skillIds" : [ "1000000173121", "1000000173029", "1000000173047", "1000000173097", "1000000173145" ],
  "departmentId" : "1000000013248"
}'

Response Example

204

Get Skills of an Agent

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

Query Params

Param Name
Data Type
Description
departmentIds

long

required

list of Department Ids separated by commas,Maximum 10 department ids allowed

GET /api/v1/agents/{agentId}/skills

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/agents/1000000003234/skills?departmentIds=10000000030987,10000000038722,10000000030294
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "associatedSkills" : [ {
      "skillName" : "French",
      "skillId" : "1000000005432",
      "skillTypeId" : "1000000019013"
    }, {
      "skillName" : "Blueprint",
      "skillId" : "10000000036323",
      "skillTypeId" : "1000000019025"
    }, {
      "skillName" : "Reports",
      "skillId" : "10000000036323",
      "skillTypeId" : "1000000019025"
    } ],
    "departmentId" : "10000000030987"
  }, {
    "associatedSkills" : [ {
      "skillName" : "Workflow",
      "skillId" : "1000000005432",
      "skillTypeId" : "1000000019089"
    }, {
      "skillName" : "English",
      "skillId" : "10000000036323",
      "skillTypeId" : "100000001342"
    } ],
    "departmentId" : "10000000038722"
  }, {
    "associatedSkills" : [ {
      "skillName" : "Malayalam",
      "skillId" : "1000000059234",
      "skillTypeId" : "100000001421"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000003967",
      "skillTypeId" : "100000001423"
    } ],
    "departmentId" : "10000000030294"
  } ]
}

Map Skills in a Department with an Agent

This API modifies skills mapped for an agent in a department

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

required

ID of the Department

skillIds

list

optional

Ids of skills to be mapped

POST /api/v1/agents/{agentId}/mapSkills

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/agents/1000000000059/mapSkills?orgId=15157826
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "skillIds" : [ "1000000173047", "1000000173121", "1000000173029" ],
  "departmentId" : "1000000013248"
}'

Response Example

{
  "data" : [ {
    "associatedSkills" : [ {
      "skillName" : "India",
      "skillId" : "1000000173029",
      "skillTypeId" : "1000000173001"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000173121",
      "skillTypeId" : "1000000173013"
    }, {
      "skillName" : "Russia",
      "skillId" : "1000000173047",
      "skillTypeId" : "1000000173001"
    } ],
    "departmentId" : "1000000013248"
  } ]
}

Get Criteria Fields for Skill in a Department

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

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department Id

module

String

required

Module, Allowed values are tickets,contacts and accounts

GET /api/v1/skills/criteriaFields

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skills/criteriaFields?orgId=15157826&departmentId=1000000013248&module=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "criteriaFields" : [ {
    "displayLabel" : "Tickets",
    "name" : "tickets",
    "fieldDetails" : [ {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Account Name",
      "i18NLabel" : "Account Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Contact Name",
      "i18NLabel" : "Contact Name",
      "type" : "lookup"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Email",
      "i18NLabel" : "Email",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Phone",
      "i18NLabel" : "Phone",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Subject",
      "i18NLabel" : "Subject",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Description",
      "i18NLabel" : "Description",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is OPEN",
        "i18NCondition" : "is OPEN",
        "value" : [ "${OPEN}" ]
      }, {
        "condition" : "is ON HOLD",
        "i18NCondition" : "is ON HOLD",
        "value" : [ "${ONHOLD}" ]
      }, {
        "condition" : "is CLOSED",
        "i18NCondition" : "is CLOSED",
        "value" : [ "${CLOSED}" ]
      }, {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Status",
      "i18NLabel" : "Status",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case Owner",
      "i18NLabel" : "Ticket Owner",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Created By",
      "i18NLabel" : "Created By",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Modified By",
      "i18NLabel" : "Modified By",
      "type" : "user"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      } ],
      "fieldLabel" : "Created Time",
      "i18NLabel" : "Created Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case On Hold Time",
      "i18NLabel" : "Ticket On Hold Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Case Closed Time",
      "i18NLabel" : "Ticket Closed Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${DUEDATE}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      } ],
      "fieldLabel" : "Modified Time",
      "i18NLabel" : "Modified Time",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Request Id",
      "i18NLabel" : "Ticket Id",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "To Address",
      "i18NLabel" : "To Address",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Thread Count",
      "i18NLabel" : "Number of Threads",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "=",
        "i18NCondition" : "=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<>",
        "i18NCondition" : "<>",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<",
        "i18NCondition" : "<",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "<=",
        "i18NCondition" : "<=",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">",
        "i18NCondition" : ">",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : ">=",
        "i18NCondition" : ">=",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Comment Count",
      "i18NLabel" : "Number of Comments",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "Good", "Bad", "Okay" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "Good", "Bad", "Okay" ]
      }, {
        "condition" : "is received",
        "i18NCondition" : "is received",
        "value" : [ ]
      }, {
        "condition" : "is not received",
        "i18NCondition" : "is not received",
        "value" : [ ]
      }, {
        "condition" : "link provided",
        "i18NCondition" : "link provided",
        "value" : [ ]
      }, {
        "condition" : "link not provided",
        "i18NCondition" : "link not provided",
        "value" : [ ]
      } ],
      "fieldLabel" : "Happiness Rating",
      "i18NLabel" : "Happiness Rating",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "has agents",
        "i18NCondition" : "has agents",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Team",
      "i18NLabel" : "Team",
      "type" : "team"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is after",
        "i18NCondition" : "is after",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "is before",
        "i18NCondition" : "is before",
        "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
      }, {
        "condition" : "between",
        "i18NCondition" : "between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "not between",
        "i18NCondition" : "not between",
        "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Due Date",
      "i18NLabel" : "Due Date",
      "type" : "dateTime"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Tags",
      "i18NLabel" : "Tags",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Priority",
      "i18NLabel" : "Priority",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Mode",
      "i18NLabel" : "Channel",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Overdue",
      "i18NLabel" : "Is Overdue",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Escalated",
      "i18NLabel" : "Is Escalated",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Resolution",
      "i18NLabel" : "Resolution",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is Less Than",
        "i18NCondition" : "is Less Than",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is Greater Than",
        "i18NCondition" : "is Greater Than",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Time to Respond",
      "i18NLabel" : "Time to Respond",
      "type" : "integer"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "isn't",
        "i18NCondition" : "isn't",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "starts with",
        "i18NCondition" : "starts with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains",
        "i18NCondition" : "contains",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "doesn't contain",
        "i18NCondition" : "doesn't contain",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "ends with",
        "i18NCondition" : "ends with",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      } ],
      "fieldLabel" : "Skill",
      "i18NLabel" : "Skill",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is empty",
        "i18NCondition" : "is empty",
        "value" : [ "${EMPTY}" ]
      }, {
        "condition" : "is not empty",
        "i18NCondition" : "is not empty",
        "value" : [ "${NOTEMPTY}" ]
      }, {
        "condition" : "contain all of",
        "i18NCondition" : "contain all of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contain any of",
        "i18NCondition" : "contain any of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contain none of",
        "i18NCondition" : "contain none of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Skills",
      "i18NLabel" : "Skills",
      "type" : "text"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "true", "false" ]
      } ],
      "fieldLabel" : "Is Response Overdue",
      "i18NLabel" : "Is Response Overdue",
      "type" : "boolean"
    }, {
      "availableConditions" : [ {
        "condition" : "during business hours of",
        "i18NCondition" : "during business hours of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "outside business hours of",
        "i18NCondition" : "outside business hours of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "on a holiday of",
        "i18NCondition" : "on a holiday of",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "not a holiday of",
        "i18NCondition" : "not a holiday of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Execution Time",
      "i18NLabel" : "Execution Time",
      "type" : "businesshour"
    }, {
      "availableConditions" : [ {
        "condition" : "is",
        "i18NCondition" : "is",
        "value" : [ "Public", "Private" ]
      } ],
      "fieldLabel" : "Recent Comment Type",
      "i18NLabel" : "Recent Comment Type",
      "type" : "commenttype"
    }, {
      "availableConditions" : [ {
        "condition" : "contains one of the following words",
        "i18NCondition" : "contains one of the following words",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains none of the following words",
        "i18NCondition" : "contains none of the following words",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "contains the string",
        "i18NCondition" : "contains the string",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "does not contain the string",
        "i18NCondition" : "does not contain the string",
        "value" : [ "${CUSTOM}" ]
      }, {
        "condition" : "has @ mentions of",
        "i18NCondition" : "has @ mentions of",
        "value" : [ "${CUSTOM}" ]
      } ],
      "fieldLabel" : "Recent Comment",
      "i18NLabel" : "Recent Comment",
      "type" : "comment"
    } ]
  } ]
}

SkillTypes

SkillType is a Category for grouping skills

Example

{
  "modifiedTime" : "2020-07-23T12:36:44.544Z",
  "associatedSkills" : [ {
    "skillName" : "India",
    "skillId" : "1000000173029",
    "skillStatus" : "ACTIVE"
  }, {
    "skillName" : "Russia",
    "skillId" : "1000000173047",
    "skillStatus" : "ACTIVE"
  } ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Country",
  "createdTime" : "2020-07-23T12:36:44.544Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173001"
}


Create Skill Type

This API Creates a Skill Type

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the skilltype

departmentId

long

required

departmentId of the Skill Type

POST /api/v1/skillTypes

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/skillTypes
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "departmentId" : "1000000013248",
  "name" : "Country"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:36:44.544Z",
  "associatedSkills" : [ ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Country",
  "createdTime" : "2020-07-23T12:36:44.544Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173001"
}

View Skill Type

This API Gets the details of a Skill Type

Credit: 1 credit/call

GET /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skillTypes/1000000173001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2020-07-23T12:36:44.544Z",
  "associatedSkills" : [ {
    "skillName" : "India",
    "skillId" : "1000000173029",
    "skillStatus" : "ACTIVE"
  }, {
    "skillName" : "Russia",
    "skillId" : "1000000173047",
    "skillStatus" : "ACTIVE"
  } ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Country",
  "createdTime" : "2020-07-23T12:36:44.544Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173001"
}

Update a Skill Type

This API Updates a Skill Type

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the skilltype

PATCH /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/skillTypes/4000003016645
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "name" : "Product"
}'

Response Example

{
  "modifiedTime" : "2020-07-23T12:39:11.776Z",
  "associatedSkills" : [ ],
  "createdBy" : "1000000000059",
  "departmentId" : "1000000013248",
  "name" : "Product",
  "createdTime" : "2020-07-23T12:39:11.776Z",
  "modifiedBy" : "1000000000059",
  "id" : "1000000173019"
}

Delete a Skill Type

This API Deletes a Skill Type

Credit: 1 credit/call

DELETE /api/v1/skillTypes/{skilTypeId}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/skillTypes/4000003016645
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

List all Skill Types

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

Query Params

Param Name
Data Type
Description
departmentId

long

optional

Department Id

from

integer

optional

Index number, starting from which the skills must be listed

limit

integer

optional,
range : 1-100

Number of skilltypes to list, allowed minimum value 1, maximum value 100,default is 100

mappedSkillsStatus

String

optional

Filter skill types by associated skills status, allowed values ACTIVE and INACTIVE

GET /api/v1/skillTypes

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skillTypes?departmentId=4000003016008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2020-07-23T12:36:44.544Z",
    "associatedSkills" : [ {
      "skillName" : "India",
      "skillId" : "1000000173029",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Russia",
      "skillId" : "1000000173047",
      "skillStatus" : "ACTIVE"
    } ],
    "mappedSkillsStatus" : [ "ACTIVE" ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Country",
    "createdTime" : "2020-07-23T12:36:44.544Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173001"
  }, {
    "modifiedTime" : "2020-07-23T12:38:59.455Z",
    "associatedSkills" : [ {
      "skillName" : "English",
      "skillId" : "1000000173097",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Malayalam",
      "skillId" : "1000000173145",
      "skillStatus" : "ACTIVE"
    }, {
      "skillName" : "Tamil",
      "skillId" : "1000000173121",
      "skillStatus" : "INACTIVE"
    } ],
    "mappedSkillsStatus" : [ "INACTIVE", "ACTIVE" ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Language",
    "createdTime" : "2020-07-23T12:38:59.455Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173013"
  }, {
    "modifiedTime" : "2020-07-23T12:39:47.900Z",
    "associatedSkills" : [ ],
    "mappedSkillsStatus" : [ ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Product",
    "createdTime" : "2020-07-23T12:39:11.776Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173019"
  }, {
    "modifiedTime" : "2020-07-23T12:38:53.429Z",
    "associatedSkills" : [ ],
    "mappedSkillsStatus" : [ ],
    "createdBy" : "1000000000059",
    "departmentId" : "1000000013248",
    "name" : "Region",
    "createdTime" : "2020-07-23T12:38:53.429Z",
    "modifiedBy" : "1000000000059",
    "id" : "1000000173007"
  } ]
}

SkillConfiguration

Department Level Configurations for Skill Stamping

ATTRIBUTES

Attribute Name
Data Type
Description
departmentId

long

ID of the Department

attachSkillsOption

string

Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER

autoSkillStamping

string

This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE

Example

{
  "autoSkillStamping" : "INACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_FIRST"
}


Get Skill Configuration

This API gets Configuration of Skill in a Department

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department Id

GET /api/v1/skillConfiguration

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/skillConfiguration?departmentId=1000000013248
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "autoSkillStamping" : "ACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_THE_END"
}

Update Skill Configuration

This API updates Configuration of Skill in a Department

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

optional

ID of the Department

attachSkillsOption

string

optional,
max chars : 100

Append new skills at AT_FIRST or AT_THE_END or BY_SKILL_ORDER

autoSkillStamping

string

optional,
max chars : 100

This indicates Auto Stamping is Active or not, Allowed values ACTIVE or INACTIVE

PATCH /api/v1/skillConfiguration

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/skillConfiguration
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "autoSkillStamping" : "INACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_FIRST"
}'

Response Example

{
  "autoSkillStamping" : "INACTIVE",
  "departmentId" : "1000000013248",
  "attachSkillsOption" : "AT_FIRST"
}

RoutingPreference

Common Configurations for Routing Rules

ATTRIBUTES

Attribute Name
Data Type
Description
departmentId

long

department Id

isThresholdEnabled

boolean

Used to enable/disable ticket threshold for Round Robin

thresholdLimit

integer

Threshold Per Agent, Range 1-500,thresholdEnabled has to be True to Update this limit

assignBacklog

boolean

Will bulk-assign tickets that were created when agents were unavailable.

backLogLimit

integer

Max. number of backlog tickets that can be bulk-assigned to an agent. Range 1-50

assignBacklogsBy

String

Assign Backlogs Based on Due Date or Created Time, Allowed values DUEDATE and CREATEDTIME

assignToOfflineAgents

boolean

Will include mail-channel offline agents also while assigning tickets.

freshTicketAssignMode

String

Fresh Ticket Assignment Mode, allowed values are IMMEDIATE,MOVE_TO_BACKLOG

isCustomThresholdEnabled

boolean

Key that enables or disables agent specific thresholds. The default value is false.

customThresholdVsAgents

list

List of Agent Specific Thresholds

Example

{
  "assignBacklog" : true,
  "assignToOfflineAgents" : true,
  "thresholdLimit" : "40",
  "backLogLimit" : "5",
  "isThresholdEnabled" : true,
  "departmentId" : "1000000013248",
  "assignBacklogsBy" : "DUEDATE",
  "freshTicketAssignMode" : "IMMEDIATE",
  "customThresholdVsAgents" : [ {
    "customThreshold" : "10",
    "agents" : [ {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013200/photo?orgId=536339",
      "name" : "Fredric",
      "id" : "1000000013200",
      "zuid" : "538762"
    } ]
  }, {
    "customThreshold" : "15",
    "agents" : [ {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013288/photo?orgId=536339",
      "name" : "Baby",
      "id" : "1000000013288",
      "zuid" : "796851"
    }, {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013299/photo?orgId=536339",
      "name" : "Denver",
      "id" : "1000000013299",
      "zuid" : "538065"
    } ]
  } ],
  "isCustomThresholdEnabled" : true
}


Get Routing Preferences

This API is used to Get the Routing Preferences for a Department

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department Id

GET /api/v1/routingPreferences

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/routingPreferences?departmentId=1000000013248
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "assignBacklog" : true,
  "assignToOfflineAgents" : true,
  "thresholdLimit" : "40",
  "backLogLimit" : "5",
  "isThresholdEnabled" : true,
  "departmentId" : "1000000013248",
  "assignBacklogsBy" : "DUEDATE",
  "freshTicketAssignMode" : "IMMEDIATE",
  "customThresholdVsAgents" : [ {
    "customThreshold" : "10",
    "agents" : [ {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013200/photo?orgId=536339",
      "name" : "Fredric",
      "id" : "1000000013200",
      "zuid" : "538762"
    } ]
  }, {
    "customThreshold" : "15",
    "agents" : [ {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013288/photo?orgId=536339",
      "name" : "Baby",
      "id" : "1000000013288",
      "zuid" : "796851"
    }, {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000013299/photo?orgId=536339",
      "name" : "Denver",
      "id" : "1000000013299",
      "zuid" : "538065"
    } ]
  } ],
  "isCustomThresholdEnabled" : true
}

Update Routing Preferences

This API is used to Update the Routing Preferences for a Department

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
departmentId

long

optional

department Id

isThresholdEnabled

boolean

optional

Used to enable/disable ticket threshold for Round Robin

thresholdLimit

integer

optional,
range : 1-500

Threshold Per Agent, Range 1-500,thresholdEnabled has to be True to Update this limit

assignBacklog

boolean

optional

Will bulk-assign tickets that were created when agents were unavailable.

backLogLimit

integer

optional,
range : 1-50

Max. number of backlog tickets that can be bulk-assigned to an agent. Range 1-50

assignBacklogsBy

String

optional

Assign Backlogs Based on Due Date or Created Time, Allowed values DUEDATE and CREATEDTIME

assignToOfflineAgents

boolean

optional

Will include mail-channel offline agents also while assigning tickets.

freshTicketAssignMode

String

optional

Fresh Ticket Assignment Mode, allowed values are IMMEDIATE,MOVE_TO_BACKLOG

isCustomThresholdEnabled

boolean

optional,
default : false

Key that enables or disables agent specific thresholds. The default value is false.

PATCH /api/v1/routingPreferences

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/routingPreferences
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "assignBacklog" : true,
  "isThresholdEnabled" : "true",
  "backLogLimit" : "22",
  "departmentId" : "1000000013248",
  "customThresholdVsAgents" : [ {
    "agentIds" : [ "1000000013288", "1000000013299" ],
    "customThreshold" : "15"
  }, {
    "agentIds" : [ "1000000013200" ],
    "customThreshold" : "10"
  } ],
  "isCustomThresholdEnabled" : true
}'

Response Example

{
  "assignBacklog" : true,
  "assignToOfflineAgents" : true,
  "thresholdLimit" : "40",
  "backLogLimit" : "22",
  "isThresholdEnabled" : true,
  "departmentId" : "1000000013248",
  "assignBacklogsBy" : "DUEDATE",
  "freshTicketAssignMode" : "IMMEDIATE"
}

Recycle Bin

The Recycle Bin is the location where deleted resources, such as tickets, contacts, tasks, and time entries among others, are temporarily stored. From this location, users can retrieve resources that may have been accidentally deleted.

ATTRIBUTES

Attribute Name
Data Type
Description
ids

list

Array containing the IDs of the resources.

isChildNeedToBeRestored

boolean

Key that denotes whether the child resources must be restored or not.

departmentId
see documentation

long

ID of the department to which the deleted resources belong.

Example

{
  "isChildNeedToBeRestored" : "true",
  "departmentId" : "4000000013244",
  "ids" : [ "232323", "3213123", "232", "4000000056156" ]
}


List deleted resources

This API lists a particular number of deleted resources, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the resources must be fetched.

limit

integer

optional,
range : 1-100

Number of resources to list. The default value is 10 and the maximum value supported is 100.

departmentId
see documentation

long

optional

ID of the department to which the deleted resources belong.

sortBy

string

optional,
max chars : 100

Sort by a specific attribute: name, type, department, deletedBy, or deletedTime. The default sorting order is ascending. A - prefix denotes descending order of sorting.

module 
deprecated

String

optional

Filter by a specific module: accounts, contacts, tickets, tasks, timeEntry, calls, events, contracts, products, topics, or solutions

moduleId
see documentation

long

optional

ID of the module to which the deleted resources belong.

include
see documentation

string

optional,
max chars : 100

Additional information related to the resources. Values allowed are: department and deletedBy. You can pass multiple values by separating them with commas in the API request.

GET api/v1/recycleBin

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/recycleBin?include=deletedBy,department
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "displayName" : "Sample display name",
    "departmentId" : null,
    "deletedById" : "4000000000059",
    "id" : "4000000046163",
    "type" : "Attachments",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046093",
    "type" : "Calls",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000017184",
    "type" : "Tickets",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046029",
    "type" : "Tickets",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : null,
    "deletedById" : "4000000000059",
    "id" : "4000000019005",
    "type" : "Contacts",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046131",
    "type" : "Events",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046111",
    "type" : "Tasks",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  }, {
    "displayName" : "Sample display name",
    "departmentId" : "4000000013244",
    "deletedById" : "4000000000059",
    "id" : "4000000046153",
    "type" : "Time Entry",
    "deletedTime" : "2020-06-21T16:16:16.000Z"
  } ]
}

Restore deleted resources

This API restores the deleted resources specified in the API request. Additionally, the parent resources are also restored.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the resources to restore

isChildNeedToBeRestored

boolean

optional

Key that denotes whether the child resources must be restored or not.

POST api/v1/recycleBin/restore

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/restore
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isChildNeedToBeRestored" : "true",
  "ids" : [ "232323", "400000005634", "232", "4000000056156" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000056156",
    "errors" : null
  }, {
    "success" : false,
    "id" : "232323",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "400000005634",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  }, {
    "success" : false,
    "id" : "232",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  } ]
}

Restore all resources from Recycle Bin

This API restores all deleted resources from the Recycle Bin.

Credit: 500 credits/call

POST api/v1/recycleBin/restoreAll

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/restoreAll
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

202

Delete resources from Recycle Bin

This API permanently deletes the resources specified in the API request. Additionally, the child resources are also permanently deleted.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the resources to delete.

POST api/v1/recycleBin/delete

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/delete
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ "232323", "3213123", "40000000561232", "4000000056156" ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "4000000056156",
    "errors" : null
  }, {
    "success" : false,
    "id" : "232323",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "3213123",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "UNPROCESSABLE_ENTITY",
      "httpCode" : "422"
    }
  }, {
    "success" : false,
    "id" : "40000000561232",
    "errors" : {
      "errorMessage" : null,
      "errorCode" : "FORBIDDEN",
      "httpCode" : "403"
    }
  } ]
}

Delete all resources from Recycle Bin

This API permanently deletes all resources from the Recycle Bin.

Credit: 500 credits/call

POST api/v1/recycleBin/deleteAll

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/recycleBin/deleteAll
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

202

Subject Access Requests

As part of the General Data Protection Regulation (GDPR), which is the core of Europe's digital privacy legislation, every customer or end-user has the right to ask an organization whether or not their personal information is used and/or stored. This is called the right of access, and exercising this right is called making a Subject Access Request (SAR).

Example

{
  "fieldConditions" : [ {
    "condition" : "is OPEN",
    "fieldName" : "Status",
    "value" : [ "${OPEN}" ]
  }, {
    "condition" : "is",
    "fieldName" : "Due Date",
    "value" : [ "${CURRENTTIME}" ]
  }, {
    "condition" : "is",
    "fieldName" : "Case Owner",
    "value" : [ "7000000092424" ]
  } ],
  "contactEmailId" : "nirmal@zylker.com",
  "module" : "tickets",
  "query" : {
    "criteriaFields" : [ {
      "condition" : "is before",
      "field" : {
        "apiName" : "createdTime",
        "fieldLabel" : "Created Time"
      },
      "value" : {
        "primitive" : [ {
          "displayKey" : "${CURRENTTIME}",
          "key" : "${CURRENTTIME}"
        } ],
        "type" : "primitive"
      }
    } ],
    "criteriaPattern" : "1"
  },
  "limit" : "20",
  "ids" : [ "232323", "3213123", "232", "7000000092431" ],
  "from" : "1",
  "status" : "INPROGRESS"
}


List subject access requests

This API lists a particular number of subject access requests, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=1

Index number, starting from which the requests must be fetched.

limit

integer

optional,
range : 1-100

Number of requests to list. The default value is 10 and the maximum value supported is 100.

contactEmailId

string

optional,
max chars : 100

Email ID of the contact who made the request.

status
see documentation

string

optional,
max chars : 100

Processing status of the request. Values allowed are: INITIATED, INPROGRESS, COMPLETED, CANCELED, EXPORTED, PARTIALLY_COMPLETED, PARTIALLY_EXPORTED and FAILED. You can pass multiple values by separating them using commas in the API request.

duration

string

optional,
max chars : 100

Period in which the requests were made. Values allowed are: TODAY, LAST_24_HOURS, LAST_7_DAYS, LAST_30_DAYS, CURRENT_WEEK, and CURRENT_MONTH.

startTime

string

optional,
max chars : 100

Starting time of the time range in which the requests should have been created. The time should be in the UTC time zone and expressed in a timestamp.

endTime

string

optional,
max chars : 100

Ending time of the time range in which the requests should have been created. The time should be in the UTC time zone and expressed in a timestamp.

requestType
see documentation

string

optional,
max chars : 100

Filter by type of the request. Values allowed are: ACCESS_REQUEST, ERASURE_REQUEST. You can pass multiple values by separating them using commas in the API request.

include
see documentation

string

optional,
max chars : 100

Additional information related to the requests. Values allowed are: createdBy and modifiedBy. You can pass multiple values by separating them using commas in the API request.

GET /api/v1/subjectAccessRequests

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/subjectAccessRequests?include=createdBy,modifiedBy
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "referencereferenceTicketNumber" : "105",
    "contactEmailId" : "john@zylker.com",
    "modifiedById" : "7000000000247",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "sarNumber" : "141",
    "createdTime" : "2020-10-29T12:11:51.890Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "id" : "7000000092437",
    "createdById" : "7000000000247",
    "status" : "COMPLETED"
  }, {
    "contactEmailId" : "nirmal@zylker.com",
    "modifiedById" : "7000000000247",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "referenceTicketNumber" : null,
    "sarNumber" : "140",
    "createdTime" : "2020-10-29T12:10:16.890Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "id" : "7000000092243",
    "createdById" : "7000000000247",
    "status" : "INITIATED"
  }, {
    "contactEmailId" : "mark@zylker.com",
    "modifiedById" : "7000000000247",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "referenceTicketNumber" : "102",
    "sarNumber" : "139",
    "createdTime" : "2020-10-29T12:08:18.838Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "id" : "7000000092049",
    "createdById" : "7000000000247",
    "status" : "INPROGRESS"
  }, {
    "contactEmailId" : "john@zylker.com",
    "modifiedById" : "7000000000247",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "referenceTicketNumber" : null,
    "sarNumber" : "138",
    "createdTime" : "2020-10-29T12:02:29.954Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "id" : "7000000091353",
    "createdById" : "7000000000247",
    "status" : "INPROGRESS"
  }, {
    "contactEmailId" : "mark@zylker.com",
    "modifiedById" : "7000000000247",
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "referenceTicketNumber" : null,
    "sarNumber" : "137",
    "createdTime" : "2020-10-29T11:59:26.592Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
      "firstName" : "Jack",
      "lastName" : "Carol",
      "id" : "7000000000247",
      "email" : "jack@zylker.com"
    },
    "id" : "7000000091159",
    "createdById" : "7000000000247",
    "status" : "INITIATED"
  } ]
}

Get subject access request

This API fetches the details of a particular SAR.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include
see documentation

string

optional,
max chars : 100

Additional information related to the request. Values allowed are: createdBy and modifiedBy. You can pass multiple values by separating them using commas in the API request.

GET /api/v1/subjectAccessRequests/{subjectAccessRequest_id}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/subjectAccessRequests/400000005634
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "contactEmailId" : "carrol@zylker.com",
  "requestType" : "ERASURE_REQUEST",
  "recordType" : "SPECIFIC",
  "module" : "tickets",
  "query" : {
    "criteriaFields" : [ {
      "condition" : "is before",
      "field" : {
        "apiName" : "createdTime",
        "fieldLabel" : "Created Time"
      },
      "value" : {
        "primitive" : [ {
          "displayKey" : "${CURRENTTIME}",
          "key" : "${CURRENTTIME}"
        } ],
        "type" : "primitive"
      }
    } ],
    "criteriaPattern" : "1"
  },
  "downloadURL" : null,
  "modifiedById" : "7000000000247",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
    "firstName" : "Nirmal",
    "lastName" : "Kumar",
    "id" : "7000000000247",
    "email" : "nirmal@zylker.com"
  },
  "referenceTicketNumber" : null,
  "sarNumber" : "141",
  "createdTime" : "2020-10-29T12:11:51.890Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/7000000000247/photo?orgId=15273347",
    "firstName" : "Nirmal",
    "lastName" : "Kumar",
    "id" : "7000000000247",
    "email" : "john@zylker.com"
  },
  "id" : "7000000092437",
  "createdById" : "7000000000247",
  "status" : "INPROGRESS"
}

List resources related to subject

This API lists a particular number of resources related to the subject, based on the limit specified.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Attributes

Param Name
Data Type
Description
module

string

required,
max chars : 100

Name of the modules from which the resources must be fetched. Values allowed are tickets and contacts. If you want to fetch resources from both modules, pass the value allEntities.

contactEmailId

string

required,
max chars : 100

Email ID of the contact who made the request.

from

integer

optional,
range : >=1

Index number, starting from which the resources must be fetched.

limit

integer

optional,
range : 1-50

Number of resources to list. The default value is 10 and the maximum value supported is 50.

fieldConditions

list

optional

Field-related conditions, based on which the resources must be filtered.

POST api/v1/subjectAccessRequests/entities

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/entities
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "condition" : "is",
    "fieldName" : "Last Name",
    "value" : [ "Carol" ]
  } ],
  "contactEmailId" : "johncarol@zylker.com",
  "module" : "contacts",
  "limit" : "5"
}'

Response Example

{
  "data" : [ {
    "firstName" : "John",
    "lastName" : "Carol",
    "accountId" : null,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/7000000092456",
    "mobile" : null,
    "createdTime" : "2019-09-24T05:06:58.000Z",
    "id" : "7000000092456",
    "type" : null,
    "email" : "johncarol@zylker.com",
    "account" : null
  } ]
}

Get count of resources related to request

This API returns the number of resources related to a subject access request.

Credit: 50 credits/call

Attributes

Param Name
Data Type
Description
fieldConditions

list

optional

Field-related conditions, based on which the resources must be filtered

module

string

required,
max chars : 100

Name of the modules from which the data must be exported. Values allowed are tickets and contacts. If you want to fetch data from both modules, pass the value allEntities.

contactEmailId

string

required,
max chars : 100

Email ID of the user who made the request.

POST api/v1/subjectAccessRequests/count

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/count
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactEmailId" : "johncarol@zylker.com",
  "module" : "allEntities"
}'

Response Example

{
  "count" : "3"
}

Export all subject data from Zoho Desk

This API exports data related to the subject, from your Zoho Desk portal.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
module

string

required,
max chars : 100

Name of the modules from which the resources must be fetched. Values allowed are tickets and contacts. If you want to fetch resources from both modules, pass the value allEntities.

fieldConditions

list

optional

Field-related conditions, based on which the data must be filtered.

contactEmailId

string

required,
max chars : 100

Email ID of the user who made the request.

callBackUrl

string

optional,
max chars : 2000

The url which will be used for the notification

POST api/v1/subjectAccessRequests/exportAll

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/exportAll
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "condition" : "is",
    "fieldName" : "Last Name",
    "value" : [ "carol" ]
  } ],
  "contactEmailId" : "jackcarol@zylker.com",
  "callBackUrl" : "https://test.com",
  "module" : "contacts"
}'

Response Example

{
  "modifiedTime" : "2020-10-29T12:11:51.890Z",
  "contactEmailId" : "jackcarol@zylker.com",
  "callBackUrl" : "https://test.com",
  "requestType" : "ACCESS_REQUEST",
  "recordType" : "ALL",
  "module" : "allEntities",
  "query" : null,
  "downloadURL" : null,
  "modifiedById" : "7000000000247",
  "referenceTicketNumber" : null,
  "sarNumber" : "141",
  "createdTime" : "2020-10-29T12:11:51.890Z",
  "id" : "7000000092437",
  "createdById" : "7000000000247",
  "status" : "INITIATED"
}

Export specific resources

This API exports specific resources related to a subject access request.

Credit: 100 credits/call

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the resources that must be exported.

contactEmailId

string

required,
max chars : 100

Email ID of the user who made the request.

POST api/v1/subjectAccessRequests/export

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/export
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactEmailId" : "jackcarol@zylker.com",
  "ids" : [ "7000000075023" ]
}'

Response Example

{
  "modifiedTime" : "2020-10-26T16:10:18.930Z",
  "contactEmailId" : "nirmal@zylker.com",
  "requestType" : "ACCESS_REQUEST",
  "recordType" : "SPECIFIC",
  "module" : "tickets",
  "query" : {
    "criteriaFields" : [ {
      "condition" : "is before",
      "field" : {
        "apiName" : "createdTime",
        "fieldLabel" : "Created Time"
      },
      "value" : {
        "primitive" : [ {
          "displayKey" : "${CURRENTTIME}",
          "key" : "${CURRENTTIME}"
        } ],
        "type" : "primitive"
      }
    } ],
    "criteriaPattern" : "1"
  },
  "downloadURL" : "https://download.zoho.com/webdownload?x-service=desk&event-id=d7c93cfe30f48f884b41171390d582f3c0cdb2&x-cli-msg=%7B%22portalname%22%3A%22jordan%22%2C%22inline%22%3A%22false%22%7D",
  "modifiedById" : "7000000000247",
  "referenceTicketNumber" : null,
  "sarNumber" : "91",
  "createdTime" : "2020-10-26T16:10:18.930Z",
  "id" : "7000000075001",
  "createdById" : "7000000000247",
  "status" : "COMPLETED"
}

Get fields and conditions

This API fetchs possible fileds list and conditions

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
module

string

required,
max chars : 100

Name of the modules from which the resources must be fetched. Values allowed are tickets and contacts. If you want to fetch resources from both modules, pass the value allEntities.

GET api/v1/subjectAccessRequests/fieldsAndConditions

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/subjectAccessRequests/fieldsAndConditions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "displayLabel" : "AllEntities",
  "name" : "AllEntities",
  "fieldDetails" : [ {
    "availableConditions" : [ {
      "condition" : "is",
      "i18NCondition" : "is",
      "value" : [ "${CUSTOM}" ]
    }, {
      "condition" : "isn't",
      "i18NCondition" : "isn't",
      "value" : [ "${CUSTOM}" ]
    }, {
      "condition" : "starts with",
      "i18NCondition" : "starts with",
      "value" : [ "${CUSTOM}" ]
    }, {
      "condition" : "is empty",
      "i18NCondition" : "is empty",
      "value" : [ "${EMPTY}" ]
    }, {
      "condition" : "is not empty",
      "i18NCondition" : "is not empty",
      "value" : [ "${NOTEMPTY}" ]
    } ],
    "fieldLabel" : "Phone",
    "i18NLabel" : "Phone",
    "type" : "text"
  }, {
    "availableConditions" : [ {
      "condition" : "is",
      "i18NCondition" : "is",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "isn't",
      "i18NCondition" : "isn't",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "is after",
      "i18NCondition" : "is after",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "is before",
      "i18NCondition" : "is before",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "between",
      "i18NCondition" : "between",
      "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
    }, {
      "condition" : "not between",
      "i18NCondition" : "not between",
      "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
    } ],
    "fieldLabel" : "Created Time",
    "i18NLabel" : "Created Time",
    "type" : "dateTime"
  }, {
    "availableConditions" : [ {
      "condition" : "is",
      "i18NCondition" : "is",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "isn't",
      "i18NCondition" : "isn't",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "is after",
      "i18NCondition" : "is after",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "is before",
      "i18NCondition" : "is before",
      "value" : [ "${CURRENTTIME}", "${CUSTOM}" ]
    }, {
      "condition" : "between",
      "i18NCondition" : "between",
      "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
    }, {
      "condition" : "not between",
      "i18NCondition" : "not between",
      "value" : [ [ "${CURRENTTIME}", "${CUSTOM}" ], [ "${CURRENTTIME}", "${CUSTOM}" ] ]
    } ],
    "fieldLabel" : "Modified Time",
    "i18NLabel" : "Modified Time",
    "type" : "dateTime"
  } ]
}

Erase all subject data from Zoho Desk

This API erases data related to the subject, from your Zoho Desk portal.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
module

string

required,
max chars : 100

Name of the modules from which the resources must be fetched. Values allowed are tickets and contacts. If you want to fetch resources from both modules, pass the value allEntities.

fieldConditions

list

optional

Field-related conditions, based on which the data must be filtered.

contactEmailId

string

required,
max chars : 100

Email ID of the user who made the request.

POST api/v1/subjectAccessRequests/eraseAll

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/eraseAll
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "fieldConditions" : [ {
    "condition" : "is",
    "fieldName" : "Last Name",
    "value" : [ "carol" ]
  } ],
  "contactEmailId" : "jackcarol@zylker.com",
  "module" : "contact"
}'

Response Example

{
  "modifiedTime" : "2020-10-29T12:11:51.890Z",
  "contactEmailId" : "jackcarol@zylker.com",
  "requestType" : "ERASURE_REQUEST",
  "recordType" : "ALL",
  "module" : "allEntities",
  "query" : null,
  "downloadURL" : null,
  "modifiedById" : "7000000000247",
  "referenceTicketNumber" : null,
  "sarNumber" : "141",
  "createdTime" : "2020-10-29T12:11:51.890Z",
  "id" : "7000000092437",
  "createdById" : "7000000000247",
  "status" : "INITIATED"
}

Erase specific resources

This API erases specific resources related to a subject access request.

Credit: 6 credits/record

Attributes

Param Name
Data Type
Description
ids

list

required

Array containing the IDs of the resources that must be exported.

contactEmailId

string

required,
max chars : 100

Email ID of the user who made the request.

POST api/v1/subjectAccessRequests/erase

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/subjectAccessRequests/erase
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "contactEmailId" : "jackcarol@zylker.com",
  "ids" : [ "7000000075023" ]
}'

Response Example

{
  "modifiedTime" : "2020-10-26T16:10:18.930Z",
  "contactEmailId" : "nirmal@zylker.com",
  "requestType" : "ERASURE_REQUEST",
  "recordType" : "SPECIFIC",
  "module" : "tickets",
  "query" : {
    "criteriaFields" : [ {
      "condition" : "is before",
      "field" : {
        "apiName" : "createdTime",
        "fieldLabel" : "Created Time"
      },
      "value" : {
        "primitive" : [ {
          "displayKey" : "${CURRENTTIME}",
          "key" : "${CURRENTTIME}"
        } ],
        "type" : "primitive"
      }
    } ],
    "criteriaPattern" : "1"
  },
  "downloadURL" : "https://download.zoho.com/webdownload?x-service=desk&event-id=d7c93cfe30f48f884b41171390d582f3c0cdb2&x-cli-msg=%7B%22portalname%22%3A%22jordan%22%2C%22inline%22%3A%22false%22%7D",
  "modifiedById" : "7000000000247",
  "referenceTicketNumber" : null,
  "sarNumber" : "91",
  "createdTime" : "2020-10-26T16:10:18.930Z",
  "id" : "7000000075001",
  "createdById" : "7000000000247",
  "status" : "COMPLETED"
}

SupportPlan

Support plans specify the type of support you'll provide to customers. This type can be hour based, ticket based or cost based where the offered support is regulated by no of hours, no of tickets and service cost respectively. You can also set the type to unlimited in which the customer can avail support without any limits. Every support plan has an associated SLA which defines the standard at which the customer will be supported. You must bind the support plan in a contract to set its period of validity.

Example

{
  "supportType" : "Hours",
  "modifiedTime" : "2022-07-26T10:00:07.538Z",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "name" : "SupportPlan for GoldCustomer",
  "sla" : {
    "name" : "Gold-SLA",
    "id" : "4000000019056",
    "status" : "ACTIVE"
  },
  "creadtedTime" : "2022-07-26T10:00:07.538Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019017",
  "department" : {
    "name" : "Automation Department",
    "id" : "4000000019012"
  },
  "status" : "ACTIVE"
}


Create Support Plan

This API Creates a Support Plan

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

required

Name of the support plan

status

String

required

Status of the support plan, Values allowed are ACTIVE and DISCONTINUED

departmentId

Long

required

Department of the support plan

slaId

Long

required

SLA configured in the support plan

supportType

String

required

Type of the support plan, Values allowed are UNLIMITED_SUPPORT , TICKET

creditDetails

object

optional

Credit details of the support plan

POST /api/v1/supportPlans

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/supportPlans
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "supportType" : "Hours",
  "slaId" : "146284000033706001",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "departmentId" : "146284000010377075",
  "name" : "SupportPlan for GoldCustomer",
  "status" : "ACTIVE"
}'

Response Example

{
  "supportType" : "Hours",
  "modifiedTime" : "2022-07-26T10:00:07.538Z",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "name" : "SupportPlan for GoldCustomer",
  "sla" : {
    "name" : "Gold-SLA",
    "id" : "4000000019056",
    "status" : "ACTIVE"
  },
  "creadtedTime" : "2022-07-26T10:00:07.538Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019017",
  "department" : {
    "name" : "Automation Department",
    "id" : "4000000019012"
  },
  "status" : "ACTIVE"
}

Get Support Plan Details

To get details of a specific support plan

Credit: 1 credit/call

GET /api/v1/supportPlans/{supportPlanId}

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/supportPlans/4000000019017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "supportType" : "Hours",
  "modifiedTime" : "2022-07-26T10:00:07.538Z",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "name" : "SupportPlan for GoldCustomer",
  "sla" : {
    "name" : "Gold-SLA",
    "id" : "4000000019056",
    "status" : "ACTIVE"
  },
  "creadtedTime" : "2022-07-26T10:00:07.538Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019017",
  "department" : {
    "name" : "Automation Department",
    "id" : "4000000019012"
  },
  "status" : "ACTIVE"
}

Update Support Plan

This API Updates the Support Plan

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the support plan

status

String

optional

Status of the support plan, Values allowed are ACTIVE and DISCONTINUED

slaId

Long

optional

SLA configured in the support plan

supportType

String

optional

Type of the support plan, Values allowed are UNLIMITED_SUPPORT , TICKET

creditDetails

object

optional

Credit details of the support plan

PATCH /api/v1/supportPlans/{supportPlanId}

OAuth Scope

Desk.settings.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/supportPlans/4000000019017
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "supportType" : "Hours",
  "slaId" : "146284000033706001",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "name" : "SupportPlan for GoldCustomer",
  "status" : "ACTIVE"
}'

Response Example

{
  "supportType" : "Hours",
  "modifiedTime" : "2022-07-26T10:00:07.538Z",
  "creditDetails" : {
    "isAdditionalUsageAllowed" : false,
    "isCarryForwardAllowed" : false,
    "creditLimit" : "10",
    "creditCycle" : "Weekly"
  },
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "name" : "SupportPlan for GoldCustomer",
  "sla" : {
    "name" : "Gold-SLA",
    "id" : "4000000019056",
    "status" : "ACTIVE"
  },
  "creadtedTime" : "2022-07-26T10:00:07.538Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
    "name" : "SanGhem",
    "id" : "4000000000059",
    "status" : "ACTIVE",
    "zuid" : "234543"
  },
  "id" : "4000000019017",
  "department" : {
    "name" : "Automation Department",
    "id" : "4000000019012"
  },
  "status" : "ACTIVE"
}

List all Support Plans

This API lists all support plans in a department

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
departmentId

long

required

Department Id

from

integer

optional

Index number, starting from which the support plans must be listed

limit

integer

optional,
range : 1-50

Number of support plans to list, allowed minimum value 1, maximum value 50,default is 50

status

String

optional

Active,Discontinued filter for support plans. Values allowed are ACTIVE and DISCONTINUED

GET /api/v1/supportPlans

OAuth Scope

Desk.settings.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/supportPlans?departmentId=1000000013248
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "supportType" : "Hours",
    "modifiedTime" : "2022-07-26T10:00:07.538Z",
    "creditDetails" : {
      "creditLimit" : "10",
      "creditCycle" : "Weekly"
    },
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
      "name" : "SanGhem",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "name" : "SupportPlan for GoldCustomer",
    "sla" : {
      "name" : "Gold-SLA",
      "id" : "4000000019056",
      "status" : "ACTIVE"
    },
    "creadtedTime" : "2022-07-26T10:00:07.538Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
      "name" : "SanGhem",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019017",
    "department" : {
      "name" : "Automation Department",
      "id" : "4000000019012"
    },
    "status" : "ACTIVE"
  }, {
    "supportType" : "Hours",
    "modifiedTime" : "2022-07-26T10:00:07.590Z",
    "creditDetails" : {
      "creditLimit" : "10",
      "creditCycle" : "Weekly"
    },
    "createdBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
      "name" : "SanGhem",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "name" : "SupportPlan for SilverCustomer",
    "sla" : {
      "name" : "Silver-SLA",
      "id" : "4000000019056",
      "status" : "ACTIVE"
    },
    "creadtedTime" : "2022-07-26T10:00:07.590Z",
    "modifiedBy" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000000045/photo?orgId=234587",
      "name" : "SanGhem",
      "id" : "4000000000059",
      "status" : "ACTIVE",
      "zuid" : "234543"
    },
    "id" : "4000000019016",
    "department" : {
      "name" : "Automation Department",
      "id" : "4000000019012"
    },
    "status" : "ACTIVE"
  } ]
}

Delete Support Plan

This API deletes a support plan.

Credit: 1 credit/call

DELETE /api/v1/supportPlans/{supportPlanId}

OAuth Scope

Desk.settings.DELETE

Request Example

  • CURL

$ curl -X DELETE https://desk.zoho.com/api/v1/supportPlans/6000000033001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

204

Generic Actions

Generic Actions are distinct functional units that allow you to perform customized actions. For example, create a record, update a record, and more.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

The name of the Generic Action

inputParams

list

The array of input parameters that are required as input for the action.

Example

{
  "modifiedTime" : "2024-01-23T16:19:37.000Z",
  "apiName" : "assignTicket",
  "creatorType" : "SYSTEM",
  "createdBy" : "1000000000517",
  "preRequisite" : {
    "preRequestScriptUrl" : "https://desk.zoho.com/api/v1/preRequestScript/assignTickets?orgId=19562073",
    "targetId" : "1000000046195",
    "postRequestScriptUrl" : null,
    "actionId" : "1000000046197",
    "inputParamsScriptUrl" : null,
    "outputParamsScriptUrl" : null,
    "targetAPIName" : null,
    "preRequisiteDO" : null,
    "id" : "1000000046198"
  },
  "outputParams" : [ {
    "jsonPointerPath" : "/id",
    "apiName" : "ticketId",
    "origin" : "STATIC",
    "length" : "30",
    "name" : "Ticket Id",
    "actionId" : "1000000046197",
    "id" : "1000000046202",
    "type" : "TEXT",
    "version" : "1",
    "order" : "1"
  }, {
    "jsonPointerPath" : "/assigneeId",
    "apiName" : "assigneeId",
    "origin" : "STATIC",
    "length" : "30",
    "name" : "Assignee Id",
    "actionId" : "1000000046197",
    "id" : "1000000046203",
    "type" : "PICKLIST",
    "version" : "1",
    "order" : "2"
  }, {
    "jsonPointerPath" : "/teamId",
    "apiName" : "teamId",
    "origin" : "STATIC",
    "length" : "30",
    "name" : "Team Id",
    "actionId" : "1000000046197",
    "id" : "1000000046204",
    "type" : "PICKLIST",
    "version" : "1",
    "order" : "3"
  }, {
    "jsonPointerPath" : "/modifiedTime",
    "apiName" : "modifiedTime",
    "origin" : "STATIC",
    "length" : "30",
    "name" : "Modified Time",
    "actionId" : "1000000046197",
    "id" : "1000000046205",
    "type" : "TEXT",
    "version" : "1",
    "order" : "4"
  }, {
    "jsonPointerPath" : "/ticketNumber",
    "apiName" : "ticketNumber",
    "origin" : "STATIC",
    "length" : "30",
    "name" : "Ticket Number",
    "actionId" : "1000000046197",
    "id" : "1000000046206",
    "type" : "TEXT",
    "version" : "1",
    "order" : "5"
  } ],
  "name" : "Assign Ticket",
  "inputParams" : [ {
    "picklistValues" : [ ],
    "apiName" : "ticketId",
    "placeHolderContext" : "tickets",
    "origin" : "STATIC",
    "length" : "200",
    "type" : "LOOKUP",
    "version" : "1",
    "targetTemplateKey" : "ticketId",
    "isEncrypted" : false,
    "name" : "Record ID",
    "uiType" : "LookUp",
    "actionId" : "1000000046197",
    "id" : "1000000046199",
    "hooks" : [ ],
    "isMandatory" : true,
    "order" : "1"
  }, {
    "picklistValues" : [ {
      "prompt" : "Agent",
      "value" : "AGENT"
    }, {
      "prompt" : "Team",
      "value" : "TEAM"
    }, {
      "prompt" : "Agent in a Team",
      "value" : "TEAM_WITH_AGENT"
    } ],
    "apiName" : "type",
    "placeHolderContext" : null,
    "origin" : "STATIC",
    "length" : "200",
    "type" : "PICKLIST",
    "version" : "1",
    "targetTemplateKey" : "type",
    "isEncrypted" : false,
    "name" : "Assignee",
    "actionId" : "1000000046197",
    "id" : "1000000046200",
    "hooks" : [ {
      "payload" : { },
      "id" : "1000000046201",
      "paramId" : "1000000046200",
      "event" : "AFTER_SELECTION",
      "valueUrl" : "https://desk.zoho.com/api/v1/defaults/listAssignFields?orgId=19562073&event=${EVENT}&fieldValue=${FIELD_VALUE}"
    } ],
    "isMandatory" : true,
    "order" : "2"
  } ],
  "createdTime" : "2024-01-23T16:19:37.000Z",
  "modifiedBy" : "1000000000517",
  "id" : "1000000046197",
  "type" : "CUSTOM_ACTION"
}


Execute Action

This API executes an action with the given input values.

Credit: 1 credit/record

Attributes

Param Name
Data Type
Description
entityIds

list

required

IDs of the entities on which the action is to be performed. Eg: Ticket Id, Record Id

moduleId

long

optional

ID of the module to which the entities belong. It could be a system or custom module.

executionType

string

optional,
max chars : 5

Specifies the type of action execution. The allowed values are SYNC and ASYNC.

actionParamMappings

list

required

Maps the input parameters of the Action with the appropriate value.

POST /api/v1/actions/([0-9]+)/execute

OAuth Scope

Desk.settings.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/actions/1000009638757/execute
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "executionType" : "SYNC",
  "actionParamMappings" : [ {
    "apiName" : "staticParam1",
    "value" : "My Action"
  }, {
    "apiName" : "staticParam2",
    "value" : "1000000026140"
  }, {
    "apiName" : "staticParam3",
    "value" : {
      "subject" : "hello ${tickets.$createdBy}"
    }
  }, {
    "picklistValues" : [ ],
    "apiName" : "dyamicParam1",
    "placeHolderContext" : null,
    "origin" : "STATIC",
    "length" : "100",
    "type" : "TEXT",
    "isEncrypted" : false,
    "name" : "Dynamic Param",
    "uiType" : null,
    "targetTemplateName" : null,
    "hooks" : [ ],
    "value" : "Some value",
    "isMandatory" : true,
    "order" : "1"
  } ],
  "moduleId" : "1000000000581",
  "entityIds" : [ "1000000048371" ]
}'

Response Example

{
  "data" : {
    "message" : "Action Execution completed for Action ID - 1000009638757",
    "status" : "SUCCESS",
    "actionResult" : {
      "executionResult" : {
        "executionStatus" : "true",
        "skippedFieldUpdates" : [ {
          "skippedFields" : [ {
            "displayLabel" : "Subject",
            "apiName" : "subject",
            "fieldId" : "1000000002157"
          } ],
          "name" : "My Action"
        } ]
      },
      "entityId" : 1000000048371
    }
  }
}

IM Channel

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

Channel ID of the channel

accountName

string

Account name of the channel

integrationServiceType

string

Integration Service of the channel. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER

defaultBotId

long

Bot ID of the channel

name

string

Name of the channel

isActive

boolean

Is channel Active ?

isStorageEnabled

boolean

Is storage enabled for the channel ?

isSandBox

boolean

Is sandbox channel ?

createdTime

timestamp

Channel creation time

createdBy

long

Agent Id who created the channel

isAuthorizationPending

boolean

Is authorization pending ?

isSubscribed

boolean

Is channel subscribed ?

authenticationURL

string

Authentication Url

isOwner

boolean

Is the agent owner of the channel ?

conversationCount

long

Total conversation count of the channel

universalLink

string

Universal link of the channel

isDeleted

boolean

Is channel deleted ?

photoURL

string

Photo Url of the channel

departmentId

long

Department Id for which channel is associated

appName

string

App name and channel name is same for a IM channel

code

string

Code Name of the channel. This is uniquely generated while creating a channel by using the channel name.

configParams

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

{
  "defaultBotId" : "-1",
  "code" : "TEST_WA_CHANNEL_4",
  "accountName" : "+14328784611",
  "integrationServiceType" : "WHATSAPP",
  "appName" : "Test WA Channel",
  "departmentId" : "186543000000006907",
  "universalLink" : "https://wa.me/14328784611",
  "isActive" : true,
  "isAuthorizationPending" : false,
  "photoURL" : "https://desk.zoho.com/api/v1/channels/test_wa_channel_4/photo?orgId=78412359",
  "isSubscribed" : true,
  "isDeleted" : false,
  "configParams" : [ {
    "isRequired" : false,
    "modifiedTime" : "2024-03-22T05:33:40.000Z",
    "isSecured" : false,
    "isDeprecated" : false,
    "defaultValue" : "CREATED",
    "parentParams" : [ ],
    "label" : "Current Onboarding Status",
    "type" : "SYSTEM_DEFINED",
    "uuid" : "56302cb334385d818e3400a023091560",
    "isInternal" : false,
    "name" : "CURRENT_STATUS",
    "options" : null,
    "id" : "3942000001423031",
    "value" : "CONNECTED",
    "maxLen" : "255"
  }, {
    "isRequired" : true,
    "modifiedTime" : "2024-03-22T05:33:40.000Z",
    "isSecured" : false,
    "isDeprecated" : false,
    "defaultValue" : null,
    "parentParams" : [ ],
    "label" : "WhatsApp Phone Number",
    "type" : "OPTIONS_COMPUTED",
    "uuid" : "56302cb334385d818e3400a023091560",
    "isInternal" : false,
    "name" : "PHONE_NUMBER",
    "options" : null,
    "id" : "3942000001423033",
    "value" : "+14328784611",
    "maxLen" : "255"
  } ],
  "isStorageEnabled" : false,
  "createdBy" : "78412824",
  "isOwner" : true,
  "conversationCount" : "4",
  "meta" : [ ],
  "name" : "Test WA Channel",
  "createdTime" : "2024-03-22T05:33:40.000Z",
  "id" : "3942000001423029",
  "authenticationURL" : null,
  "isSandBox" : false
}


List Channels

This API lists all channels

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
integrationServiceId

string

optional,
max chars : 100

Integration Service ID to filter. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER

departmentId

long

optional

Department Id for which channels to be fetched

include

string

optional,
max chars : 100

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

isSandBox

boolean

optional

Set this to fetch sandbox channels only.

isActive

boolean

optional

Set this to fetch only the active channels

includeDeleted

boolean

optional

Set this to fetch along with the deleted channels

configName

string

optional,
max chars : 100

Set this to fetch channels with the given Config Param Name. Refer config param attribute of channel to get Config Name

configValue

string

optional,
max chars : 100

Set this to fetch channels with the given Config Param Value. Refer config param attribute of channel to get Config Value

excludeConfigName

string

optional,
max chars : 100

Set this to fetch channels with the not given Config Param Name. Refer config param attribute of channel to get Config Name

excludeConfigValue

string

optional,
max chars : 100

Set this to fetch channels with the not given Config Param Value. Refer config param attribute of channel to get Config Value

GET /api/v1/im/channels

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/channels
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "defaultBotId" : "-1",
    "code" : "SANDBOX",
    "accountName" : "+13312040199",
    "integrationServiceType" : "WHATSAPP",
    "appName" : "Sandbox",
    "departmentId" : "186543000000006907",
    "universalLink" : "https://wa.me/13312040199",
    "isActive" : true,
    "isAuthorizationPending" : false,
    "photoURL" : "https://desk.zoho.com/api/v1/channels/sandbox/photo?orgId=78412359",
    "isSubscribed" : true,
    "isDeleted" : false,
    "isStorageEnabled" : false,
    "createdBy" : "78412824",
    "isOwner" : true,
    "name" : "Sandbox",
    "createdTime" : "2023-09-04T09:13:56.000Z",
    "id" : "3942000000045001",
    "authenticationURL" : null,
    "isSandBox" : true
  }, {
    "defaultBotId" : "-1",
    "code" : "TEST_SOFTWARE_4_3",
    "accountName" : "Test Software 4",
    "integrationServiceType" : "FACEBOOKMESSENGER",
    "appName" : "Test Software 4",
    "departmentId" : "186543000000393040",
    "universalLink" : "https://m.me/168123406390163",
    "isActive" : true,
    "isAuthorizationPending" : false,
    "photoURL" : "https://desk.zoho.com/api/v1/channels/test_software_4_3/photo?orgId=78412359",
    "isSubscribed" : true,
    "isDeleted" : false,
    "isStorageEnabled" : false,
    "createdBy" : "78412824",
    "isOwner" : true,
    "name" : "Test Software 4",
    "createdTime" : "2024-02-07T06:28:32.000Z",
    "id" : "3942000000943035",
    "authenticationURL" : null,
    "isSandBox" : false
  }, {
    "defaultBotId" : "-1",
    "code" : "TEST_DEP",
    "accountName" : "ZImAbhiTestBot",
    "integrationServiceType" : "TELEGRAM",
    "appName" : "Test DEP",
    "departmentId" : "186543000000393040",
    "universalLink" : "https://t.me/ZImAbhiTestBot",
    "isActive" : true,
    "isAuthorizationPending" : false,
    "photoURL" : "https://desk.zoho.com/api/v1/channels/test_dep/photo?orgId=78412359",
    "isSubscribed" : true,
    "isDeleted" : false,
    "isStorageEnabled" : false,
    "createdBy" : "76837521",
    "isOwner" : true,
    "name" : "Test DEP",
    "createdTime" : "2024-01-16T04:17:16.000Z",
    "id" : "3942000000735961",
    "authenticationURL" : null,
    "isSandBox" : false
  } ]
}

Get a Channel

This API fetches details of an channel.

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
include

string

optional,
max chars : 100

Additional information related to the channel. Allowed values are preference, creator

GET /api/v1/im/channels/{channel_id}

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/channels/3942000001423029
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "defaultBotId" : "-1",
  "code" : "TEST_WA_CHANNEL_4",
  "accountName" : "+14328784611",
  "integrationServiceType" : "WHATSAPP",
  "appName" : "Test WA Channel",
  "departmentId" : "186543000000006907",
  "universalLink" : "https://wa.me/14328784611",
  "isActive" : true,
  "isAuthorizationPending" : false,
  "photoURL" : "https://desk.zoho.com/api/v1/channels/test_wa_channel_4/photo?orgId=78412359",
  "isSubscribed" : true,
  "isDeleted" : false,
  "configParams" : [ {
    "isRequired" : false,
    "modifiedTime" : "2024-03-22T05:33:40.000Z",
    "isSecured" : false,
    "isDeprecated" : false,
    "defaultValue" : "CREATED",
    "parentParams" : [ ],
    "label" : "Current Onboarding Status",
    "type" : "SYSTEM_DEFINED",
    "uuid" : "56302cb334385d818e3400a023091560",
    "isInternal" : false,
    "name" : "CURRENT_STATUS",
    "options" : null,
    "id" : "3942000001423031",
    "value" : "CONNECTED",
    "maxLen" : "255"
  }, {
    "isRequired" : true,
    "modifiedTime" : "2024-03-22T05:33:40.000Z",
    "isSecured" : false,
    "isDeprecated" : false,
    "defaultValue" : null,
    "parentParams" : [ ],
    "label" : "WhatsApp Phone Number",
    "type" : "OPTIONS_COMPUTED",
    "uuid" : "56302cb334385d818e3400a023091560",
    "isInternal" : false,
    "name" : "PHONE_NUMBER",
    "options" : null,
    "id" : "3942000001423033",
    "value" : "+14328784611",
    "maxLen" : "255"
  } ],
  "isStorageEnabled" : false,
  "createdBy" : "78412824",
  "isOwner" : true,
  "conversationCount" : "4",
  "meta" : [ ],
  "name" : "Test WA Channel",
  "createdTime" : "2024-03-22T05:33:40.000Z",
  "id" : "3942000001423029",
  "authenticationURL" : null,
  "isSandBox" : false
}

Initiate Session

This API initiates a session with a template message

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
receiverId

string

required,
max chars : 100

ID to which Message Has to be sent

receiverType

string

required,
max chars : 100

Specifies receiverID type. Allowed value PHONENUMBER

cannedMessageId

long

required

TemplateMessageId to send that template

message

string

required,
max chars : 1024

Content of the message

headerMessage

string

optional,
max chars : 60

Content of the header message

urlMessage

string

optional,
max chars : 2000

Content of the URL message

language

string

required,
max chars : 50

Language of Translation. Enter this input in ISO language code. For example en, fr, de, bn, ta etc

meta

JSONArray

optional

Message meta to be added to chat message

POST /api/v1/im/channels/([0-9]+)/initiateSession

OAuth Scope

Desk.InstantMessages.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/im/channels/([0-9]+)/initiateSession
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "receiverId" : "+918478935387",
  "receiverType" : "PHONENUMBER",
  "cannedMessageId" : "3942000001074175",
  "language" : "en",
  "message" : "Welcome to Tasty Bakery. What would you like to eat?"
}'

Response Example

{
  "template" : {
    "rows" : [ {
      "arrangement" : "list",
      "columns" : [ {
        "text" : {
          "style" : "SUB_TITLE",
          "text" : "Welcome to Tasty Bakery. What would you like to eat?"
        },
        "type" : "TEXT"
      } ]
    }, {
      "arrangement" : "list",
      "columns" : [ {
        "button" : {
          "action" : "REPLY",
          "text" : "Cakes",
          "value" : ""
        },
        "type" : "BUTTON"
      }, {
        "button" : {
          "action" : "REPLY",
          "text" : "pizza",
          "value" : ""
        },
        "type" : "BUTTON"
      } ]
    } ]
  },
  "kbArticle" : null,
  "fullContentURL" : null,
  "externalInfo" : null,
  "isRead" : true,
  "index" : "12",
  "sessionId" : "3942000001423083",
  "type" : "TEMPLATE",
  "ticketWebUrl" : "https://desk.zoho.com/support/abhicom4/ShowHomePage.do#Cases/dv/186543000001662116",
  "actor" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
    "contactName" : null,
    "name" : "Abhishek Aich",
    "externalId" : null,
    "id" : "186543000000190001",
    "type" : "AGENT",
    "email" : "zykler.sales@zoho.com"
  },
  "layout" : null,
  "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
  "attachment" : null,
  "meta" : {
    "BOT_REPLY_STATUS" : null,
    "DESK_TICKET_ID" : "186543000001662116",
    "DESK_KB_ARTICLE_TRANSLATION_ID" : null,
    "GC_SELECTED" : null,
    "DESK_TICKET_NUMBER" : "480",
    "BROADCAST_TRACKING_ID" : null,
    "GC_SKIPPED" : null,
    "GC_TRANSFERRED" : null,
    "COST" : null,
    "BROADCAST_ID" : null,
    "RATING_STAR" : null,
    "SYSTEM_MESSAGE_TYPE" : null,
    "REACTION" : null,
    "CANNED_MESSAGE_ID" : "3942000001074175",
    "UNKNOWN" : null,
    "GC_FETCH" : null,
    "FAILED_REASON" : null
  },
  "replyToMessage" : null,
  "createdTime" : "2024-03-26T07:42:13.000Z",
  "action" : null,
  "statusUpdatedTime" : "2024-03-26T07:42:13.000Z",
  "location" : null,
  "id" : "3942000001456011",
  "contentType" : "text/plain",
  "direction" : "OUT",
  "status" : "QUEUED",
  "info" : null
}

Start a Facebook Messenger Session

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

Query Params

Param Name
Data Type
Description
payload

null

Session payload for Facebook Messenger

File Params

file

Content-Type:multipart/form-data

File attachment to send

Attributes

Param Name
Data Type
Description
integrationServiceId

string

required,
max chars : 100

Integration Service of the channel. Only available integration service is FACEBOOKMESSENGER

facebookMessengerPayload

JSONObject

optional

Facebook messenger payload for which the session needed to be created and message to be sent

meta

JSONArray

optional

Message meta to be added to chat message

POST /api/v1/im/channels/([0-9]+)/sessions

OAuth Scope

Desk.InstantMessages.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/im/channels/([0-9]+)/sessions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "integrationServiceId" : "FACEBOOKMESSENGER",
  "facebookMessengerPayload" : {
    "facebookUserId" : "123456778",
    "facebookUserName" : "John Cena",
    "facebookCommentId" : "122127450026859324_989216176516248",
    "message" : "This is test message"
  }
}'

Response Example

{
  "template" : null,
  "kbArticle" : null,
  "fullContentURL" : null,
  "externalInfo" : null,
  "isRead" : true,
  "index" : "31",
  "sessionId" : "41922000000005839",
  "type" : "TEXT",
  "ticketWebUrl" : "https://desk.zoho.com/support/testportal/ShowHomePage.do#Cases/dv/8738475683468768",
  "actor" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/264775000000190001/photo?orgId=108097340",
    "contactId" : null,
    "contactName" : null,
    "name" : "Abhi Aich",
    "zohoService" : "ZOHO_DESK",
    "externalId" : null,
    "id" : "264775000000190001",
    "type" : "AGENT",
    "email" : "test.email+deskim@zoho.com"
  },
  "layout" : null,
  "displayMessage" : "This is test message",
  "attachment" : null,
  "meta" : {
    "BOT_REPLY_STATUS" : null,
    "SKIP_PAYMENT" : null,
    "DESK_TICKET_ID" : "264775000000547304",
    "DESK_KB_ARTICLE_TRANSLATION_ID" : null,
    "CTWA_CLID" : null,
    "GC_SELECTED" : null,
    "DESK_TICKET_NUMBER" : "104",
    "PRODUCT_ID" : null,
    "BROADCAST_TRACKING_ID" : null,
    "GC_SKIPPED" : null,
    "GC_TRANSFERRED" : null,
    "COST" : null,
    "BROADCAST_ID" : null,
    "RATING_STAR" : null,
    "SYSTEM_MESSAGE_TYPE" : null,
    "REACTION" : null,
    "CANNED_MESSAGE_ID" : null,
    "CATALOG_ID" : null,
    "UNKNOWN" : null,
    "GC_FETCH" : null,
    "FAILED_REASON" : null,
    "FB_COMMENT_ID" : "122127450026859324_989216176516248"
  },
  "replyToMessage" : null,
  "createdTime" : "2025-07-26T06:22:03.563Z",
  "action" : null,
  "statusUpdatedTime" : "2025-07-26T06:22:03.579Z",
  "location" : null,
  "id" : "41922000000063019",
  "contentType" : "text/plain",
  "direction" : "OUT",
  "status" : "QUEUED",
  "info" : null
}

IM Session

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.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

Sesion ID of the session

channelId

long

Channel ID for which the session is created

status

string

Status filter for the conversations. Allowed values are OPEN, ON_PROGRESS ,ON_HOLD ,BLOCKED

createdTime

timestamp

Session creation time

agentId

long

Agent Id assicoated with the session

botId

long

Bot ID associated with the session

actor

JSONObject

Session actor

subject

string

Subject of the session

messagesCount

int

Total message count in the session

agentLastActiveTime

timestamp

Last active time of agent

contactLastActiveTime

timestamp

End user last active time of agent

lastActiveTime

timestamp

Last active time of agent

unreadMessagesCount

int

Total unread message count in the session

integrationService

string

Integration Service of the channel. Available integration services are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER

replyStatus

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

contactId

long

End user desk contact Id

meta

JSONObject

Session meta

deskAssignee

JSONObject

Session assignee

channel

string

Channel code

Example

{
  "agentId" : "78412824",
  "lastActiveTime" : "2024-03-22T07:57:13.000Z",
  "contactId" : "186543000000451259",
  "subject" : "This is test 2   Abhishek Aich",
  "unreadMessagesCount" : "0",
  "channel" : "TEST_WA_CHANNEL_4",
  "integrationService" : "WHATSAPP",
  "deskAssignee" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
    "botType" : null,
    "contactName" : null,
    "name" : "Abhishek Aich",
    "externalId" : null,
    "id" : "186543000000190001",
    "type" : "AGENT",
    "email" : "zykler.sales@zoho.com"
  },
  "contactLastActiveTime" : "2024-03-22T05:51:09.000Z",
  "actor" : {
    "photoURL" : null,
    "botType" : null,
    "contactName" : "Abhishek Aich",
    "name" : "Abhishek Aich",
    "externalId" : "+918478935387",
    "id" : "186543000000451285",
    "type" : "ENDUSER",
    "email" : null
  },
  "meta" : {
    "DESK_TICKET_ID" : "186543000001662116",
    "DESK_TICKET_NUMBER" : "480"
  },
  "createdTime" : "2024-03-22T05:34:19.000Z",
  "replyStatus" : "SESSION_EXPIRED",
  "botId" : null,
  "messagesCount" : "10",
  "id" : "3942000001423083",
  "channelId" : "3942000001423029",
  "agentLastActiveTime" : "2024-03-22T07:57:13.000Z",
  "status" : "ON_PROGRESS"
}


List Sessions

This API lists all sessions

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 0

Index number, starting from which the conversations must be fetched

limit

int

optional,
default : 0

Number of conversations to fetch

channelId

long

optional

Filter conversations of a channel

botIds

long

optional

Filter conversations assigned to bots

agentId

long

optional

Filter conversations assigned to an agent

contactId

long

optional

Filter conversations of a contact

profileId

long

optional

Filter conversations of a profile

modifiedAfter

timestamp

optional

After which modified date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

createdBefore

timestamp

optional

Before which date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

createdAfter

timestamp

optional

After which date conversations should be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

status

string

optional,
max chars : 100

Status filter for the conversations. Allowed values are OPEN, ON_PROGRESS ,ON_HOLD ,BLOCKED

assigneeFilter

string

optional,
max chars : 100

Assignment status filter for the conversations. Allowed values are MINE, UNASSIGNED ,NONE ,BOT

departmentId

long

optional

Filter conversations of all channels in given department

excludeSyncingChannels

boolean

optional

Exclude session of channels which are in syncing status

GET /api/v1/im/sessions

OAuth Scope

Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/sessions
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "agentId" : "78412824",
    "lastActiveTime" : "2024-03-22T07:57:13.000Z",
    "contactId" : "186543000000451259",
    "subject" : "This is test 2   Abhishek Aich",
    "unreadMessagesCount" : "0",
    "channel" : "TEST_WA_CHANNEL_4",
    "integrationService" : "WHATSAPP",
    "deskAssignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "botType" : null,
      "contactName" : null,
      "name" : "Abhishek Aich",
      "externalId" : null,
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler.sales@zoho.com"
    },
    "contactLastActiveTime" : "2024-03-22T05:51:09.000Z",
    "actor" : {
      "photoURL" : null,
      "botType" : null,
      "contactName" : "Abhishek Aich",
      "name" : "Abhishek Aich",
      "externalId" : "+918478935387",
      "id" : "186543000000451285",
      "type" : "ENDUSER",
      "email" : null
    },
    "meta" : {
      "DESK_TICKET_ID" : "186543000001662116",
      "DESK_TICKET_NUMBER" : "480"
    },
    "createdTime" : "2024-03-22T05:34:19.000Z",
    "replyStatus" : "SESSION_EXPIRED",
    "botId" : null,
    "messagesCount" : "10",
    "id" : "3942000001423083",
    "channelId" : "3942000001423029",
    "agentLastActiveTime" : "2024-03-22T07:57:13.000Z",
    "status" : "ON_PROGRESS"
  }, {
    "agentId" : "78412824",
    "lastActiveTime" : "2024-03-22T07:57:03.000Z",
    "contactId" : "186543000000451259",
    "subject" : "This is test 2   Abhishek Aich",
    "unreadMessagesCount" : "0",
    "channel" : "SANDBOX",
    "integrationService" : "WHATSAPP",
    "deskAssignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "botType" : null,
      "contactName" : null,
      "name" : "Abhishek Aich",
      "externalId" : null,
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler.sales@zoho.com"
    },
    "contactLastActiveTime" : "2024-03-21T09:11:00.000Z",
    "actor" : {
      "photoURL" : null,
      "botType" : null,
      "contactName" : "Abhishek Aich",
      "name" : "Abhishek Aich",
      "externalId" : "+918478935387",
      "id" : "186543000000451285",
      "type" : "ENDUSER",
      "email" : null
    },
    "meta" : {
      "DESK_TICKET_ID" : "186543000001653193",
      "DESK_TICKET_NUMBER" : "477"
    },
    "createdTime" : "2023-09-04T09:30:15.000Z",
    "replyStatus" : "SESSION_EXPIRED",
    "botId" : null,
    "messagesCount" : "65",
    "id" : "3942000000042104",
    "channelId" : "3942000000045001",
    "agentLastActiveTime" : "2024-03-22T07:57:03.000Z",
    "status" : "ON_PROGRESS"
  }, {
    "agentId" : "78412824",
    "lastActiveTime" : "2024-03-22T05:32:38.000Z",
    "contactId" : "186543000000451259",
    "subject" : "Hi good morning",
    "unreadMessagesCount" : "0",
    "channel" : "WA_CHANNEL",
    "integrationService" : "WHATSAPP",
    "deskAssignee" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "botType" : null,
      "contactName" : null,
      "name" : "Abhishek Aich",
      "externalId" : null,
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler.sales@zoho.com"
    },
    "contactLastActiveTime" : "2024-03-22T05:04:06.000Z",
    "actor" : {
      "photoURL" : null,
      "botType" : null,
      "contactName" : "Abhishek Aich",
      "name" : "Abhishek Aich",
      "externalId" : "+918478935387",
      "id" : "186543000000451285",
      "type" : "ENDUSER",
      "email" : null
    },
    "meta" : {
      "DESK_TICKET_ID" : "186543000001662009",
      "DESK_TICKET_NUMBER" : "479"
    },
    "createdTime" : "2024-03-22T05:04:06.000Z",
    "replyStatus" : "CHANNEL_DELETED",
    "botId" : null,
    "messagesCount" : "5",
    "id" : "3942000001422171",
    "channelId" : "3942000001422011",
    "agentLastActiveTime" : "2024-03-22T05:32:38.000Z",
    "status" : "ON_PROGRESS"
  } ],
  "hasMore" : false
}

Get a session

This API fetches details of an session.

Credit: 1 credit/call

GET /api/v1/im/sessions/{session_id}

OAuth Scope

Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/sessions/3942000001423083
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "agentId" : "78412824",
  "lastActiveTime" : "2024-03-22T07:57:13.000Z",
  "contactId" : "186543000000451259",
  "subject" : "This is test 2   Abhishek Aich",
  "unreadMessagesCount" : "0",
  "channel" : "TEST_WA_CHANNEL_4",
  "integrationService" : "WHATSAPP",
  "deskAssignee" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
    "botType" : null,
    "contactName" : null,
    "name" : "Abhishek Aich",
    "externalId" : null,
    "id" : "186543000000190001",
    "type" : "AGENT",
    "email" : "zykler.sales@zoho.com"
  },
  "contactLastActiveTime" : "2024-03-22T05:51:09.000Z",
  "actor" : {
    "photoURL" : null,
    "botType" : null,
    "contactName" : "Abhishek Aich",
    "name" : "Abhishek Aich",
    "externalId" : "+918478935387",
    "id" : "186543000000451285",
    "type" : "ENDUSER",
    "email" : null
  },
  "meta" : {
    "DESK_TICKET_ID" : "186543000001662116",
    "DESK_TICKET_NUMBER" : "480"
  },
  "createdTime" : "2024-03-22T05:34:19.000Z",
  "botId" : null,
  "messagesCount" : "10",
  "id" : "3942000001423083",
  "channelId" : "3942000001423029",
  "agentLastActiveTime" : "2024-03-22T07:57:13.000Z",
  "status" : "ON_PROGRESS"
}

Update an IM session

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

Attributes

Param Name
Data Type
Description
agentId

long

optional

Current assignee of this session

status

string

optional,
max chars : 100

Current status of the session to be set. Possible values are OPEN, ENDED, ON_PROGRESS, ON_HOLD, BLOCKED

botId

long

optional

Current Desk bot assignee of this session.

PATCH /api/v1/im/sessions/{session_id}

OAuth Scope

Desk.InstantMessages.UPDATE

Request Example

  • CURL

$ curl -X PATCH https://desk.zoho.com/api/v1/im/sessions/3942000001423083
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "agentId" : 186543000000451285,
  "status" : "ON_PROGRESS"
}'

Response Example

{
  "agentId" : "799129183",
  "lastActiveTime" : "2025-08-06T07:05:19.403Z",
  "contactId" : "435798000010618001",
  "subject" : "Test",
  "unreadMessagesCount" : "0",
  "channel" : "WHATSAPP_CHANNEL",
  "integrationService" : "WHATSAPP",
  "deskAssignee" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/435798000011895001/photo?orgId=1230993133",
    "contactId" : null,
    "botType" : null,
    "contactName" : null,
    "name" : "Abhishek",
    "externalId" : null,
    "id" : "435798000011895001",
    "type" : "AGENT",
    "email" : "raymon@zykler.com"
  },
  "contactLastActiveTime" : "2025-08-06T07:05:19.403Z",
  "actor" : {
    "photoURL" : null,
    "contactId" : "435798000010618001",
    "botType" : null,
    "contactName" : "Sanjay",
    "name" : "John Cena",
    "externalId" : "+91123456789",
    "id" : "435798000010618029",
    "type" : "ENDUSER",
    "email" : null
  },
  "meta" : {
    "DESK_CX_HAPPINESS_SURVEY_STATE" : "ENDED",
    "DESK_TICKET_ID" : "435798000023790011",
    "DESK_TICKET_NUMBER" : "6448"
  },
  "createdTime" : "2023-10-16T13:10:34.285Z",
  "replyStatus" : "SESSION_ENDED",
  "botId" : null,
  "messagesCount" : "1494",
  "id" : "136000001393001",
  "channelId" : "3942000001423029",
  "agentLastActiveTime" : "2025-08-05T06:30:28.701Z",
  "status" : "ENDED"
}

IM Template Message

An IM template Message predefined comman message to send while initiating a session

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

Template Message ID

title

string

Message title

displayMessage

string

Display Message

isPrivate

boolean

Specify whether the message is private to the creator

message

string

Content of the message

tags

string

Message tags

modifiedTime

timestamp

Last modified time

departmentId

long

Department ID

wabaId

string

Waba ID

type

string

Message Type. Allowed value is TEMPLATE

status

string

Message status

isActive

boolean

Is active ?

actor

JSONObject

Actor

translations

JSONArray

List of translations

Example

{
  "modifiedTime" : "2024-03-22T05:36:02.000Z",
  "departmentId" : "186543000000006907",
  "title" : "WhatsApp marketing",
  "message" : "Welcome to Tasty Bakery. What would you like to eat?",
  "type" : "TEMPLATE",
  "isActive" : true,
  "tags" : "MARKETING",
  "actor" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
    "name" : "Abhishek Aich",
    "id" : "186543000000190001",
    "type" : "AGENT",
    "email" : "zykler@sales.com"
  },
  "wabaId" : "102086489526176",
  "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
  "translations" : [ {
    "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
    "templateItems" : {
      "buttons" : [ {
        "action" : null,
        "type" : "QUICK_REPLY",
        "message" : "Cakes"
      }, {
        "action" : null,
        "type" : "QUICK_REPLY",
        "message" : "pizza"
      } ],
      "footer" : {
        "type" : "TEXT",
        "message" : "Thank you"
      },
      "header" : {
        "attachment" : null,
        "type" : "TEXT",
        "message" : "Welcome Back"
      }
    },
    "language" : "en",
    "id" : "3942000001074177",
    "message" : "Welcome to Tasty Bakery. What would you like to eat?",
    "rejectionReason" : null,
    "status" : "APPROVED"
  } ],
  "id" : "3942000001074175",
  "status" : "APPROVED"
}


List Template Message

This API lists all sessions

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Query Params

Param Name
Data Type
Description
from

int

optional,
default : 0

Index number, starting from which the canned messages must be fetched

limit

int

optional,
default : 0

Number of canned messages to fetch

modifiedAfter

timestamp

optional

After which date entities to be included. Enter a date in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ.

tag

string

optional,
max chars : 100

Tag to filter by

isActive

boolean

optional

Canned Message Active Status

departmentId

long

required

Department ID for which the canned messages to be fetched

wabaId

string

optional,
max chars : 100

Waba ID for which the canned messages to be fetched

channelId

long

optional

Channel ID for which the canned messages to be fetched

contactId

long

optional

Contact ID for which the canned messages to be applied

status

string

optional,
max chars : 100

Filter with Status of Message Applicable only if messageType is Template. Allowed values are PENDING, FAILED, APPROVED, REJECTED

type

string

required,
max chars : 100

Filter by MessageType. Allowed values are TEMPLATE

language

string

optional,
max chars : 100

Language to filter canned message. Enter this input in ISO language code. For example en, fr, de, bn, ta etc

sessionId

long

optional

Session ID for which the canned messages to be applied

GET /api/v1/im/cannedMessages

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/cannedMessages
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2024-03-22T05:36:02.000Z",
    "departmentId" : "186543000000006907",
    "title" : "fb marketing",
    "message" : "Welcome to Tasty Bakery. What would you like to eat?",
    "type" : "TEMPLATE",
    "isActive" : true,
    "tags" : "MARKETING",
    "actor" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "name" : "Abhishek Aich",
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler@sales.com"
    },
    "wabaId" : "102086489526176",
    "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
    "translations" : [ {
      "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
      "templateItems" : {
        "buttons" : [ {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Cakes"
        }, {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "pizza"
        } ],
        "footer" : null,
        "header" : null
      },
      "language" : "en",
      "id" : "3942000001074177",
      "message" : "Welcome to Tasty Bakery. What would you like to eat?",
      "rejectionReason" : null,
      "status" : "APPROVED"
    } ],
    "id" : "3942000001074175",
    "status" : "APPROVED"
  }, {
    "modifiedTime" : "2024-03-22T05:35:53.000Z",
    "departmentId" : "186543000000006907",
    "title" : "Rice Marketing",
    "message" : "Hello please select our new rice items",
    "type" : "TEMPLATE",
    "isActive" : true,
    "tags" : "MARKETING",
    "actor" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "name" : "Abhishek Aich",
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler@sales.com"
    },
    "wabaId" : "102086489526176",
    "displayMessage" : "Hello please select our new rice items",
    "translations" : [ {
      "displayMessage" : "Hello please select our new rice items",
      "templateItems" : {
        "buttons" : [ {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Boiled Rice"
        }, {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Rice Cake"
        }, {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Fried Rice"
        } ],
        "footer" : null,
        "header" : {
          "attachment" : null,
          "type" : "TEXT",
          "message" : "Welcome Back"
        }
      },
      "language" : "en",
      "id" : "3942000001423160",
      "message" : "Hello please select our new rice items",
      "rejectionReason" : null,
      "status" : "APPROVED"
    } ],
    "id" : "3942000001423158",
    "status" : "APPROVED"
  }, {
    "modifiedTime" : "2024-03-22T04:47:53.000Z",
    "departmentId" : "186543000000006907",
    "title" : "Whatsapp marketing",
    "message" : "Welcome to Tasty Bakery. What would you like to eat?\nHere are our new products",
    "type" : "TEMPLATE",
    "isActive" : true,
    "tags" : "UTILITY",
    "actor" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
      "name" : "Abhishek Aich",
      "id" : "186543000000190001",
      "type" : "AGENT",
      "email" : "zykler@sales.com"
    },
    "wabaId" : "102086489526176",
    "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?\nHere are our new products",
    "translations" : [ {
      "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?\nHere are our new products",
      "templateItems" : {
        "buttons" : [ {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Croissants"
        }, {
          "action" : null,
          "type" : "QUICK_REPLY",
          "message" : "Pizza"
        } ],
        "footer" : null,
        "header" : null
      },
      "language" : "en",
      "id" : "3942000001262607",
      "message" : "Welcome to Tasty Bakery. What would you like to eat?\nHere are our new products",
      "rejectionReason" : null,
      "status" : "APPROVED"
    } ],
    "id" : "3942000001262605",
    "status" : "APPROVED"
  } ],
  "hasMore" : false
}

Get a Template Message

This API fetches details of a template message.

Credit: 1 credit/call

GET /api/v1/im/cannedMessages/{template_message_id}

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/im/cannedMessages/3942000001300011
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2024-03-22T05:36:02.000Z",
  "departmentId" : "186543000000006907",
  "title" : "fb marketing",
  "message" : "Welcome to Tasty Bakery. What would you like to eat?",
  "type" : "TEMPLATE",
  "isActive" : true,
  "tags" : "MARKETING",
  "actor" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/186543000000190001/photo?orgId=78412359",
    "name" : "Abhishek Aich",
    "id" : "186543000000190001",
    "type" : "AGENT",
    "email" : "zykler@sales.com"
  },
  "wabaId" : "102086489526176",
  "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
  "translations" : [ {
    "displayMessage" : "Welcome to Tasty Bakery. What would you like to eat?",
    "templateItems" : {
      "buttons" : [ {
        "action" : null,
        "type" : "QUICK_REPLY",
        "message" : "Cakes"
      }, {
        "action" : null,
        "type" : "QUICK_REPLY",
        "message" : "pizza"
      } ],
      "footer" : {
        "type" : "TEXT",
        "message" : "Thank you"
      },
      "header" : null
    },
    "language" : "en",
    "id" : "3942000001074177",
    "message" : "Welcome to Tasty Bakery. What would you like to eat?",
    "rejectionReason" : null,
    "status" : "APPROVED"
  } ],
  "id" : "3942000001074175",
  "status" : "APPROVED"
}

Get applied Canned Message

Get a canned message or a template message with applied contact information in the placeholders

Credit: 1 credit/call

Query Params

Param Name
Data Type
Description
contactId

long

optional

Contact id for which the canned message has to be applied

sessionId

long

optional

Session id for which the canned message has to be applied

language

string

optional,
max chars : 100

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

POST /api/v1/im/cannedMessages/{template_message_id}/apply

OAuth Scope

Desk.basic.CREATE , Desk.InstantMessages.CREATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/im/cannedMessages/111000005515319/apply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2025-05-22T06:16:49.347Z",
  "departmentId" : "222222000000006907",
  "title" : "UTILITY template - orders",
  "message" : "Dear John Cena, this is the updated invoice for the month of May\n\ncheck the policy document  ",
  "type" : "TEMPLATE",
  "isActive" : true,
  "tags" : "UTILITY",
  "actor" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/11111111000005421001/photo?orgId=111111111",
    "name" : "De Paul",
    "id" : "11111111000005421001",
    "type" : "AGENT",
    "email" : "de.paul@zykler.com"
  },
  "wabaId" : "123456789123456789",
  "displayMessage" : "Dear John Cena, this is the updated invoice for the month of May\n\ncheck the policy document  ",
  "translations" : [ {
    "modifiedTime" : null,
    "displayMessage" : "Dear ${Contacts.Last Name}, this is the updated invoice for the month of May\n\ncheck the policy document ${Contacts.policy}",
    "templateItems" : {
      "buttons" : [ {
        "action" : "+1123456787",
        "type" : "PHONE_NUMBER",
        "message" : "Call us"
      }, {
        "action" : "https://www.zoho.com/visit-us",
        "type" : "URL",
        "message" : "Visit Us"
      } ],
      "footer" : null,
      "header" : {
        "attachment" : {
          "size" : "829429",
          "name" : "test.png",
          "id" : "1111000005511111",
          "type" : "image/png",
          "uuid" : "5f0a1866c9885cdcbf81ed20ca630738",
          "url" : "https://desk.zoho.com/api/v1/im/attachments/5f0a1866c9885cdcbf81ed20ca630738?orgId=111111111"
        },
        "type" : "IMAGE",
        "message" : null
      }
    },
    "language" : "en",
    "id" : "1111000005515321",
    "message" : "Dear ${Contacts.Last Name}, this is the updated invoice for the month of May\n\ncheck the policy document ${Contacts.policy}",
    "uuid" : "65f0db516cb659e3b872d579c3d81424",
    "status" : "APPROVED",
    "failedReason" : null
  } ],
  "id" : "111000005515319",
  "primaryLanguage" : "en",
  "status" : "APPROVED"
}

Pinned Conversations

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.

ATTRIBUTES

Attribute Name
Data Type
Description
type

string

The type of entity to pin. The allowed values are COMMENTS and THREADS

isPublic

boolean

The visibility of the pin.

entityId

long

ID of the entity to pin.

ids

list

IDs of the pins to delete.

Example

{
  "pinnedTime" : "2024-05-07T05:24:34Z",
  "isPublic" : true,
  "id" : "1235000000013295",
  "pinnedBy" : {
    "firstName" : "Nirmal",
    "lastName" : "Kumar",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
    "id" : "1235000000010078",
    "email" : "nirmalkumar.rs@zylker.com"
  },
  "type" : "comments",
  "pinnedEntity" : {
    "modifiedTime" : "2024-05-06T13:05:50.000Z",
    "attachments" : [ ],
    "encodedContent" : "&lt;div style&#x3d;&quot;font-size&#x3a; 13px&#x3b; font-family&#x3a; Arial, Helvetica, sans-serif&quot;&gt;&lt;div&gt;zsu&#x5b;&#x40;user&#x3a;76260187&#x5d;zsu a comment.&lt;br&gt;&lt;&#x2f;div&gt;&lt;&#x2f;div&gt;",
    "commentedTime" : "2024-05-06T13:05:50.000Z",
    "isPublic" : false,
    "id" : "1235000000013468",
    "contentType" : "html",
    "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, sans-serif\"><div>zsu[@user:76260187]zsu a comment.<br></div></div>",
    "commenterId" : "1235000000010078",
    "commenter" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
      "firstName" : "Immanuel",
      "lastName" : "T",
      "id" : "1235000000010078",
      "type" : "AGENT",
      "email" : "immanuel.t@zylker.com"
    },
    "impersonatedUser" : null,
    "mention" : [ {
      "firstName" : "Kamalesh",
      "lastName" : "SN",
      "photoURL" : "https://deskt.zoho.com/api/v1/agents/1235000000034048/photo?orgId=61815772",
      "offSet" : "77",
      "length" : "22",
      "id" : "1235000000034048",
      "type" : "AGENT",
      "email" : "kamalesh.sn@zylker.com",
      "zuid" : "76260187"
    } ]
  }
}


Create a pin on the ticket

This API creates a new pin on the ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
type

string

required,
max chars : 100

The type of entity to pin. The allowed values are COMMENTS and THREADS

isPublic

boolean

optional

The visibility of the pin.

entityId

long

required

ID of the entity to pin.

POST api/v1/tickets/{ticket_id}/pins

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1235000000013359/pins
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "isPublic" : false,
  "entityId" : "1235000000013468",
  "type" : "comments"
}'

Response Example

{
  "pinnedTime" : "2024-05-07T05:24:34Z",
  "isPublic" : false,
  "id" : "1235000000013295",
  "pinnedBy" : {
    "firstName" : "Nirmal",
    "lastName" : "Kumar",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
    "id" : "1235000000010078",
    "email" : "nirmalkumar@zylker.com"
  },
  "type" : "comments",
  "pinnedEntity" : {
    "modifiedTime" : "2024-05-06T13:05:50.000Z",
    "attachments" : [ ],
    "encodedContent" : "&lt;div style&#x3d;&quot;font-size&#x3a; 13px&#x3b; font-family&#x3a; Arial, Helvetica, sans-serif&quot;&gt;&lt;div&gt;zsu&#x5b;&#x40;user&#x3a;76260187&#x5d;zsu a comment.&lt;br&gt;&lt;&#x2f;div&gt;&lt;&#x2f;div&gt;",
    "commentedTime" : "2024-05-06T13:05:50.000Z",
    "isPublic" : false,
    "id" : "1235000000013468",
    "contentType" : "html",
    "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, sans-serif\"><div>zsu[@user:76260187]zsu a comment.<br></div></div>",
    "commenterId" : "1235000000010078",
    "commenter" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
      "firstName" : "Immanuel",
      "lastName" : "T",
      "id" : "1235000000010078",
      "type" : "AGENT",
      "email" : "immanuel.t@zylker.com"
    },
    "impersonatedUser" : null,
    "mention" : [ {
      "firstName" : "Kamalesh",
      "lastName" : "SN",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000034048/photo?orgId=61815772",
      "offSet" : "77",
      "length" : "22",
      "id" : "1235000000034048",
      "type" : "AGENT",
      "email" : "kamalesh.sn@zylker.com",
      "zuid" : "76260187"
    } ]
  }
}

Get pins of a ticket

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

Query Params

Param Name
Data Type
Description
types

string

optional,
max chars : 100

The type of pins to fetch as a comma separated list. The allowed values are comments and threads

include
see documentation

string

optional,
max chars : 100

Secondary information related to the pinned conversations. Values allowed are pinnedBy, and mentions.

GET api/v1/tickets/{ticket_id}/pins

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1235000000013359/pins?types=comments,threads
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "pinnedTime" : "2024-05-07T05:24:34Z",
    "isPublic" : true,
    "id" : "1235000000013295",
    "pinnedBy" : {
      "firstName" : "Nirmal",
      "lastName" : "Kumar",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
      "id" : "1235000000010078",
      "email" : "nirmalkumar@zylker.com"
    },
    "type" : "comments",
    "pinnedEntity" : {
      "modifiedTime" : "2024-05-06T13:05:50.000Z",
      "attachments" : [ ],
      "encodedContent" : "&lt;div style&#x3d;&quot;font-size&#x3a; 13px&#x3b; font-family&#x3a; Arial, Helvetica, sans-serif&quot;&gt;&lt;div&gt;zsu&#x5b;&#x40;user&#x3a;76260187&#x5d;zsu a comment.&lt;br&gt;&lt;&#x2f;div&gt;&lt;&#x2f;div&gt;",
      "commentedTime" : "2024-05-06T13:05:50.000Z",
      "isPublic" : false,
      "id" : "1235000000013468",
      "contentType" : "html",
      "content" : "<div style=\"font-size: 13px; font-family: Arial, Helvetica, sans-serif\"><div>zsu[@user:76260187]zsu a comment.<br></div></div>",
      "commenterId" : "1235000000010078",
      "commenter" : {
        "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
        "firstName" : "Immanuel",
        "lastName" : "T",
        "id" : "1235000000010078",
        "type" : "AGENT",
        "email" : "immanuel.t@zylker.com"
      },
      "impersonatedUser" : null,
      "mention" : [ {
        "firstName" : "Kamalesh",
        "lastName" : "SN",
        "photoURL" : "https://deskt.zoho.com/api/v1/agents/1235000000034048/photo?orgId=61815772",
        "offSet" : "77",
        "length" : "22",
        "id" : "1235000000034048",
        "type" : "AGENT",
        "email" : "kamalesh.sn@zylker.com",
        "zuid" : "76260187"
      } ]
    }
  }, {
    "pinnedTime" : "2024-05-06T05:32:47Z",
    "isPublic" : true,
    "id" : "1235000000014147",
    "pinnedBy" : {
      "firstName" : "Nirmal",
      "lastName" : "Kumar",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1235000000010078/photo?orgId=61815772",
      "id" : "1235000000010078",
      "email" : "nirmalkumar@zylker.com"
    },
    "type" : "threads",
    "pinnedEntity" : {
      "sentiment" : "NEGATIVE",
      "isDescriptionThread" : false,
      "canReply" : true,
      "bcc" : "",
      "channel" : "EMAIL",
      "aspects" : [ ],
      "source" : {
        "appName" : null,
        "extId" : null,
        "permalink" : null,
        "type" : "SYSTEM",
        "appPhotoURL" : null
      },
      "lastRatingIconURL" : null,
      "impersonatedUser" : null,
      "channelRelatedInfo" : null,
      "createdTime" : "2024-04-22T10:32:08.000Z",
      "id" : "1235000000013283",
      "contentType" : "text/html",
      "direction" : "in",
      "summary" : "Email reply...",
      "cc" : "",
      "keyWords" : [ ],
      "visibility" : "public",
      "scheduleInfo" : null,
      "author" : {
        "photoURL" : null,
        "firstName" : "Immanuel",
        "lastName" : "T",
        "id" : "1235000000011288",
        "type" : "END_USER",
        "email" : "immanuel.t@zylker.com"
      },
      "isForward" : false,
      "hasAttach" : true,
      "respondedIn" : null,
      "attachmentCount" : "1",
      "readReceipts" : null,
      "to" : "\"zylker support\"<support@zylker.com>",
      "fromEmailAddress" : "\"kamelesh sn\"<kamelsh.sn@zylker.com>",
      "actions" : [ ],
      "status" : "SUCCESS"
    }
  } ]
}

Unpin a ticket's pin

This API deletes one or more pins from a ticket.

Credit: 1 credit/call

Attributes

Param Name
Data Type
Description
ids

list

required

IDs of the pins to delete.

POST api/v1/tickets/{ticket_id}/pins/unpin

OAuth Scope

Desk.tickets.UPDATE

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1235000000013359/pins/unpin
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "ids" : [ 1235000000013295, 1235000000013345 ]
}'

Response Example

{
  "results" : [ {
    "success" : true,
    "id" : "1235000000013295"
  }, {
    "success" : false,
    "id" : "1235000000013345",
    "error" : {
      "errorMessage" : "Pin not found",
      "errorCode" : "Not Found",
      "httpCode" : 404
    }
  } ]
}

IM Metrics

Metics APIs will provide various IM agent and conversation related metrics to the managers/leads.

Get Agents Metrics

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

Query Params

Param Name
Data Type
Description
startDate

string

optional,
max chars : 100

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

endDate

string

optional,
max chars : 100

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

duration

string

required,
max chars : 100

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

attributeGroup

string

required,
max chars : 100

Denotes which attribute group data is required. Eg: RESPONSIVENESS - AVG_RESPONSE_TIME comes under responsiveness group. It's Mandatory Param. Available value is RESPONSIVENESS

attributes

string

required,
max chars : 100

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

channelIds

string

optional,
max chars : 1000

To filter Agent Metrics only on a list of channelIds. It's a Optional Param

agentIds

string

optional,
max chars : 1000

To filter Agent Metrics only for particular Agents. It's a Optional Param

departmentId

long

optional

Filter agent metrics in given department Id

integrationService

string

optional,
max chars : 100

Agent metrics for a particular integration service. Available values are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER, INSTAGRAM

basedOn

string

optional,
max chars : 100

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

GET /api/v1/im/metrics/agents

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/supportapi/api/v1/im/metrics/agents?duration=LAST_WEEK&attributeGroup=RESPONSIVENESS&attributes=ATTENDED_CHATS,AVG_PICKUP_TIME,AVG_FIRST_RESPONSE_TIME,AVG_RESPONSE_TIME&departmentId=123456000000001234
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "1"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : "00:00:23"
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "345343453"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "2"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "86434543"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "8"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "976543456"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "1"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "853447543"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "3"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "887764523"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "1"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "987654224"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "1"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "136000000321001"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "1"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "136000000414269"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "10"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "136000000537373"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "9"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "136000003639035"
  }, {
    "values" : [ {
      "attribute" : "ATTENDED_CHATS",
      "value" : "3"
    }, {
      "attribute" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "attribute" : "AVG_RESPONSE_TIME",
      "value" : null
    } ],
    "id" : "136000003759045"
  } ],
  "entityDetails" : {
    "345343453" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/435798423232323001/photo?orgId=987876543",
      "name" : "john",
      "id" : "435798423232323001",
      "email" : "john@zykler.com"
    },
    "887764523" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/232342342232323001/photo?orgId=987876543",
      "name" : "siya",
      "id" : "232342342232323001",
      "email" : "siya@zykler.com"
    },
    "853447543" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/453223242232323001/photo?orgId=987876543",
      "name" : "robert",
      "id" : "453223242232323001",
      "email" : "robert@zykler.com"
    },
    "86434543" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4212312313232323001/photo?orgId=987876543",
      "name" : "tina",
      "id" : "4212312313232323001",
      "email" : "tina@zykler.com"
    },
    "987654224" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/642323432342342333/photo?orgId=987876543",
      "name" : "donald",
      "id" : "642323432342342333",
      "email" : "donald@zykler.com"
    },
    "976543456" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/53234234234234234/photo?orgId=987876543",
      "name" : "ram",
      "id" : "53234234234234234",
      "email" : "ram@zykler.com"
    }
  },
  "entity" : "AGENT"
}

Get Session Metrics

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

Query Params

Param Name
Data Type
Description
startDate

string

optional,
max chars : 100

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

endDate

string

optional,
max chars : 100

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

duration

string

required,
max chars : 100

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

granularity

string

required,
max chars : 100

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

dimension

string

required,
max chars : 100

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

dimensionValue

string

required,
max chars : 100

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

integrationService

string

optional,
max chars : 100

Session metrics for a particular integration service. Available values are TELEGRAM, TWILIO, LINE, WECHAT, WHATSAPP, FACEBOOKMESSENGER, INSTAGRAM

channelIds

string

optional,
max chars : 1000

Filter Session metrics by channelId

departmentId

long

optional

Filter session metrics in given department Id

basedOn

string

optional,
max chars : 100

Used to select the required metrics, based on Session Started time or Ended Time. Available values are START_TIME, END_TIME

GET /api/v1/im/metrics/sessions/timeseries

OAuth Scope

Desk.basic.READ , Desk.InstantMessages.READ

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/supportapi/api/v1/im/metrics/sessions/timeseries?granularity=DAY&duration=THIS_WEEK&dimension=RESPONSIVENESS&dimensionValue=AVG_PICKUP_TIME,AVG_RESPONSE_TIME,AVG_FIRST_RESPONSE_TIME&departmentId=123456000000001234
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "aggregatedMetrics" : [ {
    "dimension" : "AVG_RESPONSE_TIME",
    "value" : "07:57:38"
  }, {
    "dimension" : "AVG_FIRST_RESPONSE_TIME",
    "value" : "07:57:48"
  }, {
    "dimension" : "AVG_PICKUP_TIME",
    "value" : "00:00:00"
  } ],
  "trendDataList" : [ {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    } ],
    "time" : "2024-11-16"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    } ],
    "time" : "2024-11-17"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : "23:52:53"
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : "23:53:22"
    } ],
    "time" : "2024-11-18"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : "00:00:00"
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : "00:00:01"
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : "00:00:01"
    } ],
    "time" : "2024-11-19"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : "00:00:00"
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : "00:00:01"
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : "00:00:01"
    } ],
    "time" : "2024-11-20"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    } ],
    "time" : "2024-11-21"
  }, {
    "data" : [ {
      "dimension" : "AVG_PICKUP_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_RESPONSE_TIME",
      "value" : null
    }, {
      "dimension" : "AVG_FIRST_RESPONSE_TIME",
      "value" : null
    } ],
    "time" : "2024-11-22"
  } ]
}

Imports

This API directly imports data to Desk without the need for bundling it into a specific file format.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

The ID of the Import request.

scopeId

string

The ID is used to uniquely identify the import scope, enabling multiple import requests within the same scope. The purpose of the scopeId is to categorize external data under a specific classification. This categorization ensures that the parent-child relationship between entities is established only within the same category. The value of scopeId will be a UUID.

groupId

long

It is a unique ID used to identify a group. All the entity data under a group is sequentially imported. The sequential import order is determined by the parent-child relationship. For instance, if the contacts are linked to specific accounts, you might need to import accounts before contacts. Following the recommended order ensures that data dependencies are correctly established and maintained within the system after the import. This practice eliminates potential data integrity issues. Note: Entity data belonging to the same group will be imported sequentially, while entity data from different groups can be imported in parallel.

importInitiatedTime

timestamp

The time at which the import request is initiated.

importCompletedTime

timestamp

The time at which the import is completed.

notifyUrl

string

Callback URL to receive notification upon the completion of a particular import.

importedBy

long

The ID of the user who submitted the import request.

hasError

boolean

The key that indicates whether the import has errors or not.

status

String

The key that returns the status of the Import request. The values are queued, scheduled, completed and systemError.

data

String

The data to be imported.

errorReportUrl

string

The URL to retrieve the import error log.

Example

{
  "importInitiatedTime" : "2018-12-17T06:40:57.109Z",
  "importCompletedTime" : "2018-12-17T12:11:04.000Z",
  "scopeId" : "7d69f2c6-1d6d-4a75-99d1-fafc4e4177a7",
  "errorReportUrl" : "https://desk.zoho.com/api/v1/importErrorLog/4000000024001",
  "runAutomation" : "false",
  "notifyUrl" : "www.demoServer.com/notifyImportStatus",
  "hasError" : true,
  "id" : "4000000024001",
  "importedBy" : "4000000016079",
  "status" : "completed"
}


Get imports

This API fetches a single import info from your help desk portal.

Credit: 1 credit/call

GET /api/v1/imports/{import_id}

OAuth Scope

Desk.imports

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/imports/1892000000042032
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "importInitiatedTime" : "2018-12-17T06:40:57.109Z",
  "importCompletedTime" : "2018-12-17T12:11:04.000Z",
  "scopeId" : "7d69f2c6-1d6d-4a75-99d1-fafc4e4177a7",
  "errorReportUrl" : "https://desk.zoho.com/api/v1/importErrorLog/4000000024001",
  "runAutomation" : "false",
  "notifyUrl" : "www.demoServer.com/notifyImportStatus",
  "hasError" : true,
  "id" : "4000000024001",
  "importedBy" : "4000000016079",
  "status" : "completed"
}

Post imports

This API add a import entry under a given scope in your help desk portal.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
scopeId

string

required,
max chars : 36

The ID is used to uniquely identify the import scope, enabling multiple import requests within the same scope. The purpose of the scopeId is to categorize external data under a specific classification. This categorization ensures that the parent-child relationship between entities is established only within the same category. The value of scopeId will be a UUID.

groupId

long

optional

It is a unique ID used to identify a group. All the entity data under a group is sequentially imported. The sequential import order is determined by the parent-child relationship. For instance, if the contacts are linked to specific accounts, you might need to import accounts before contacts. Following the recommended order ensures that data dependencies are correctly established and maintained within the system after the import. This practice eliminates potential data integrity issues. Note: Entity data belonging to the same group will be imported sequentially, while entity data from different groups can be imported in parallel.

notifyUrl

string

optional,
max chars : 500

Callback URL to receive notification upon the completion of a particular import.

data

object

optional

The data to be imported.

POST /api/v1/imports

OAuth Scope

Desk.imports

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/imports
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "scopeId" : "7d69f2c6-1d6d-4a75-99d1-fafc4e4177a7",
  "data" : {
    "endusers" : [ {
      "firstName" : "John",
      "lastName" : "Abraham",
      "phone" : null,
      "city" : null,
      "displayName" : "John",
      "mobile" : null,
      "timeZone" : "Asia/Kolkata",
      "endUserExtId" : "14091310393191",
      "countryLocale" : "en_US",
      "helpCenterId" : "894114121213421",
      "email" : [ {
        "emailAddress" : "john.ab@zylker.com",
        "isPrimary" : "true"
      } ],
      "status" : "ACTIVE"
    } ],
    "tickets" : [ {
      "modifiedTime" : "2016-10-12T06:57:38.000Z",
      "subCategory" : null,
      "contactExtId" : "externalContact1",
      "productId" : null,
      "contactId" : null,
      "subject" : "Here's your first import ticket1.",
      "departmentId" : "1000000012806",
      "channel" : "Email",
      "priority" : null,
      "assigneeId" : "1000000016086",
      "tags" : [ "meenakshi" ],
      "ticketExtId" : "externalTicket1",
      "phone" : "1 888 900 9646",
      "createdTime" : "2019-07-17T14:00:32.000Z",
      "category" : null,
      "email" : "testmail@zylker.com",
      "status" : "Open"
    }, {
      "modifiedTime" : "2016-10-12T06:57:38.000Z",
      "subCategory" : null,
      "contactExtId" : null,
      "productId" : null,
      "contactId" : 5000000016426,
      "subject" : "Here's your first import ticket2.",
      "departmentId" : "1000000012806",
      "channel" : "Email",
      "priority" : null,
      "assigneeId" : "1000000016086",
      "tags" : [ "meenakshi" ],
      "ticketExtId" : "externalTicket2",
      "phone" : "1 888 900 9646",
      "createdTime" : "2019-07-17T14:00:32.000Z",
      "category" : null,
      "email" : "testmail123@zylker.com",
      "status" : "Open"
    } ],
    "kbRootCategories" : [ {
      "isReviewEnabled" : "false",
      "visibility" : "NONE",
      "articleViewType" : "LISTVIEW",
      "translations" : [ {
        "name" : "Import sdcwed 1289",
        "locale" : "en_US",
        "permalink" : "importis1289"
      } ],
      "name" : "Import RootCatesdcwedgory 1289",
      "description" : "sdcwed data 7812899",
      "primaryDepartmentExtId" : "1000000025808",
      "kbRootCategoryExtId" : "1289",
      "status" : "SHOW_IN_HELPCENTER",
      "associatedDepartmentIds" : [ "1000000025808", "1000000069588" ]
    } ],
    "accounts" : [ {
      "modifiedTime" : "2016-10-12T06:57:38.000Z",
      "country" : "0country",
      "website" : "www.test0.com",
      "accountName" : "externalAccount-1",
      "city" : "0city",
      "customFields" : { },
      "description" : "import account",
      "industry" : "0industry",
      "accountExtId" : "externalAccount-1",
      "phone" : "+123 0",
      "street" : "0street",
      "createdTime" : "2016-08-12T06:57:38.000Z",
      "state" : "0state",
      "fax" : "+111 0",
      "email" : "02email@zylker.com"
    } ],
    "contacts" : [ {
      "zip" : 94588,
      "lastName" : " lastname 02",
      "country" : "India",
      "modifiedTime" : "2016-10-12T06:57:38.000Z",
      "contactExtId" : "externalContactWithExternalAccount-1",
      "secondaryEmail" : "00secondaryemail@zylker.com",
      "city" : "0city",
      "customFields" : { },
      "facebook" : "testfacebook",
      "mobile" : null,
      "description" : "test contact for Import",
      "title" : "Customer Support Executive",
      "type" : null,
      "accountExtId" : "externalAccount-1",
      "accountId" : null,
      "firstName" : null,
      "twitter" : "testTwitter",
      "phone" : "+1111 0",
      "street" : "0street",
      "createdTime" : "2016-08-12T06:57:38.000Z",
      "state" : "0state",
      "email" : "00email@zylker.com"
    }, {
      "zip" : 94588,
      "lastName" : " lastname 03",
      "country" : "India",
      "modifiedTime" : "2016-10-12T06:57:38.000Z",
      "contactExtId" : "externalContactWithDeskAccount",
      "secondaryEmail" : "03secondaryemail@zylker.com",
      "city" : "03city",
      "customFields" : { },
      "facebook" : "testfacebook",
      "mobile" : null,
      "description" : "test contact for Import",
      "title" : "Customer Support Executive",
      "type" : null,
      "accountExtId" : null,
      "accountId" : "359876756",
      "firstName" : null,
      "twitter" : "testTwitter",
      "phone" : "+1111 03",
      "street" : "03street",
      "createdTime" : "2016-08-12T06:57:38.000Z",
      "state" : "03state",
      "email" : "03email@zylker.com"
    } ]
  },
  "runAutomation" : true
}'

Response Example

{
  "importInitiatedTime" : "2018-12-17T06:40:57.109Z",
  "importCompletedTime" : "2018-12-17T12:11:04.000Z",
  "scopeId" : "7d69f2c6-1d6d-4a75-99d1-fafc4e4177a7",
  "errorReportUrl" : "https://desk.zoho.com/api/v1/importErrorLog/4000000024001",
  "runAutomation" : "false",
  "notifyUrl" : null,
  "hasError" : true,
  "id" : "4000000024001",
  "importedBy" : "4000000016079",
  "status" : "completed"
}

Get import Mappings

This API fetches entity id's for given external ids your help desk portal.

Credit: 3 credits/call

Note: Credits depends on the range where the records are fetched. Refer for details

Attributes

Param Name
Data Type
Description
scopeId

string

required,
max chars : 36

The ID is used to uniquely identify the Import scope, enabling multiple import requests within the same scope. The purpose of the scopeId is to categorize external data under a specific classification. This categorization ensures that the parent-child relationship between entities is established only within the same category. The value of scopeId will be a UUID.

module

String

required

The modules that are associated with the externalIds.

externalIds

list

required

The Id for which the entityId had to be fetched.

POST /api/v1/importMappings

OAuth Scope

Desk.imports

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/importMappings
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "scopeId" : "74da0304-e8e2-4f74-9da1-5359e4359d9a",
  "module" : "tickets",
  "externalIds" : [ "ticketLayout1", "ticketLayout3" ]
}'

Response Example

{
  "data" : [ {
    "externalId" : "ticketLayout1",
    "entityId" : "6000000073007"
  } ]
}

BulkExport

BulkExport helps you to export your records from helpdesk

ATTRIBUTES

Attribute Name
Data Type
Description
exportId

long

Specifies the ID of the export

module

string

The list of modules to export. Allowed values are tickets, contacts, tasks, calls, events, timeEntry, accounts, solutions, products, topics, departments, agents, teams or custom module

callBackUrl

string

Callback URL to receive notification upon the completion of a particular export.

fields

list

Fields of the selected module that are to be exported. Note: Provide the API name of the fields that are to be exported.

modifiedAfter

timestamp

Specifies the timestamp after which data modifications are included in the export.

Example

{
  "modifiedAfter" : "2019-05-06T18:20:37.733Z",
  "callBackUrl" : "https://test.com",
  "viewId" : "5000000031695",
  "hasNextPage" : false,
  "module" : "tickets",
  "departmentId" : "5000000031695",
  "fields" : [ "email", "subject", "status", "isSpam" ],
  "exportId" : "78123412123",
  "status" : "COMPLETED"
}


File Structure

Structure of the exported file

When you export data using the /api/v1/bulkExport, the resulting exported file will contain specific CSV files depending on whether the modifiedAfterkey was passed in the request or not.

If the modifiedAfterkey was not passed in the request, the exported .zip file will contain only one file mentioned below:

  • Normal Records:This will include all active records.

If the modifiedAfterkey was passed in the request, the exported .zip file contains below CSV files:

  • RestoredRecords:File containing records restored after the time specified by the modifiedAfterkey.
  • SpammedRecords:File containing the IDs and deleted time of records that were spammed after the time specified by the modifiedAfterkey.
  • TrashedRecords:File containing the IDs and deleted time of records that were trashed after the time specified by the modifiedAfterkey.
  • DeletedRecords:File containing the IDs and deleted time of the records that were deleted after the time specified by the modifiedAfterkey.
  • Normal Records:File containing active records that were added or modified after the time specified by the modifiedAfterkey.

BulkExport

  1. The exported data is provided as a set of CSV files that are zipped together.
  2. Each export request is limited to a maximum of 100,000 records.
  3. Users are limited to a maximum of 20 requests per module per day.
  4. The number of select fields for export via an endpoint is limited to a maximum of 200. If the count exceeds 200, all fields will be selected for export.
  5. You can fetch records in batches of 1 lakh using the exportId. Start with the initial export (1L records), then use the returned exportId to fetch the next set of records. Based on your needs, you can repeat the process until all records are fetched (i.e., the hasNextPage value becomes false) by passing the most recently returned exportId.

ATTRIBUTES

Attribute Name
Data Type
Description
type

string

RHS Type

primitive

object

PrimitiveValue

field

string

RHS field.

Example

{
  "modifiedAfter" : "2019-05-06T18:20:37.733Z",
  "callBackUrl" : "https://test.com",
  "viewId" : "5000000031695",
  "hasNextPage" : false,
  "module" : "tickets",
  "departmentId" : "5000000031695",
  "fields" : [ "email", "subject", "status", "isSpam" ],
  "exportId" : "78123412123",
  "status" : "COMPLETED"
}


GetExportDetails

To get Export details.

Credit: 1 credit/call

GET /api/v1/bulkExport/{export_id}

OAuth Scope

Desk.exports

Request Example

  • CURL

$ curl -X GET https://desk.zoho.com/api/v1/bulkExport/5000001003083
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedAfter" : "2019-05-06T18:20:37.733Z",
  "callBackUrl" : "https://webhook.site/c57564f2-f262-4092-adc4-7c416d401d50",
  "viewId" : "5000000031695",
  "hasNextPage" : "false",
  "module" : "tickets",
  "departmentId" : "5000000031695",
  "fields" : [ "email", "subject", "status", "isSpam" ],
  "exportId" : "5000001003083",
  "limitPerFile" : "100000",
  "status" : "INITIATED"
}

InitiateModuleExports

To initiate module Exports.

Credit: 500 credits/call

Attributes

Param Name
Data Type
Description
exportId

long

optional

Specifies the ID of the export

module

string

required,
max chars : 100

The list of modules to export. Allowed values are tickets, contacts, tasks, calls, events, timeEntry, accounts, solutions, products, topics, departments, agents, teams or custom module

callBackUrl

string

optional,
max chars : 2000

Callback URL to receive notification upon the completion of a particular export.

fields

list

optional

Fields of the selected module that are to be exported. Note: Provide the API name of the fields that are to be exported.

limitPerFile

long

optional,
range : 1000-100000

The maximum number of rows per file.

viewId

long

optional

Specifies the ID of the view from which the corresponding records will be exported.

departmentId

long

optional

Specifies the ID of the department.
Note: To export records from pre-defined views, both the viewId and departmentId must be provided; otherwise, all the view records will be fetched regardless of departments.

POST /api/v1/bulkExport

OAuth Scope

Desk.exports

Request Example

  • CURL

$ curl -X POST https://desk.zoho.com/api/v1/bulkExport
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s" 

  -d'{
  "modifiedAfter" : "2019-05-06T18:20:37.733Z",
  "exportTimeFilter" : {
    "duration" : "CUSTOM_IN_DATE",
    "endDate" : "06-06-2024",
    "filterField" : "4000000250354",
    "startDate" : "06-05-2024"
  },
  "callBackUrl" : "https://webhook.site/c57564f2-f262-4092-adc4-7c416d401d50",
  "viewId" : "5000000031695",
  "criteria" : {
    "criteriaFields" : [ {
      "condition" : "is",
      "field" : {
        "apiName" : "contactId",
        "module" : "tickets",
        "fieldLabel" : "Contact Name"
      },
      "value" : {
        "primitive" : [ {
          "key" : "13735000002029311"
        } ],
        "type" : "primitive"
      }
    }, {
      "condition" : "is not empty",
      "field" : {
        "apiName" : "contactId",
        "module" : "tickets",
        "fieldLabel" : "Contact Name"
      },
      "value" : {
        "primitive" : [ ],
        "type" : "primitive"
      }
    }, {
      "condition" : "is CLOSED",
      "field" : {
        "apiName" : "status",
        "module" : "tickets",
        "fieldLabel" : "Status"
      },
      "value" : {
        "primitive" : [ ],
        "type" : "primitive"
      }
    } ],
    "criteriaPattern" : "((1and2)and3)"
  },
  "module" : "tickets",
  "departmentId" : "5000000031695",
  "fields" : [ "email", "subject", "status", "isSpam" ]
}'

Response Example

{
  "modifiedAfter" : "2019-05-06T18:20:37.733Z",
  "callBackUrl" : "https://webhook.site/c57564f2-f262-4092-adc4-7c416d401d50",
  "viewId" : "5000000031695",
  "module" : "tickets",
  "departmentId" : "5000000031695",
  "fields" : [ "email", "subject", "status", "isSpam" ],
  "exportId" : "5000001003083",
  "limitPerFile" : "100000",
  "status" : "INITIATED"
}

Download Export File

API to download the bulk Export zip file from ZFS.

Credit: 50 credits/call

Query Params

Param Name
Data Type
Description
exportId

long

required

the id of the export which was initiated for first time

GET api/v1/downloadBulkExportFile

OAuth Scope

Desk.exports

Request Example

  • CURL

$ curl -X GET https://support.zoho.com/api/v1/downloadBulkExportFile
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Limitations

  1. The exported data is provided as a set of CSV files that are zipped together.
  2. Each export request is limited to a maximum of 100,000 records.
  3. Users are limited to a maximum of 20 requests per module per day.
  4. The number of select fields for export via an endpoint is limited to a maximum of 200. If the count exceeds 200, all fields will be selected for export.
  5. You can fetch records in batches of 1 lakh using the exportId. Start with the initial export (1L records), then use the returned exportId to fetch the next set of records. Based on your needs, you can repeat the process until all records are fetched (i.e., the hasNextPage value becomes false) by passing the most recently returned exportId.