Desk API Documentation

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

https://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.


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


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


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


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


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

Authentication

Zoho Desk's APIs can be authenticated through one of the following methods:

  • AuthToken(Deprecated)
  • OauthToken

AuthTokens (Deprecated)

You can obtain an authtoken through one of the following ways:

  1. Browser method
  2. API method

Browser Method

Obtaining an authtoken using a browser is a simple task. All that you need to do is just login to your Zoho Account and visit the following URL.


https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoSearch/SearchAPI

API Method

To obtain the authToken using an API, perform the following steps:

Submit an HTTP POST request to the following URL.


https://accounts.zoho.com/apiauthtoken/nb/create.


In the body of the POST request, include a string in the following format.


?SCOPE=ZohoSupport/supportapi,ZohoSearch/SearchAPI&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]


Below are the mandatory case-sensitive fields to be passed in the URL.


Parameter Value to Pass
SCOPE ZohoSupport/supportapi
EMAIL_ID Your Zoho ID or Email ID
PASSWORD Your Zoho password

Request Example using authtoken

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 67013ab3960787bcf3affae67e649fc0a789"


OauthTokens

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 Java-based OAuth library, click here.

Obtaining the OAuthToken

To obtain the OAuthToken for your app, perform the following steps:

1. Register the App

First, register your app in Zoho's Developer Console, which you can access here.
On successful registration, you will be provided with a client ID and a client secret. These are your OAuth credentials.


2. Obtain the Authorization Grant

Next, 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.
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. Once the user accepts, a GET request will be made to the redirect_uri with the authorization code appended in the query param.


3. Obtain the Access Token

As the final step, 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.
scope Specify the scope allowed for Zoho Desk.
grant_type "authorization_code"
redirect_uri Redirect URI mentioned while registering the client.
state State is an opaque value used by the client to maintain state between the request and callback.Has to be maintained the same during the entire process for authenticity.

After invoking the URL, you will be presented with an access token, which you must include in all API calls.



Generating Access Token from a Refresh Token

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.


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



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

Sample Success Response

Authorization Grant 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


Access Token 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
&scope=Desk.tickets.READ,Desk.basic.READ


Response Example

Generating access token using refresh token

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

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

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.

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

Required

Actual name of the organization/business

organizationName

string

Optional

(Deprecated: Use portalName attribute instead). Unique name for the organization. Only lower-case letters and numbers are allowed in the name.

portalName

string

Optional

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

phoneNumber

string

Optional

Phone number of the organization

edition

string

Optional

Zoho Desk edition purchased. Values allowed are: FREEENTERPRISE, and PROFESSIONAL.

id

long

ReadOnly

Unique ID of the organization

isDefault

boolean

ReadOnly

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

isAdminInOrg

boolean

ReadOnly

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

portalURL

string

ReadOnly

URL of the help desk

logoURL

string

ReadOnly

URL of the image file displaying the organization's logo

alias

string

Optional

Alternative name for the help desk portal

employeeCount

string

Optional

Number of employees in the organization

description

string

Optional

Brief description of the organization

mobile

string

Optional

Mobile number of the organization

website

string

Optional

Website of the organization

fax

string

Optional

Fax number of the organization

primaryContact

string

Optional

Primary contact person in the organization

street

string

Optional

Street in which the organization's office is located

city

string

Optional

City in which the organization's office is located

state

string

Optional

State in which the organization's office is located

zip

string

Optional

Zip code of the organization's address

country

string

Optional

Country in which the organization's office is located

currencyLocale

string

Optional

Currency locale in which the organization operates

Example

{ "zip" : "68838-2640", "country" : "United States", "website" : "www.zylker.com", "organizationName" : "zylker", "city" : "Bernierview", "companyName" : "Zylker INC.", "mobile" : "9848022338", "description" : "We are Zylker Support.", "edition" : "ENTERPRISE", "employeeCount" : "10", "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true, "isDefault" : "false", "phoneNumber" : "9884358081", "portalName" : "zylker", "street" : "70961 Powlowski Crossing", "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do", "primaryContact" : "steve@zylker.com", "currencyLocale" : "US", "alias" : "Zylker Teams", "id" : "3981311", "state" : "NC", "fax" : "8392839821" }



Get organization

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

Query Params

Param Name
Data Type
Description
includeCustomDomain

boolean

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

GET /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

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

Response Example

{
  "zip" : "68838-2640",
  "country" : "United States",
  "website" : "www.zylker.com",
  "organizationName" : "zylker",
  "city" : "Bernierview",
  "companyName" : "Zylker INC.",
  "mobile" : "9848022338",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
  "customDomain" : "support.zylker.com",
  "isAdminInOrg" : true,
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalName" : "zylker",
  "street" : "70961 Powlowski Crossing",
  "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
  "primaryContact" : "steve@zylker.com",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "fax" : "8392839821"
}

Get all organizations

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

GET /api/v1/organizations

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

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

Response Example

{
  "data" : [ {
    "zip" : "68838-2640",
    "country" : "United States",
    "website" : "www.zylker.com",
    "organizationName" : "zylker",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "mobile" : "9848022338",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "employeeCount" : "10",
    "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "phoneNumber" : "9884358081",
    "portalName" : "zylker",
    "street" : "70961 Powlowski Crossing",
    "portalURL" : "http://support.zylker.com/support/zylker/ShowHomePage.do",
    "primaryContact" : "steve@zylker.com",
    "currencyLocale" : "US",
    "alias" : "Zylker Teams",
    "id" : "3981311",
    "state" : "NC",
    "fax" : "8392839821"
  }, {
    "zip" : "33560-8932",
    "country" : "United States",
    "website" : "www.nshlerin.com",
    "organizationName" : "nshlerin",
    "city" : "Port Cierra",
    "companyName" : "Nshlerin LLC.",
    "mobile" : "987654321",
    "description" : "We are Nshlerin Support.",
    "edition" : "PROFESSIONAL",
    "employeeCount" : "20",
    "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "phoneNumber" : "9884309090",
    "portalName" : "nshlerin",
    "street" : "269 Adam Flats",
    "portalURL" : "http://support.nshlerin.com/support/nshlerin/ShowHomePage.do",
    "primaryContact" : "kelvin@nshlerin.com",
    "currencyLocale" : "US",
    "alias" : "Nshlerinians",
    "id" : "5988319",
    "state" : "Port Cierra",
    "fax" : "987654321"
  } ]
}

Check for duplicate organization

This API checks if multiple organizations have the same portal name.

Query Params

Param Name
Data Type
Description
portalName

string

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

GET /api/v1/organizations/checkExists

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

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

Response Example

{
  "isHelpCenterExistInPortal" : false,
  "isPortalNameExist" : true,
  "isMailBoxExist" : false
}

Create organization

This API creates an organization in your help desk. The portalName attribute is mandatory in the API request.

POST /api/v1/organizations

OAuth Scope

Desk.basic.CREATE , Desk.settings.CREATE

Request Example

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

  -d '{ "phoneNumber" : "9884358080", "portalName" : "zylker", "companyName" : "Zylker INC.", "edition" : "ENTERPRISE" }'

Response Example

{
  "zip" : "",
  "country" : "",
  "website" : "",
  "organizationName" : "zylker",
  "city" : "",
  "companyName" : "Zylker INC.",
  "mobile" : "",
  "description" : null,
  "edition" : "ENTERPRISE",
  "employeeCount" : "1",
  "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
  "isAdminInOrg" : true,
  "isDefault" : "false",
  "phoneNumber" : "9884358080",
  "portalName" : "zylker",
  "street" : "",
  "portalURL" : "http://desk.zoho.com/support/zylker/ShowHomePage.do",
  "primaryContact" : "steve@zylker.com",
  "currencyLocale" : "US",
  "alias" : null,
  "id" : "3981311",
  "state" : "",
  "fax" : ""
}

Update organization

This API updates the details of an organization.

PATCH /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.basic.UPDATE , Desk.settings.UPDATE

Request Example

$ 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

{
  "zip" : "68838-2640",
  "country" : "United States",
  "website" : "www.zylker.com",
  "organizationName" : "zylkerdesk",
  "city" : "Bernierview",
  "companyName" : "Zylker Desk",
  "mobile" : "9848022338",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "employeeCount" : "10",
  "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
  "isAdminInOrg" : true,
  "isDefault" : "false",
  "phoneNumber" : "9884358081",
  "portalName" : "zylkerdesk",
  "street" : "70961 Powlowski Crossing",
  "portalURL" : "http://support.zylker.com/support/zylkerdesk/ShowHomePage.do",
  "primaryContact" : "kelvin@zylker.com",
  "currencyLocale" : "US",
  "alias" : "Zylker Teams",
  "id" : "3981311",
  "state" : "NC",
  "fax" : "8392839821"
}

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

null

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

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

OAuth Scope

Request Example

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

File Params

favicon

Content-Type:multipart/form-data

Image file of the favicon.The maximum file size allowed is 2 MB.

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

OAuth Scope

Desk.basic.UPDATE , Desk.settings.UPDATE

Request Example

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

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

OAuth Scope

Desk.basic.DELETE , Desk.settings.DELETE

Request Example

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

POST /api/v1/organizations/markDefault

OAuth Scope

Desk.basic.UPDATE , Desk.settings.UPDATE

Request Example

$ 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

Required

Email ID of the agent

status

string

ReadOnly

Activation status of the agent: ACTIVE or DISABLED

lastName

string

Required

Last name of the agent

firstName

string

Optional

First name of the agent

phone

string

Optional

Phone number of the agent

mobile

string

Optional

Mobile number of the agent

extn

string

Optional

Extn 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

id

long

ReadOnly

ID of the agent

zuid

long

ReadOnly

Zoho user ID of the agent

roleId

long

ReadOnly

Role ID of the agent

profileId

long

ReadOnly

Profile ID of the agent

photoURL

string

ReadOnly

Photo URL of the agent

isConfirmed

boolean

ReadOnly

Confirmation status of the agent

countryCode

string

Optional

Agent country code. One can update his own countryCode only. If it is passed for other agent it will be ignored.

timeZone

string

Optional

The timeZone of the agent. Eg Asia/Calcutta, Europe/Moscow. One can update his own timeZone only. If it is passed for other agent it will be ignored.

langCode

string

Optional

The language code for the agent. One can update his own langCode only. If it is passed for other agent it will be ignored.

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", "rolePermissionType" : "Admin", "isConfirmed" : true, "id" : "1892000000056007", "status" : "ACTIVE" }



Get agent

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

Query Params

Param Name
Data Type
Description

string

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/agents/{agent_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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"

Response Example

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

List agents

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

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the agents must be limited

limit

integer

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

status

string

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

searchStr

string

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

departmentIds
see documentation

long

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

profileIds
see documentation

long

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

long

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

rolePermissionType

string

Types of roles and permissions of the agents to list. Values allowed are AgentPublic, AgentPersonal, Admin, Light, Custom, and ${NON_LIGHT}. ${NON_LIGHT} refers to agents who are not associated with the light agent profile.

isConfirmed

boolean

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

GET /api/v1/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

Response Example

{
  "data" : [ {
    "lastName" : "case",
    "extn" : "3298",
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "timeZone" : "Asia/Kolkata",
    "emailId" : "case@zylker.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "492-736-6424",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "rolePermissionType" : "Admin",
    "isConfirmed" : true,
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "jade",
    "extn" : "3203",
    "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://contacts.zoho.com/file?t=user&ID=10657727",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "rolePermissionType" : "Light",
    "isConfirmed" : true,
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "john",
    "extn" : "3228",
    "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",
    "rolePermissionType" : "AgentPersonal",
    "isConfirmed" : true,
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "Waugh",
    "extn" : "4020",
    "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",
    "rolePermissionType" : "Custom",
    "isConfirmed" : false,
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get agents count

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

Query Params

Param Name
Data Type
Description
status

string

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

isConfirmed

boolean

Filters Confirmed & Unconfirmed agents

includeLightAgent

boolean

Count light agent.

GET /api/v1/agents/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

Query Params

Param Name
Data Type
Description
agentIds

long

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 -X GET https://desk.zoho.com/api/v1/agentsByIds?agentIds=1892000000056007,1892000000042001,1892000000888059
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

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://contacts.zoho.com/file?t=user&ID=10657727",
    "roleId" : "7000000012324",
    "profileId" : "7000000012339",
    "emailId" : "jade@zylker.com",
    "id" : "1892000000042001",
    "zuid" : "279392"
  }, {
    "firstName" : "Steve",
    "lastName" : "Waugh",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657828",
    "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.

Query Params

Param Name
Data Type
Description

string

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 -X GET https://desk.zoho.com/api/v1/myinfo?include=profile,role,associatedDepartments,associatedChatDepartments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

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

Activate agents

This API activates agents in your help desk.

Note: To activate agents in CRMPlus and ZohoOne, first generate an authtoken through this URL: https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoDirectory/directoryapi

POST /api/v1/agents/activate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

POST /api/v1/agents/reinvite

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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 emailIdlastNameassociatedDepartmentIds, 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"

POST /api/v1/agents

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ 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" ] }'

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",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Update agent

This API updates details of an agent.

Note: To update details of agents in CRMPlus and ZohoOne, first generate an authtoken through this URL: https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoDirectory/directoryapi

PATCH /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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" ] }'

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",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "id" : "1892000000056007",
  "status" : "ACTIVE"
}

Delete unconfirmed agents

This API deletes unconfirmed agents from your help desk.

POST /api/v1/agents/deleteUnconfirmed

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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

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 -X POST https://desk.zoho.com/api/v1/uploadMyPhoto
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669"
}

Delete My Photo

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

POST /api/v1/deleteMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

GET /api/v1/myPreferences

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" ],
  "datePattern" : "dd/MM/yyyy",
  "currentDepartment" : "allDepartment"
}

Update My Preferences

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

PATCH /api/v1/myPreferences

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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" ], "currentDepartment" : "1892000000082069" }'

Response Example

204

Get agent by email ID

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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",
  "rolePermissionType" : "Admin",
  "isConfirmed" : true,
  "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.

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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

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

Required

Name of the profile

description

string

Optional

Description of the profile

isVisible

boolean

ReadOnly

If the profile is visible in UI

type

string

ReadOnly

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

default

boolean

ReadOnly

If the profile is system generated

id

long

ReadOnly

Id of the profile

permissions

object

Optional

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, "mailReview" : true, "delete" : true, "view" : true, "create" : true, "addFollowers" : true, "export" : true, "mailSend" : true, "unassignedChangeOwner" : false, "shareTickets" : true }, "comments" : { "edit" : true, "delete" : true }, "social" : { "view" : true }, "contracts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "community" : { "view" : true }, "products" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "kbCategory" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "setup" : { "timeTracking" : true, "fetchAcrossDepartment" : true, "globalReports" : true, "exportPortalUsers" : true, "layouts" : true, "userAndGroups" : true, "automation" : true, "customerHappiness" : true, "department" : true, "portal" : true, "webForm" : true, "rebranding" : true, "email" : true, "tabsAndFields" : true, "exportUsers" : true, "social" : true, "templates" : true, "moveRecords" : true, "permission" : true, "signUpApproval" : true, "community" : true, "importHistory" : true, "portalUsers" : true, "managerDashboard" : true, "chat" : true, "telephony" : true }, "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.

Query Params

Param Name
Data Type
Description
visible

boolean

Key that filters profiles according to their visibility in the UI

default

boolean

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

searchStr

string

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.basic.READ , Desk.settings.READ

Request Example

$ 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,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : true
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "kbCategory" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : true,
        "fetchAcrossDepartment" : true,
        "globalReports" : true,
        "exportPortalUsers" : true,
        "layouts" : true,
        "userAndGroups" : true,
        "automation" : true,
        "customerHappiness" : true,
        "department" : true,
        "portal" : true,
        "webForm" : true,
        "rebranding" : true,
        "email" : true,
        "tabsAndFields" : true,
        "exportUsers" : true,
        "social" : true,
        "templates" : true,
        "moveRecords" : true,
        "permission" : true,
        "signUpApproval" : true,
        "community" : true,
        "importHistory" : true,
        "portalUsers" : true,
        "managerDashboard" : true,
        "chat" : true,
        "telephony" : true
      },
      "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,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : false,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : 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
      },
      "kbCategory" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "portalUsers" : false,
        "managerDashboard" : true,
        "chat" : false,
        "telephony" : 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,
        "mailReview" : false,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : false,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : 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
      },
      "kbCategory" : {
        "view" : true,
        "import" : false,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : false
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "chat" : false,
        "telephony" : 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,
        "mailReview" : false,
        "delete" : false,
        "view" : true,
        "create" : true,
        "addFollowers" : false,
        "export" : true,
        "mailSend" : false,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : false,
        "delete" : false
      },
      "social" : {
        "view" : false
      },
      "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
      },
      "kbCategory" : {
        "view" : true,
        "import" : false,
        "edit" : false,
        "create" : false,
        "delete" : false,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : false,
        "globalReports" : false,
        "exportPortalUsers" : false,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : false,
        "social" : false,
        "templates" : false,
        "moveRecords" : false,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : false,
        "portalUsers" : false,
        "managerDashboard" : false,
        "chat" : false,
        "telephony" : 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,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "kbCategory" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "portalUsers" : false,
        "managerDashboard" : false,
        "chat" : false,
        "telephony" : 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,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "kbCategory" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : false,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "portalUsers" : false,
        "managerDashboard" : true,
        "chat" : false,
        "telephony" : 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,
        "mailReview" : true,
        "delete" : true,
        "view" : true,
        "create" : true,
        "addFollowers" : true,
        "export" : true,
        "mailSend" : true,
        "unassignedChangeOwner" : false,
        "shareTickets" : false
      },
      "comments" : {
        "edit" : true,
        "delete" : true
      },
      "social" : {
        "view" : true
      },
      "contracts" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "community" : {
        "view" : true
      },
      "products" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "kbCategory" : {
        "view" : true,
        "import" : true,
        "edit" : true,
        "create" : true,
        "delete" : true,
        "export" : true
      },
      "setup" : {
        "timeTracking" : false,
        "fetchAcrossDepartment" : true,
        "globalReports" : false,
        "exportPortalUsers" : true,
        "layouts" : false,
        "userAndGroups" : false,
        "automation" : true,
        "customerHappiness" : false,
        "department" : false,
        "portal" : false,
        "webForm" : false,
        "rebranding" : false,
        "email" : false,
        "tabsAndFields" : false,
        "exportUsers" : true,
        "social" : false,
        "templates" : false,
        "moveRecords" : true,
        "permission" : false,
        "signUpApproval" : false,
        "community" : false,
        "importHistory" : true,
        "portalUsers" : false,
        "managerDashboard" : true,
        "chat" : false,
        "telephony" : 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.

Query Params

Param Name
Data Type
Description
visible

boolean

Key that filters profiles according to their visibility in the UI

default

boolean

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

GET /api/v1/profiles/count

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

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

GET /api/v1/profiles/{profile_id}

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

$ 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,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "kbCategory" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "userAndGroups" : true,
      "automation" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "chat" : true,
      "telephony" : true
    },
    "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.

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

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ 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,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "kbCategory" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "userAndGroups" : false,
      "automation" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "portalUsers" : false,
      "managerDashboard" : false,
      "chat" : false,
      "telephony" : 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.

PATCH /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "kbCategory" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "userAndGroups" : false,
      "automation" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "portalUsers" : false,
      "managerDashboard" : false,
      "chat" : false,
      "telephony" : 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.

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

$ 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 permissions

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

GET /api/v1/myProfilePermissions

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

$ 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,
      "mailReview" : true,
      "delete" : true,
      "view" : true,
      "create" : true,
      "addFollowers" : true,
      "export" : true,
      "mailSend" : true,
      "unassignedChangeOwner" : false,
      "shareTickets" : true
    },
    "comments" : {
      "edit" : true,
      "delete" : true
    },
    "social" : {
      "view" : true
    },
    "contracts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "community" : {
      "view" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "kbCategory" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "userAndGroups" : true,
      "automation" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "chat" : true,
      "telephony" : true
    },
    "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.

Query Params

Param Name
Data Type
Description
active

boolean

Activation status of the agents to list

confirmed

boolean

Confirmation status of the agents to list

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

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

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

GET /api/v1/lightAgentProfile

OAuth Scope

Desk.basic.READ , Desk.settings.READ

Request Example

$ 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,
      "mailReview" : false,
      "delete" : false,
      "view" : true,
      "create" : false,
      "addFollowers" : false,
      "export" : true,
      "mailSend" : false,
      "unassignedChangeOwner" : false,
      "shareTickets" : false
    },
    "comments" : {
      "edit" : false,
      "delete" : false
    },
    "social" : {
      "view" : 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
    },
    "kbCategory" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : false,
      "layouts" : false,
      "userAndGroups" : false,
      "automation" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : false,
      "social" : false,
      "templates" : false,
      "moveRecords" : false,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : false,
      "portalUsers" : false,
      "managerDashboard" : true,
      "chat" : false,
      "telephony" : 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

Required

Name of the role

description

string

Optional

A short description of the role

isVisible

boolean

ReadOnly

Key that denotes if the role is visible in the UI

isDefault

boolean

ReadOnly

Key that denotes if the role is the default role

shareDataWithPeers

boolean

Required

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

id

long

ReadOnly

ID of the role

reportsTo

long

Optional

ID of the role to which the current role reports

immediateSubRoles

list

ReadOnly

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.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the roles must be listed

limit

integer

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

isVisible

boolean

Key that filters roles according to their visibility in the UI

isDefault

boolean

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

searchStr

string

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 -X GET http://desk.zoho.com/api/v1/roles&orgId=123456
  -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.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

POST /api/v1/roles

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

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

PATCH /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

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

GET /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

Query Params

Param Name
Data Type
Description
isVisible

boolean

Key that filters roles according to their visibility in the UI

isDefault

boolean

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

GET /api/v1/personalRole

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

Query Params

Param Name
Data Type
Description

long

Comma separated role ids. Maximum allowed count is 50

GET /api/v1/rolesByIds

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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

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

list

Optional

List of sub-teams within the team

list

Optional

List of roles to add to the team

rolesWithSubordinates

list

Optional

List of roles with subordinates to add to the team

list

Optional

List of agents to add to the team

derivedAgents

list

ReadOnly

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" ], "agents" : [ "6000000009086", "6000000012003" ] }



Create team

This API creates a team in your help desk portal.

POST /api/v1/teams

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ 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" ],
  "agents" : [ "6000000009086" ]
}

Update team

This API updates details of an existing team.

PATCH /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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" ],
  "agents" : [ "6000000009086" ]
}

Delete team

This API deletes an existing team from your help desk portal. To reassign the open 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.

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

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

GET /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" ],
  "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.

GET /api/v1/teams

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000009326",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ ],
    "id" : "17000000013005",
    "subTeams" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "17000000007253",
    "roles" : [ ],
    "name" : "Engineering",
    "description" : "Developers and Engineers.",
    "derivedAgents" : [ ],
    "id" : "17000000013001",
    "subTeams" : [ ],
    "agents" : [ ]
  } ]
}

List details of team members

This API fetches details of all the members of a particular team.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "agents" : [ "6000000011313" ]
  } ]
}

List associated teams for a role

This API fetches details of all the teams associated with a particular role.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" : [ ],
    "agents" : [ ]
  }, {
    "rolesWithSubordinates" : [ ],
    "departmentId" : "60000000839483",
    "roles" : [ "6000000008684" ],
    "name" : "Support Teams",
    "description" : "Support teams for solving customer issues.",
    "derivedAgents" : [ "6000000011313" ],
    "id" : "6000000083034",
    "subTeams" : [ ],
    "agents" : [ "6000000011313" ]
  } ]
}

List teams in department

This API fetches details of all the teams in a particular department.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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" : [ ],
    "agents" : [ "6000000009086" ]
  }, {
    "rolesWithSubordinates" : [ "6000000008684", "6000000008686" ],
    "roles" : [ "6000000011311", "6000000011309", "6000000011307" ],
    "departmentId" : "6000000007245",
    "name" : "Managers",
    "derivedAgents" : [ "6000000009086" ],
    "description" : "Managers",
    "id" : "6000000016007",
    "subTeams" : [ "6000000016011", "6000000014005" ],
    "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

ReadOnly

ID of the department

name

string

Required

Name of the department

nameInCustomerPortal

string

Optional

Display name of the department in the help center

description

string

Optional

A short description of the department

isVisibleInCustomerPortal

boolean

Optional

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

isEnabled

boolean

ReadOnly

Key that denotes if the department is enabled or not

isAssignToTeamEnabled

boolean

Optional

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

hasLogo

boolean

ReadOnly

Key that denotes if the department has a logo

creatorId

long

ReadOnly

ID of user who created the department

associatedAgentIds

list

Required

IDs of agents associated with the department

isDefault

boolean

ReadOnly

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

Example

{ "isAssignToTeamEnabled" : true, "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.", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "id" : "1892000000082069", "nameInCustomerPortal" : "ZylCares" }



Get department

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

GET /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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,
  "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.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ],
  "id" : "1892000000082069",
  "nameInCustomerPortal" : "ZylCares"
}

List departments

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

Query Params

Param Name
Data Type
Description
isEnabled

boolean

Key that filters departments based on their enabled status

from

integer

Index number, starting from which the departments must be listed

searchStr

string

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

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

GET /api/v1/departments

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

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

Response Example

{
  "data" : [ {
    "isAssignToTeamEnabled" : true,
    "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.",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "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.",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

List agents in department

This API lists the agents in a department.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the agents must be listed

limit

integer

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

status

string

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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",
    "isConfirmed" : true,
    "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",
    "isConfirmed" : true,
    "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",
    "isConfirmed" : true,
    "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",
    "isConfirmed" : false,
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Get department count

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

Query Params

Param Name
Data Type
Description
isEnabled

boolean

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

Query Params

Param Name
Data Type
Description
departmentIds

long

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 -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,
    "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.",
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "ZylCares"
  }, {
    "isAssignToTeamEnabled" : true,
    "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.",
    "id" : "1892000000082085",
    "nameInCustomerPortal" : "zPad"
  } ]
}

Check for duplicate departments

This API checks if multiple departments have the same name.

Query Params

Param Name
Data Type
Description
departmentName

string

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

POST /api/v1/departments

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

$ 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,
  "isDefault" : false,
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "isEnabled" : true,
  "name" : "zPhone",
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone"
}

Update department

This API updates the details of an existing department.

PATCH /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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,
  "isDefault" : false,
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "isEnabled" : true,
  "name" : "zPhone",
  "creatorId" : "1892000000042001",
  "description" : "With the most advanced technology, the zPhone is the world’s largest selling smartphone.",
  "associatedAgentIds" : [ "1892000000042001", "1892000000056007" ],
  "id" : "1892000000082085",
  "nameInCustomerPortal" : "zPhone Support"
}

Disable department

This API disables a department in your help desk portal.

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

$ 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

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

ReadOnly

ID of the ticket

subject

string

Required

Subject of the ticket

departmentId
see documentation

long

Required

Department to which the ticket belongs

referred object

Required

Contact who raised the ticket

productId

referred object

Optional

Product to which the ticket is mapped

list

Optional

List of attachments in the ticket. For more information, refer to the Uploads API documentation

email

string

Optional

Email ID in the ticket

phone

string

Optional

Phone number in the ticket

description

string

Optional

Description of the ticket

status

string

Optional

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

statusType

string

ReadOnly

Type of ticket resolution status.The possible values can be OPEN and CLOSED.

assigneeId

long

Optional

ID of agent to whom the ticket is assigned

category

string

Optional

Ticket category

subCategory

string

Optional

Ticket subcategory

resolution

string

Optional

Resolution of the ticket

dueDate

timestamp

Optional

Due date for resolving the ticket

priority

string

Optional

Priority of the ticket

channel

string

Optional

Channel through which the ticket originated.

classification

string

Optional

Ticket classification

customFields

JSONObject

Optional

Custom fields in the ticket

webUrl

string

Optional

URL to access the resource

createdTime

timestamp

ReadOnly

Time of creating the ticket

modifiedTime

timestamp

ReadOnly

Time of modifying the ticket

timeEntryCount

integer

ReadOnly

Number of time entries associated with the ticket

approvalCount

integer

ReadOnly

Number of approvals associated with the ticket

commentCount

integer

ReadOnly

Number of comments in the ticket

attachmentCount

integer

ReadOnly

Number of attachments in the ticket

taskCount

integer

ReadOnly

Number of tasks associated with the ticket

threadCount

integer

ReadOnly

Number of threads in the ticket

isDeleted

boolean

ReadOnly

Field that denotes whether the ticket is in trash.This key is deprecated. Use isTrashed instead

isTrashed

boolean

ReadOnly

Field that denotes whether the ticket is in trash

product

Product

ReadOnly

Product associated with the ticket. You obtain this information using the include:product query param.

closedTime

timestamp

ReadOnly

Time of closing the ticket

ticketNumber

integer

ReadOnly

Index number of the ticket

contact

Contact

ReadOnly

Secondary information related to the contact who raised the ticket. You obtain this information using the include:contact query param

customerResponseTime

timestamp

ReadOnly

Time of receiving the customer response

isRead

boolean

ReadOnly

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

object

ReadOnly

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

teamId

long

Optional

ID of the team assigned to resolve the ticket

isFollowing

boolean

ReadOnly

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

department

object

ReadOnly

Details of the department to which the ticket belongs

object

ReadOnly

Details of the team assigned to resolve the ticket

channelRelatedInfo

object

ReadOnly

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.

Example

{ "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", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority", "resolution" : null, "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "isTrashed" : false, "contact" : { "lastName" : "Carol", "firstName" : "Lucas", "phone" : "1 888 900 9646", "id" : "1892000000042032", "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", "product" : null, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "team" : { "name" : "kjsdfjks", "id" : "8920000000069071" }, "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", "assignee" : { "firstName" : "dasca", "lastName" : "vins", "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo", "id" : "1892000000056007", "email" : "jack@asdad.com" }, "category" : "general", "status" : "Open" }



Get a ticket

This API fetches a single ticket from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Key that fetches secondary information related to the ticket. Values allowed are: contacts, products, assignee, departments and team . Multiple values can be passed, with commas for separation.

GET /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.READ

Request Example

$ 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",
  "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",
  "customFields" : {
    "secondaryEmail" : null,
    "ModelName" : "F3 2017",
    "severityPercentage" : "0.0",
    "phone" : null,
    "numberOfItems" : null,
    "dateofPurchase" : null,
    "permanentAddress" : null,
    "url" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "description" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
  "resolution" : null,
  "closedTime" : null,
  "sharedCount" : "3",
  "approvalCount" : "1",
  "timeEntryCount" : "3",
  "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,
  "contact" : {
    "lastName" : "Carol",
    "firstName" : "Lucas",
    "phone" : "1 888 900 9646",
    "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",
  "id" : "1892000000042034",
  "department" : {
    "name" : "dasdasdasd",
    "id" : "1892000000006907"
  },
  "followerCount" : "5",
  "email" : "carol@zylker.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "product" : null,
  "isFollowing" : "true",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "team" : {
    "name" : "kjsdfjks",
    "id" : "8920000000069071"
  },
  "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",
  "tagCount" : "2",
  "attachmentCount" : "1",
  "assignee" : {
    "firstName" : "dasca",
    "lastName" : "vins",
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
    "id" : "1892000000056007",
    "email" : "jack@asdad.com"
  },
  "category" : "general",
  "status" : "Open"
}

List all tickets

This API lists a particular number of tickets from your help desk, based on the limit specified.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the tickets must be listed

limit

integer

Number of tickets to fetch

departmentId
see documentation

long

ID of the department from which the tickets must be fetched (Please note that this key will be deprecated soon and replaced by the departmentIds key.)

departmentIds
see documentation

long

Departments from which the tickets need to be queried

long

ID of the view to apply while fetching the resources

assignee

string

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

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

status

string

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

sortBy

string

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

receivedInDays

integer

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

string

Additional information related to the tickets. Values allowed are: contactsproducts, departmentsteamisRead, and assignee. You can pass multiple values by separating them with commas in the API request.

priority

string

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 -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,
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "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",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "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@asdad.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",
    "isRead" : false,
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : 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",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "casie@zylker.com",
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "isRead" : true,
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : 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",
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

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.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the tickets must be listed

limit

integer

Number of tickets to fetch

departmentId
see documentation

long

ID of the department from which the tickets must be fetched

assignee

string

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

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

follower

string

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

commenter

string

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

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

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

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

string

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 -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",
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-09-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "phone" : "1 888 900 9646",
      "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",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.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",
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : 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",
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "72",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Closed"
  }, {
    "ticketNumber" : "191",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "closedTime" : null,
    "sharedCount" : "0",
    "responseDueDate" : "2017-10-05T11:21:07.000Z",
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "phone" : 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",
    "email" : "casie@zylker.com",
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "productId" : null,
    "contactId" : "1892000000045028",
    "threadCount" : "19",
    "priority" : "High",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

Create a ticket

This API creates a ticket in your helpdesk.

POST /api/v1/tickets

OAuth Scope

Desk.tickets.CREATE

Request Example

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

  -d '{ "subCategory" : "Sub General", "productId" : "", "contactId" : "1892000000042032", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hai This is Description", "priority" : "High", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "general", "email" : "carol@zylker.com", "status" : "Open" }'

Response Example

{
  "modifiedTime" : "2016-06-21T12:50:04.000Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "customFields" : {
    "secondaryEmail" : null,
    "ModelName" : "F3 2017",
    "severityPercentage" : "0.0",
    "phone" : null,
    "numberOfItems" : null,
    "dateofPurchase" : null,
    "permanentAddress" : null,
    "url" : null
  },
  "dueDate" : "2016-06-21T18:50:04.573Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "Hai This is description",
  "resolution" : null,
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "channelRelatedInfo" : null,
  "isDeleted" : "false",
  "isTrashed" : false,
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "carol@zylker.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "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",
  "category" : "general",
  "status" : "Open"
}

Update a ticket

This API updates an existing ticket.

Query Params

Param Name
Data Type
Description
disableClosureNotification

boolean

disable Closure Notification use this param.

PATCH /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

  -d '{ "subCategory" : "Sub General", "productId" : "", "contactId" : "1892000000042032", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "channel" : "FORUMS", "description" : "Sample Ticket", "priority" : "Low", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "general", "email" : "carol@zylker.com", "status" : "Open" }'

Response Example

{
  "modifiedTime" : "2016-06-21T12:58:09.122Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "customFields" : {
    "secondaryEmail" : null,
    "ModelName" : "F3 2017",
    "severityPercentage" : "0.0",
    "phone" : null,
    "numberOfItems" : null,
    "dateofPurchase" : null,
    "permanentAddress" : null,
    "url" : null
  },
  "dueDate" : "2016-06-23T12:58:09.211Z",
  "departmentId" : "1892000000006907",
  "channel" : "FORUMS",
  "description" : "Sample Ticket",
  "resolution" : null,
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "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",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "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",
  "category" : "general",
  "status" : "Open"
}

Move Tickets to trash

This API moves tickets to the Recycle Bin

POST /api/v1/tickets/moveToTrash

OAuth Scope

Desk.tickets.DELETE

Request Example

$ 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

Merge two tickets

This API merges two different tickets.

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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

{
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Real Time analysis Requirement",
  "customFields" : {
    "secondaryEmail" : null,
    "ModelName" : "F3 2017",
    "severityPercentage" : "0.0",
    "phone" : null,
    "numberOfItems" : null,
    "dateofPurchase" : null,
    "permanentAddress" : null,
    "url" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "42000000006907",
  "channel" : "Email",
  "description" : "Real Time analysis Requirement",
  "resolution" : null,
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "4000000008749",
  "email" : "carol@zylker.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "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",
  "attachmentCount" : "1",
  "category" : "general",
  "status" : "Open"
}

Move ticket

This API moves a ticket from one department to another.

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

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

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

Response Example

200

Split tickets

This API splits a thread into a ticket.

POST /api/v1/tickets/{ticket_id}/thread/{thread_id}/split

OAuth Scope

Desk.tickets.CREATE

Request Example

$ 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",
  "customFields" : {
    "secondaryEmail" : null,
    "ModelName" : "F3 2017",
    "severityPercentage" : "0.0",
    "phone" : null,
    "numberOfItems" : null,
    "dateofPurchase" : null,
    "permanentAddress" : null,
    "url" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "Real Time analysis Requirement",
  "resolution" : null,
  "closedTime" : null,
  "sharedCount" : "0",
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "channelRelatedInfo" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "email" : "carol@zylker.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "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",
  "category" : "general",
  "status" : "Open"
}

Update many tickets

This API updates multiple tickets at once.

POST /api/v1/tickets/updateMany

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

POST /api/v1/closeTickets

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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 spam

This API marks a ticket as spam.

POST /api/v1/tickets/markSpam

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

  -d '{ "ids" : [ 1892000001021097 ], "isSpam" : "true" }'

Response Example

200

List tickets by CRMType

This API lists tickets by contact types as categorized in Zoho CRM.

Query Params

Param Name
Data Type
Description
from

int

Index number, starting from which the tickets must be listed

limit

int

Number of tickets to fetch

departmentId
see documentation

long

ID of the department from which the tickets must be fetched

crmContactType
see documentation

string

Contact type as set in Zoho CRM. Values allowed areunmapped,contacts_leads,potentials, and customers

string

Additional information related to the tickets. Values allowed are: contactsproducts, departmentsteamisRead, and assignee. You can pass multiple values by separating them with commas in the API request.

GET /api/v1/ticketsByCrmContactType

OAuth Scope

Desk.tickets.READ

Request Example

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

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "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",
    "isRead" : true,
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "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",
    "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"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "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@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Hi. There is a sudden delay in the processing of the orders. Check this with high priority",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "isRead" : true,
    "channel" : "Facebook",
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebbcaefeb9d93ba74750b02843cad3b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

List tickets by due minutes

This API lists tickets by the due time for resolution.

Query Params

Param Name
Data Type
Description
from

int

Index number, starting from which the tickets must be listed

limit

int

Number of tickets to fetch

departmentId
see documentation

long

ID of the department from which the tickets must be fetched

dueInMinutes
see documentation

integer

Number of minutes left for resolving the ticket. Currently, the minimum number of minutes is 15 and the maximum is 2,880. This query param can return overdue and no-due tickets too. Values allowed areoverDue,15,30,45,60,90,120,180,360,540,720,1080,1440,2880,noDue, andonhold.

string

Additional information related to the tickets. Values allowed are: contactsproducts, departmentsteamisRead, and assignee. You can pass multiple values by separating them with commas in the API request.

GET /api/v1/ticketsByDueInMinutes

OAuth Scope

Desk.tickets.READ

Request Example

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

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : true,
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@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" : "lawrence@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "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@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "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,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "accountName" : "desk Account",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2014-03-06T09:34:53.000Z",
    "id" : "1892000000093205",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "lawrence@zylker.com",
    "customerResponseTime" : "2014-03-11T07:51:29.618Z",
    "productId" : null,
    "contactId" : "1892000000093203",
    "threadCount" : "43",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebc54aeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "Open"
  } ]
}

List tickets by status

This API fetches tickets by resolution status.

Query Params

Param Name
Data Type
Description
from

int

Index number, starting from which the tickets must be listed

limit

int

Number of tickets to fetch

departmentId
see documentation

long

ID of the department from which the tickets must be fetched

string

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

string

Additional information related to the tickets. Values allowed are: contactsproducts, departmentsteamisRead, and assignee. You can pass multiple values by separating them with commas in the API request.

GET /api/v1/ticketsByStatus

OAuth Scope

Desk.tickets.READ

Request Example

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

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "subCategory" : null,
    "statusType" : "Open",
    "subject" : "Real Time analysis Requirement",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "isRead" : false,
    "closedTime" : null,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@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" : "lawrence@zylker.com",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "121",
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247ca87daeb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=298902",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "On Hold"
  }, {
    "ticketNumber" : "169",
    "subCategory" : null,
    "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,
    "sharedCount" : "0",
    "contact" : {
      "lastName" : "Lawrence",
      "firstName" : "Jonathan",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "lawrence@zylker.com",
      "account" : {
        "website" : null,
        "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"
    },
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9eb9bb9d93ba74750b0284bc703b38",
    "teamId" : "8920000000069071",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=298902",
      "id" : "1892000000042001",
      "email" : "jack@asdad.com"
    },
    "category" : null,
    "status" : "On Hold"
  } ]
}

List all ticketQueueView count

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

Query Params

Param Name
Data Type
Description
viewId

long

ID of the view whose ticket count must be fetched

departmentId
see documentation

String

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

agentId

long

ID of the agent assigned to resolve the tickets

GET api/v1/ticketQueueView/count

OAuth Scope

Desk.tickets.READ

Request Example

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

Query Params

Param Name
Data Type
Description
departmentId
see documentation

String

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

IDs of the agents whose ticket count must be fetched

GET api/v1/agentsTicketsCount

OAuth Scope

Desk.tickets.READ

Request Example

$ 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" : [ {
    "agentId" : "4000000008734",
    "dueIn1HrCount" : 0,
    "overDueCount" : 2,
    "channel" : [ "Mail", "Phone" ],
    "isOnline" : true,
    "openCount" : 18
  }, {
    "agentId" : "4000000056010",
    "dueIn1HrCount" : 0,
    "overDueCount" : 0,
    "isOnline" : false,
    "openCount" : 0
  } ]
}

Get ticket resolution

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

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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" : 160200000000068005,
    "email" : "saranraj.shanugam@zohocorp.com"
  },
  "content" : "test resolution API"
}

Get resolution history

This API fetches the resolution history of a ticket

Query Params

Param Name
Data Type
Description
from

int

Index number starting from which records must be fetched

limit

int

Number of records to fetch

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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" : 160200000000068005,
      "email" : "saranraj.shanugam@zohocorp.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" : 160200000000068005,
      "email" : "saranraj.shanugam@zohocorp.com"
    },
    "content" : "add ticket resolution"
  } ]
}

Get a ticket comment history

This API fetches the history of comments recorded on a ticket, including instances of adding and editing the comments.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the comment activities must be fetched

limit

integer

Number of comment activities to fetch

GET api/v1/tickets/{ticket_id}/comments/{comment_id}/history

OAuth Scope

Desk.tickets.get

Request Example

$ 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" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "adsada",
      "type" : "AGENT",
      "email" : "hagdsag@hfhjd.com"
    }
  }, {
    "attachments" : [ "sample.png", "sam.txt" ],
    "commentedTime" : "2013-11-04T11:21:07.912Z",
    "isPublic" : true,
    "commenterId" : 13231241244,
    "content" : "hello comment",
    "commenter" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2000000012629/photo?orgId=292828",
      "name" : "adsada",
      "type" : "AGENT",
      "email" : "hagdsag@hfhjd.com"
    }
  } ]
}

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

ReadOnly

ID of the thread

channel

string

Optional

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

status

string

ReadOnly

Status of the thread.Possible values are(SUCCESS,PENDING,FAILED,DRAFT)

content

string

Required

Content of the thread

contentType

string

Optional

Used to denote the content-type(need to be given only when channel is EMAIL) which maybe html or plainText. The default type is plainText.

isForward

boolean

Optional

States whether the thread data was forwarded, applicable only for EMAIL

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 this thread is a reply, applicable only for EMAIL

list

Optional

List of attachment IDs, applicable only for EMAIL. You can obtain attachment IDs from Uploads API

createdTime

timestamp

ReadOnly

Time of thread creation

direction

string

Optional

Returns whether the thread is incoming or outgoing

object

ReadOnly

Details of the thread Author.

fromEmailAddress
see documentation

string

Optional

Mandatory param for creating an email thread, applicable only for EMAIL, ONLINE_CHAT, OFFLINE_CHAT, CUSTOMERPORTAL, and FORUMS.

to

string

Optional

To ID in the thread, applicable only for EMAIL

cc

string

Optional

CC-ed email ID, if any exist. Applicable only for EMAIL

bcc

string

Optional

BCC-ed email ID, if any exist. Applicable only for EMAIL

phoneno

string

ReadOnly

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

summary

string

ReadOnly

Summary of the thread

attachments

object

ReadOnly

Attachments in the thread

hasAttach

boolean

Optional

States whether the thread has attachments

isDescriptionThread

boolean

ReadOnly

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

channelRelatedInfo

object

ReadOnly

Secondary information related to the channel of the thread. Currently, this key is supported only for the Forums channel. Therefore, the API response will not return this information for threads generated through other channels

list

ReadOnly

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.

Example

{ "hasAttach" : true, "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" } ], "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade@zylker.zohodesk.com" }, "channel" : "FORUMS", "createdTime" : "2016-03-21T08:46:48.248Z", "id" : "1892000000135387", "actions" : [ ], "content" : "How was our Customer Service ?", "status" : "SUCCESS", "direction" : "out" }



Get a thread

This API fetches a single thread from your helpdesk.

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

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000135387
  -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",
  "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,
  "visibility" : "public",
  "author" : {
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@gmail.com"
  },
  "fullContentURL" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/fullContent",
  "channel" : "EMAIL",
  "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,
  "channelRelatedInfo" : null,
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "attachmentCount" : "1",
  "to" : "techsupport@zylker.zohodesk.com",
  "id" : "1892000000135387",
  "fromEmailAddress" : "jade12tywin@gmail.com",
  "actions" : [ ],
  "status" : "SUCCESS",
  "direction" : "in"
}

Get Latest thread

This API fetches the latest thread recorded on a ticket.

Query Params

Param Name
Data Type
Description
needPublic

boolean

Key that denotes if the thread must be a public thread

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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" : "",
  "visibility" : "public",
  "author" : {
    "photoURL" : null,
    "name" : "Jade Tywin",
    "type" : "END_USER",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "EMAIL",
  "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,
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "to" : "techsupport@zylker.zohodesk.com",
  "id" : "1892000001083008",
  "fromEmailAddress" : "jade12tywin@gmail.com",
  "actions" : [ ],
  "status" : "SUCCESS",
  "direction" : "in"
}

List all threads

This API lists all threads in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

The from index of the threads

limit

integer

The number of threads in the case to be displayed

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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,
    "visibility" : "public",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "FORUMS",
    "hasAttach" : false,
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true"
    },
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "7",
    "id" : "1892000000413186",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "summary" : "Customer Rating",
    "cc" : "",
    "isDescriptionThread" : false,
    "bcc" : "",
    "visibility" : "public",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "EMAIL",
    "isForward" : false,
    "hasAttach" : true,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : null,
    "createdTime" : "2016-05-25T10:06:09.686Z",
    "attachmentCount" : "4",
    "id" : "1892000001004072",
    "to" : "carol@zoho.com",
    "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/resendFailedThread?threadId=1892000001083008"
    } ],
    "status" : "FAILED",
    "direction" : "out"
  }, {
    "summary" : "Please fix this problem, since it is urgent posted the issue on Facebook ",
    "isDescriptionThread" : false,
    "visibility" : "public",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FACEBOOK",
    "hasAttach" : false,
    "responderId" : "2150000000043591",
    "channelRelatedInfo" : null,
    "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"
    } ],
    "status" : "DRAFT",
    "direction" : "out"
  }, {
    "isDescriptionThread" : false,
    "visibility" : "public",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo",
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "FEEDBACK",
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "attachmentCount" : "5",
    "id" : "1892000000413189",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "status" : "SUCCESS",
    "direction" : "in"
  } ]
}

List all conversation

This API lists the threads and comments recorded on a ticket.

Query Params

Param Name
Data Type
Description
from

integer

Index number, starting from which the conversations must be fetched

limit

integer

No. of conversations to fetch

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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,
    "visibility" : "public",
    "author" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    },
    "channel" : "FORUMS",
    "type" : "thread",
    "isForward" : false,
    "hasAttach" : false,
    "responderId" : "1892000000042001",
    "channelRelatedInfo" : {
      "isDeleted" : "false",
      "isBestSolution" : "true"
    },
    "createdTime" : "2016-07-07T10:12:04.177Z",
    "attachmentCount" : "7",
    "id" : "1892000001080014",
    "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
    "actions" : [ ],
    "status" : "SUCCESS",
    "direction" : "out"
  }, {
    "summary" : "Any update regarding the issue",
    "cc" : "productmanagement@zylker.zohodesk.com",
    "isDescriptionThread" : false,
    "bcc" : "",
    "visibility" : "public",
    "author" : {
      "photoURL" : null,
      "name" : "Jade Tywin",
      "type" : "END_USER",
      "email" : "jade12tywin@gmail.com"
    },
    "channel" : "EMAIL",
    "type" : "thread",
    "isForward" : false,
    "hasAttach" : false,
    "channelRelatedInfo" : null,
    "createdTime" : "2016-07-07T10:02:04.663Z",
    "attachmentCount" : "6",
    "id" : "1892000001080004",
    "to" : "techsupport@zylker.zohodesk.com",
    "fromEmailAddress" : "jade12tywin@gmail.com",
    "actions" : [ ],
    "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" : {
      "photoURL" : "https://desk.zoho.com/api/v1/agents/4000000008692/photo?orgId=3983939",
      "name" : "Jade Tywin",
      "type" : "AGENT",
      "email" : "jade12tywin@zylker.com"
    }
  } ]
}

Send Email Reply

This API sends an email reply.The from address of the email must be one of the from addresses configured in your helpdesk.

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

  -d '{ "channel" : "EMAIL", "attachmentIds" : [ "1312123141313" ], "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.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"
  } ],
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/176276372673/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "EMAIL",
  "content" : "We have identified the root cause and fixed it.",
  "isForward" : true,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "carol@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.com",
  "actions" : [ ],
  "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 -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,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "content" : "We are looking into the issue.",
  "hasAttach" : false,
  "responderId" : "2150000000043591",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:04:43.739Z",
  "id" : "2150000002498038",
  "actions" : [ ],
  "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 -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,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@gmail.com"
  },
  "channel" : "TWITTER",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : null,
  "createdTime" : "2016-07-25T10:01:14.536Z",
  "id" : "2150000002498018",
  "actions" : [ ],
  "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 -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,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true"
  },
  "createdTime" : "2016-07-25T09:50:03.578Z",
  "id" : "1892000001121138",
  "actions" : [ ],
  "status" : "SUCCESS",
  "direction" : "out"
}

Draft Email Reply

This API drafts an email reply.The from address of the email must be one of the from addresses configured in your helpdesk.

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.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"
  } ],
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "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@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.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"
  } ],
  "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 -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,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/2150000000043591/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FACEBOOK",
  "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"
  } ],
  "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 -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,
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "FORUMS",
  "content" : "Thanks for your feedback",
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "channelRelatedInfo" : {
    "isDeleted" : "false",
    "isBestSolution" : "true"
  },
  "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"
  } ],
  "status" : "DRAFT",
  "direction" : "out"
}

Update Draft

This API updates a draft thread.Update Draft is only applicable for EMAIL,FACEBOOK and FORUM

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.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" : "",
  "visibility" : "public",
  "author" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000042001/photo?orgId=3983939",
    "name" : "Jade Tywin",
    "type" : "AGENT",
    "email" : "jade12tywin@zylker.com"
  },
  "channel" : "EMAIL",
  "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@zoho.com",
  "fromEmailAddress" : "techsupport@zylker.zohodesk.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"
  } ],
  "status" : "DRAFT",
  "direction" : "out"
}

Delete an attachment

This API deletes the draft attachment in a thread.

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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

ReadOnly

ID of the contact

customFields

object

Optional

User-defined fields

lastName

string

Required

Last name of the contact

firstName

string

Optional

First name of the contact

facebook

string

Optional

Facebook ID of the contact

twitter

string

Optional

Twitter ID of the contact

secondaryEmail

string

Optional

Secondary email ID of the contact

email

string

Optional

Email ID of the contact

phone

string

Optional

Phone number of the contact

mobile

string

Optional

Mobile number of the contact

city

string

Optional

Contact's city of residence

country

string

Optional

Contact's country of residence

state

string

Optional

Contact's state of residence

street

string

Optional

Contact's address

zip

string

Optional

Zip code

description

string

Optional

Contact description

title

string

Optional

Contact title

type

string

Optional

Contact type

ownerId

long

Optional

Contact owner

object

ReadOnly

Details of the user to whom the contact is assigned.

long

Optional

Account to which the contact is mapped

zohoCRMContact

object

ReadOnly

Contact details fetched from Zoho CRM

customerHappiness

object

ReadOnly

Average customer happiness rating of the contact

isDeleted

boolean

ReadOnly

Field that denotes whether the contact is in trash.This key is deprecated. Use isTrashed instead

isTrashed

boolean

ReadOnly

Field that denotes whether the contact is in trash

photoURL

string

ReadOnly

Photo URL of the contact

webUrl

string

ReadOnly

URL to access the resource

createdTime

timestamp

ReadOnly

Time of contact creation

modifiedTime

timestamp

ReadOnly

Time of contact modification

Example

{ "lastName" : "Smith", "modifiedTime" : "2015-03-02T14:49:32.000Z", "country" : null, "secondaryEmail" : null, "city" : null, "customFields" : { "permanentAddress" : null, "lastContactedOn" : 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, "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" }



Get a contact

This API fetches a single contact from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : accounts , owner

GET /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.READ

Request Example

$ 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,
  "customFields" : {
    "permanentAddress" : null,
    "lastContactedOn" : null
  },
  "description" : null,
  "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"
  },
  "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"
}

List all contacts

This API lists all contacts in your helpdesk.

Query Params

Param Name
Data Type
Description

list

Allowed values are : accounts

from

integer

From index

limit

string

No. of contacts to fetch

viewId

integer

ID of the view to apply while fetching the resources

sortBy

string

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

GET /api/v1/contacts

OAuth Scope

Desk.contacts.READ

Request Example

$ 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",
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "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,
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

Create a contact

This API creates a contact in your helpdesk.

POST /api/v1/contacts

OAuth Scope

Desk.contacts.CREATE

Request Example

$ 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",
  "customFields" : {
    "permanentAddress" : null,
    "lastContactedOn" : null
  },
  "description" : "first priority contact",
  "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",
  "facebook" : "hugh jack",
  "mobile" : "+10 2328829010",
  "accountId" : "1892000000052077",
  "firstName" : "hugh",
  "phone" : "91020080878",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38"
}

Update a contact

This API updates details of an existing contact.

PATCH /api/v1/contacts/{contact_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ 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",
  "customFields" : {
    "permanentAddress" : null,
    "lastContactedOn" : null
  },
  "description" : "first priority contact",
  "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",
  "facebook" : "Steve john",
  "mobile" : "+129737289298",
  "accountId" : "1892000000052077",
  "firstName" : "Stephen",
  "phone" : "8981901921",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38"
}

Move Contacts to trash

This API moves contacts to the Recycle Bin.

POST /api/v1/contacts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

$ 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

List tickets by contact

This API lists tickets received from a specific contact.

Query Params

Param Name
Data Type
Description
departmentId

long

Department from which the tickets need to be queried

from

Integer

From index

limit

Integer

No of tickets to be fetched

sortBy

string

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

string

Additional information related to the tickets. Values allowed are: productsdepartmentsteamisRead, 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.contacts.READ , Desk.tickets.READ , Desk.search.READ

Request Example

$ 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",
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zohodesk.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "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@asdad.com"
    },
    "status" : "Open"
  } ]
}

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.

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

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ 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", "city" : "4000000018011", "customFields" : { "permanentAddress" : 1892220000042001 }, "facebook" : "4000000018011", "mobile" : "4000000018011", "description" : "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,
  "customFields" : {
    "permanentAddress" : null,
    "lastContactedOn" : null
  },
  "description" : null,
  "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,
  "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"
}

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

ReadOnly

ID of the account

customFields

list

Optional

User-defined fields associated with the account

accountName

string

Required

Name of the account

email

string

Optional

Email ID of the account

website

string

Optional

Website of the account

fax

string

Optional

Fax number of the account

ownerId

long

Optional

ID of account owner

object

ReadOnly

Details of the user to whom the account is assigned.

associatedSLAIds

list

Optional

IDs of the SLAs associated to the account. An account can have multiple SLAs, but you can map only one SLA per department in an account

industry

string

Optional

Industry in which the account operates

city

string

Optional

City in which the account is based

country

string

Optional

Country in which the account is based

state

string

Optional

State in which the account is based

street

string

Optional

Address of the account

code

string

Optional

Zip code

description

string

Optional

A short description of the account

phone

string

Optional

Phone number of the account

annualrevenue

double

Optional

Annual revenue of the account

createdTime

timestamp

ReadOnly

Time of account creation

modifiedTime

timestamp

ReadOnly

Time of account modification

isTrashed

boolean

ReadOnly

Field that denotes whether the account is in trash

webUrl

string

ReadOnly

URL to access the resource

Example

{ "country" : "USA", "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : "www.zylker.com", "code" : "4436", "accountName" : "Zylker", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "contactCount" : "1" }, "description" : null, "industry" : "Automation", "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 an account

This API fetches an account from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : owner

GET /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.READ

Request Example

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

Response Example

{
  "owner" : {
    "firstName" : "Twin",
    "lastName" : "john",
    "id" : "3263000000057001"
  },
  "country" : "USA",
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : "www.zylker.com",
  "code" : "3211",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "contactCount" : "1"
  },
  "description" : null,
  "industry" : "Automation",
  "ownerId" : "3263000000057001",
  "isDeleted" : false,
  "isTrashed" : false,
  "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"
}

List all accounts

This API lists all accounts in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

No. of accounts to fetch

viewId

long

ID of the view to apply while fetching the resources

sortBy

string

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

GET /api/v1/accounts

OAuth Scope

Desk.contacts.READ

Request Example

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

Response Example

{
  "data" : [ {
    "website" : "112121",
    "accountName" : "Admin Account",
    "phone" : "121212",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "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",
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

Create an account

This API creates an account in your helpdesk.

POST /api/v1/accounts

OAuth Scope

Desk.contacts.CREATE

Request Example

$ 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" }'

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "contactCount" : null
  },
  "description" : null,
  "industry" : null,
  "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 an account

This API updates details of an existing account.

PATCH /api/v1/accounts/{account_id}

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ 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" }'

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "accountName" : "Zylker Agents",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "contactCount" : "1"
  },
  "description" : null,
  "industry" : null,
  "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
}

Move Accounts to trash

This API moves accounts to the Recycle Bin.

POST /api/v1/accounts/moveToTrash

OAuth Scope

Desk.contacts.DELETE

Request Example

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

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

Response Example

204

List tickets by account

This API lists tickets received from a specific account.

Query Params

Param Name
Data Type
Description
departmentId

long

Department from which the tickets need to be queried

from

Integer

From index

limit

Integer

No of tickets to be fetched

sortBy

string

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

string

Additional information related to the tickets. Values allowed are: productsdepartmentsteamisRead, 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.accounts.READ , Desk.tickets.READ , Desk.search.READ

Request Example

$ 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"

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,
    "closedTime" : null,
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "department" : {
      "name" : "dasdasdasd",
      "id" : "1892000000006907"
    },
    "email" : "support@zohodesk.com",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "threadCount" : "7",
    "lastThread" : null,
    "team" : {
      "name" : "kjsdfjks",
      "id" : "8920000000069071"
    },
    "priority" : "Medium",
    "assigneeId" : "1892000000042001",
    "commentCount" : "0",
    "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@asdad.com"
    },
    "status" : "Open"
  } ]
}

Merge Accounts

This API merges two or more accounts.

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

OAuth Scope

Desk.contacts.UPDATE

Request Example

$ 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", "city" : "4000000018011", "customFields" : { "contactCount" : 1892220000042001 }, "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",
  "accountName" : "Zylker",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "contactCount" : "1"
  },
  "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"
}

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

ReadOnly

ID of the task

customFields

list

Optional

User-defined fields related to the task

departmentId
see documentation

long

Required

Department associated with the task

subject

string

Required

Subject of the task

long

Optional

Ticket ID, if the task is associated with a particular ticket

dueDate

timestamp

Optional

Due date for completing the task

ownerId

string

Optional

Owner of the task

category

string

Optional

Category of the task

status

string

Optional

Status of task completion

priority

string

Optional

Priority of the task

description

string

Optional

Description of the task

createdTime

timestamp

ReadOnly

Time of creating the task

modifiedTime

timestamp

ReadOnly

Time of modifying the task

creatorId

string

ReadOnly

ID of user who created the task

ticket

Ticket

ReadOnly

Ticket associated with the task

object

ReadOnly

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

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "customFields" : { }, "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", "id" : "3000000018001", "category" : null, "ticketId" : "3000000008753", "status" : "Not Started" }



Get a task

This API fetches a single task from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Additional information related to the tasks. Values allowed are: assignee and tickets

GET api/v1/tasks/{task_id}

OAuth Scope

Desk.tasks.READ

Request Example

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

Response Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "ticket" : {
    "ticketNumber" : "101",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "id" : "3000000008749"
    },
    "id" : "3000000008753"
  },
  "customFields" : {
  },
  "subject" : "New Task",
  "completedTime" : null,
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-29T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : "1892000000056007",
  "priority" : "Normal",
  "createdTime" : "2016-07-26T17:32:11.000Z",
  "assignee" : {
    "firstName" : "dasca",
    "lastName" : "vins",
    "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo",
    "id" : "1892000000056007",
    "email" : "jack@asdad.com"
  },
  "id" : "3000000018001",
  "category" : null,
  "ticketId" : "3000000008753",
  "status" : "Not Started"
}

List all tasks

This API lists all the tasks in your helpdesk.

Query Params

Param Name
Data Type
Description

string

Additional information related to the tasks. Values allowed are: assignee and tickets

from

integer

From index

limit

integer

No. of tasks to fetch

departmentId
see documentation

long

Department from which the tasks need to be queried

long

ID of the view to apply while fetching the resources

assignee

long

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

dueDate

string

Filter by task duedate. Values allowed are Overdue, Tomorrow, CurrentWeek, CurrentMonth and Today. You can include both values by separating them with a comma

sortBy

string

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

GET api/v1/tasks

OAuth Scope

Desk.tasks.READ

Request Example

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

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-13T06:45:56.000Z",
    "subject" : "New task",
    "completedTime" : null,
    "dueDate" : "2013-12-28T06:30:00.000Z",
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : null,
    "ownerId" : "1892000000056007",
    "priority" : "Low",
    "isCommented" : true,
    "createdTime" : "2013-12-19T12:02:23.000Z",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "id" : "1892000000055041",
    "category" : "Meeting",
    "ticketId" : "1892000001125055",
    "status" : "Not Started"
  }, {
    "modifiedTime" : "2014-03-21T11:31:55.000Z",
    "subject" : "Modify ticket 102",
    "completedTime" : null,
    "dueDate" : "2014-03-28T06:30:00.000Z",
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : null,
    "ownerId" : "1892000000042001",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2014-03-21T11:31:03.000Z",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "id" : "1892000000138005",
    "category" : null,
    "ticketId" : "1892000000094004",
    "status" : "Not Started"
  }, {
    "modifiedTime" : "2014-05-26T07:26:46.000Z",
    "subject" : "Review changes",
    "completedTime" : null,
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : "Make all the mentioned changes",
    "ownerId" : null,
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2014-05-26T07:26:46.000Z",
    "assignee" : null,
    "id" : "1892000000272001",
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ]
}

Create a task

This API adds a task in your helpdesk.

POST api/v1/tasks

OAuth Scope

Desk.tasks.CREATE

Request Example

$ 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", "category" : null, "priority" : "High", "status" : "In Progress" }'

Response Example

{
  "modifiedTime" : "2016-07-14T09:14:41.000Z",
  "customFields" : {
  },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

Update a task

This API updates an existing task.

PATCH api/v1/tasks/{task_id}

OAuth Scope

Desk.tasks.UPDATE

Request Example

$ 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",
  "customFields" : {
  },
  "subject" : "Bug Fix #120",
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-21T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "High",
  "createdTime" : "2016-07-14T08:27:26.000Z",
  "id" : "3000000054002",
  "category" : "null",
  "ticketId" : "3000000008753",
  "status" : "In Progress"
}

List tasks by ticket

This API lists all tasks related to a particular ticket.

Query Params

Param Name
Data Type
Description
from

integer

From index

isCompleted

boolean

Completion status of the task

limit

integer

No. of tasks to fetch

sortBy

string

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

string

Additional information related to the tasks. Values allowed are: assignee

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

OAuth Scope

Desk.tasks.READ , Desk.tickets.READ

Request Example

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

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-14T08:22:16.000Z",
    "customFields" : {
    },
    "subject" : "Bug Fix #120",
    "departmentId" : "3000000007043",
    "dueDate" : "2016-07-21T16:16:16.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "1892000000056007",
    "priority" : "Normal",
    "createdTime" : "2016-07-14T08:22:16.000Z",
    "assignee" : {
      "firstName" : "dasca",
      "lastName" : "vins",
      "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000056007/photo",
      "id" : "1892000000056007",
      "email" : "jack@asdad.com"
    },
    "id" : "3000000053002",
    "category" : "null",
    "ticketId" : "3000000008753",
    "status" : "In Progress"
  }, {
    "modifiedTime" : "2016-07-14T08:22:16.000Z",
    "customFields" : {
    },
    "subject" : "Bug Fix #120",
    "departmentId" : "3000000007043",
    "dueDate" : "2016-07-21T16:16:16.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : "null",
    "priority" : "Normal",
    "createdTime" : "2016-07-14T08:22:16.000Z",
    "assignee" : null,
    "id" : "3000000053002",
    "category" : "null",
    "ticketId" : "3000000008753",
    "status" : "In Progress"
  } ]
}

List all tasks count

This API returns the number of tasks in your help desk.

Query Params

Param Name
Data Type
Description
viewId

long

ID of the view to apply while fetching the resources

departmentId
see documentation

long

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

assignee

string

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

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

Products

Products are the goods/services your organization sells.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the product

list

Required

IDs of departments associated with the product

ownerId

long

Optional

ID of user to whom the product is assigned

productName

string

Required

Name of the product

productCode

string

Optional

Reference code of the product

productCategory

string

Optional

Category to which the product belongs

manufacturer

string

Optional

Organization that manufactures the product

unitPrice

double

Optional

Price of the product

customFields

list

Optional

User-defined fields related to the product

createdBy

long

ReadOnly

User who added the product to the help desk portal

modifiedBy

long

ReadOnly

User who modified the details of the product

createdTime

timestamp

ReadOnly

Time of adding the product to the help desk portal

modifiedTime

timestamp

ReadOnly

Time of modifying product details

description

string

Optional

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 a product

This API fetches a single product from your helpdesk.

GET /api/v1/products/{products_id}

OAuth Scope

Desk.settings.READ

Request Example

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

Response Example

{
  "unitPrice" : "100.0",
  "modifiedTime" : "2017-06-28T13:25:06.000Z",
  "customFields" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "ownerId" : "6000000009050",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009"
}

List products

This API lists a specific number of products from your helpdesk, based on the limit defined.

Query Params

Param Name
Data Type
Description
viewId

long

ID of the view to apply while fetching the products

from

integer

Index number, starting from which the products must be fetched

limit

integer

No. of products to fetch

departmentIds

long

IDs of departments (separated by comma) from which the products must be fetched

ownerId

long

ID of user to whom the product is assigned

sortBy

string

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

GET /api/v1/products

OAuth Scope

Desk.settings.READ

Request Example

$ 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",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "HTC"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000121037",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "Dell"
  }, {
    "unitPrice" : "100.0",
    "productCode" : null,
    "id" : "6000000145024",
    "departmentIds" : [ "6000000007239", "6000000029263" ],
    "productName" : "Lenovo"
  } ]
}

Create product

This API adds a product to your helpdesk.

POST /api/v1/products

OAuth Scope

Desk.settings.CREATE

Request Example

$ 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",
  "customFields" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000007239", "6000000029263" ],
  "ownerId" : "6000000009050",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-07-18T10:46:25.667Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000164001"
}

Update product

This API updates details of a product in your help desk portal.

PATCH /api/v1/products/{products_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

$ 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",
  "customFields" : {
  },
  "description" : null,
  "departmentIds" : [ "6000000029263", "6000000125041" ],
  "ownerId" : "6000000009050",
  "productName" : "Dell",
  "productCategory" : null,
  "productCode" : "12345",
  "isDeleted" : false,
  "createdBy" : "6000000009050",
  "createdTime" : "2017-06-28T13:25:06.000Z",
  "modifiedBy" : "6000000009050",
  "id" : "6000000124009"
}

Associate contacts with a product

This API associates contacts with a product.

POST api/v1/products/{products_id}/associateContacts

OAuth Scope

Desk.settings.UPDATE

Request Example

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

POST api/v1/products/{products_id}/associateAccounts

OAuth Scope

Desk.settings.UPDATE

Request Example

$ curl -X POST https://support.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

Query Params

Param Name
Data Type
Description
from

int

Index number starting from which the accounts must be fetched

limit

integer

Number of accounts to fetch

sortBy

string

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

Request Example

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

Response Example

{
  "data" : [ {
    "website" : "112121",
    "accountName" : "Admin Account",
    "phone" : "121212",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Accounts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "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",
    "id" : "1892000000052090",
    "email" : "agent@zylker.com"
  } ]
}

List contacts associated with product

This API lists the contacts associated with a product.

Query Params

Param Name
Data Type
Description
from

int

Index number starting from which the contacts must be fetched

limit

integer

Number of contacts to fetch

sortBy

string

Key that sorts the contacts by a specific attribute:
firstName,

lastName,

phone,

email,

account,

createdTime,

modifiedTime

list

Secondary information related to the product/contacts.Value allowed is accounts

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

OAuth Scope

Desk.settings.READ

Request Example

$ 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",
    "phone" : "555555",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "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",
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "email" : "jade@zylker.com"
  } ]
}

Articles

Articles are content pieces that you share on the knowledge base of your helpdesk. Articles intend to educate users and provide solutions to issues that customers frequently encounter.

Example

{ "modifiedTime" : "2017-09-13T18:44:11.000Z", "attachments" : [ { "name" : "Solution_translation_table.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", "public" : true, "createdTime" : "2017-09-13T18:18:32.000Z", "modifiedBy" : { "name" : "Yahya", "id" : "22372000000094005" }, "id" : "22372000000119001", "seo" : { "keywords" : "SI, Ronda, Profile", "description" : "Si Ronda Profile", "title" : "Si Ronda" }, "summary" : "Si Ronda was released in 1930;[11] Effendi stated that it was released before Tan's Nancy Bikin Pembalesan (Nancy Takes Revenge), a sequel to Njai Dasima, began screening in May 1930.[12] Dutch newspapers indicate that it had screened in Medan, North Sumatra, ", "latestVersionStatus" : "DRAFT", "permission" : "ALL", "reviewedBy" : { }, "authorId" : "22372000000094005", "tags" : [ "si", "ronda" ], "commentCount" : "0", "answer" : "<p><i>Si Ronda</i> was released in 1930;<sup id=\"cite_ref-FOOTNOTEFilmindonesia.or.id.2C_Si_Ronda_11-0\" class=\"reference\"><a href=\"#cite_note-FOOTNOTEFilmindonesia.or.id.2C_Si_Ronda-11\">[11]</a></sup> Effendi stated that it was released before Tan&#39;s <i><a href=\"/wiki/Nancy_Bikin_Pembalesan\" title=\"Nancy Bikin Pembalesan\">Nancy Bikin Pembalesan</a></i> (<i>Nancy Takes Revenge</i>), a sequel to <i>Njai Dasima</i>, began screening in May 1930.", "latestVersion" : "0.1", "createdBy" : { "name" : "Yahya", "id" : "22372000000094005" }, "latestPublishedVersion" : "null", "attachmentCount" : "1", "position" : "0", "metrics" : { "feedbackCount" : "0", "unlikeCount" : "0", "lastUsageTime" : null, "likeCount" : "0", "viewCount" : "0", "lastActivityTime" : "2017-09-13T18:44:11.000Z", "usageCount" : "0" }, "permalink" : "test123-13-9-2017", "category" : { "name" : "General", "id" : "22372000000094159" }, "status" : "Draft" }



List articles

This API lists a specific number of articles from your help desk, based on the limit defined

Query Params

Param Name
Data Type
Description
from

Integer

Index number starting from which the articles must be fetched.

limit

Integer

Number of articles to fetch

sortBy

String

Key that sorts the articles based on a specific attribute:
createdTime,
or
modifiedTime

status

String

Publishing status of the article. Values allowed are Draft, Published, Review, Expired

authorId

Long

ID of article owner

categoryId

Long

ID of the article category

modifiedTimeRange

timestamp

Key that filters articles 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'

permission

String

Publishing status of the article. Values allowed are ALL, REGISTEREDUSERS, AGENTS

GET /api/v1/articles

OAuth Scope

Desk.articles.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles?from=0&limit=10&sortBy=-createdTime&status=Published&categoryId=4000000013240&permission=AGENTS&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" : [ {
    "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
    "modifiedTime" : "2018-07-16T06:48:08.000Z",
    "latestVersionStatus" : "Published",
    "creatorId" : "4000000012931",
    "modifierId" : "4000000012931",
    "dislikeCount" : "1",
    "permission" : "AGENTS",
    "likeCount" : "2",
    "title" : "Importance of a Knowledge Base",
    "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",
    "createdTime" : "2018-07-16T06:48:08.000Z",
    "latestPublishedVersion" : "1.0",
    "viewCount" : "3",
    "id" : "22372000000281023",
    "permalink" : "importance-of-a-knowledge-base",
    "categoryId" : "4000000013240",
    "status" : "Published"
  } ]
}

Get article

This API fetches an article from your knowledge base.

Query Params

Param Name
Data Type
Description
version

String

Version number of the article

GET /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.READ

Request Example

$ 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" : "2017-09-19T04:45:48.000Z",
  "attachments" : [ {
    "reseourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40",
    "name" : "Solution_translation_table.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-19T04:22:24.000Z",
    "filesize" : "113727"
  } ],
  "reviewedTime" : null,
  "departmentId" : "22372000000006907",
  "title" : "Importance of a Knowledge Base",
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "createdTime" : "2017-09-19T04:22:24.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "id" : "22372000000133001",
  "seo" : {
    "keywords" : "Knowledge Base, Helpcenter",
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
  "latestVersionStatus" : "Published",
  "permission" : "REGISTEREDUSERS",
  "reviewedBy" : null,
  "authorId" : "22372000000094005",
  "currentVersion" : "1.2",
  "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" : "1.2",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "portalURL" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-knowledge-base",
  "latestPublishedVersion" : "1.0",
  "attachmentCount" : "0",
  "position" : "1",
  "metrics" : {
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "permalink" : "importance-of-knowledge-base",
  "category" : {
    "name" : "General",
    "id" : "22372000000094159"
  },
  "status" : "Published"
}

Get published version of article

This API fetches the final published version of an article.

GET /api/v1/publishedArticles/{article_id}

OAuth Scope

Desk.articles.READ

Request Example

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

Response Example

{
  "modifiedTime" : "2017-09-19T04:58:50.000Z",
  "attachments" : [ ],
  "reviewedTime" : null,
  "departmentId" : "22372000000006907",
  "title" : "Importance of a Knowledge Base",
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "createdTime" : "2017-09-19T04:22:24.000Z",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "id" : "22372000000133001",
  "seo" : {
    "keywords" : "Helpcenter, Knowledge Base",
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
  "latestVersionStatus" : "Draft",
  "permission" : "REGISTEREDUSERS",
  "reviewedBy" : null,
  "authorId" : "22372000000094005",
  "currentVersion" : "1.3",
  "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" : "1.3",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "portalURL" : "https://desk.zoho.com/portal/zylker/kb/articles/importance-of-knowledge-base",
  "latestPublishedVersion" : "1.0",
  "attachmentCount" : "0",
  "position" : "1",
  "metrics" : {
    "feedbackCount" : "0",
    "unlikeCount" : "0",
    "lastUsageTime" : null,
    "likeCount" : "0",
    "viewCount" : "0",
    "lastActivityTime" : null,
    "usageCount" : "0"
  },
  "permalink" : "importance-of-knowledge-base",
  "category" : {
    "name" : "General",
    "id" : "22372000000094159"
  },
  "status" : "Published"
}

Create an article

This API creates an article in your helpdesk.

POST /api/v1/articles

OAuth Scope

Desk.articles.CREATE

Request Example

$ 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 '{ "expiryDate" : "2018-05-21T05:55:00.000Z", "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" : "ALL", "title" : "Importance of a Knowledge Base", "permalink" : "knowledgebase", "authorId" : 22372000000094004, "seoTitle" : "Knowledge Base", "seoKeywords" : "Helpcenter, Knowledge Base", "categoryId" : 22372000000094160, "status" : "Draft", "tags" : [ "knowledge base", "helpcenter" ] }'

Response Example

{
  "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
  "modifiedTime" : "2017-09-19T04:22:24.000Z",
  "latestVersionStatus" : "Draft",
  "attachments" : [ ],
  "reviewedTime" : null,
  "departmentId" : "22372000000006907",
  "permission" : "ALL",
  "title" : "Importance of a Knowledge Base",
  "reviewedBy" : null,
  "authorId" : "22372000000094005",
  "currentVersion" : "0.1",
  "tags" : [ "knowledge base", "helpcenter" ],
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "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"
  },
  "createdTime" : "2017-09-19T04:22:24.000Z",
  "latestPublishedVersion" : "null",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "id" : "22372000000133001",
  "permalink" : "importance-of-knowledge-base",
  "category" : {
    "name" : "General",
    "id" : "22372000000094159"
  },
  "seo" : {
    "keywords" : "Helpcenter, Knowledge Base",
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "status" : "Draft"
}

Update an article

This API updates an existing article.

Query Params

Param Name
Data Type
Description
createVersion

Boolean

Denotes if a new version is needed

PATCH /api/v1/articles/{article_id}

OAuth Scope

Desk.articles.UPDATE

Request Example

$ 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", "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

{
  "summary" : "Help articles are vital resources in user education. They are the first building blocks of an effective self-service setup.",
  "modifiedTime" : "2017-09-19T04:29:56.000Z",
  "latestVersionStatus" : "Draft",
  "attachments" : [ {
    "reseourceId" : "1vq0db78bc1203a0645e0a38373b3bddf8d40",
    "name" : "Solution_translation_table.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-19T04:22:24.000Z",
    "filesize" : "113727"
  } ],
  "reviewedTime" : null,
  "departmentId" : "22372000000006907",
  "permission" : "REGISTEREDUSERS",
  "title" : "Importance of a Knowledge Base",
  "reviewedBy" : null,
  "authorId" : "22372000000094005",
  "currentVersion" : "1.2",
  "tags" : [ "helpcenter", "knowledge base" ],
  "expiryDate" : "2018-05-21T05:55:00.000Z",
  "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.2",
  "createdBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "createdTime" : "2017-09-19T04:22:24.000Z",
  "latestPublishedVersion" : "1.0",
  "modifiedBy" : {
    "photoURL" : "https://desk.zoho.com/api/v1/agents/1000000012768/photo?orgId=292828",
    "name" : "Zylker",
    "id" : "22372000000094005"
  },
  "id" : "22372000000133001",
  "permalink" : "importance-of-knowledge-base",
  "category" : {
    "name" : "General",
    "id" : "22372000000094159"
  },
  "seo" : {
    "keywords" : "Helpcenter, Knowledge Base",
    "description" : "Knowledge Base for your product",
    "title" : "Knowledge Base"
  },
  "status" : "Published"
}

Move articles to trash

This API moves articles to the Recycle Bin

POST /api/v1/articles/moveToTrash

OAuth Scope

Desk.articles.DELETE

Request Example

$ 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"
    }
  } ]
}

KBCategory

Category API's are used to create, delete, modify categories

Example

{ }



List all category

This API lists all the categories

Query Params

Param Name
Data Type
Description
departmentId

long

To get individual department details

GET /api/v1/kbCategory

OAuth Scope

Desk.articles.READ

Request Example

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

Response Example

{
  "data" : [ {
    "articleViewType" : "OVERVIEW",
    "level" : "1",
    "departmentId" : 1000000007245,
    "description" : null,
    "logoUrl" : "https://desk.zoho.com/portal/api/departments/1000000007245/logo?orgId=4782286",
    "childOrder" : [ 1000000019004 ],
    "name" : "knowledge base",
    "parentCategoryId" : null,
    "id" : 1000000009271,
    "articlesCount" : null,
    "featuredCategory" : true,
    "order" : "1",
    "child" : [ {
      "articleViewType" : "OVERVIEW",
      "level" : "2",
      "departmentId" : 1000000007245,
      "description" : null,
      "logoUrl" : "https://desk.zoho.com/portal/api/departments/1000000007245/logo?orgId=4782286",
      "childOrder" : [ ],
      "name" : "uncategorized",
      "parentCategoryId" : 1000000009271,
      "id" : 1000000019004,
      "articlesCount" : null,
      "featuredCategory" : true,
      "order" : null,
      "child" : [ ],
      "isVisibleInHC" : true
    } ],
    "isVisibleInHC" : false
  } ]
}

Create a category

This API creates a category in your helpdesk

POST /api/v1/kbCategory

OAuth Scope

Desk.articles.CREATE

Request Example

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

  -d '{ "name" : "Knowledge base", "parentCategoryId" : 1000000009271, "featuredCategory" : true, "isVisibleInHC" : true }'

Response Example

{
  "articleViewType" : null,
  "level" : "2",
  "departmentId" : 1000000007245,
  "description" : null,
  "logoUrl" : null,
  "childOrder" : null,
  "name" : "Knowledge base",
  "parentCategoryId" : 1000000009271,
  "id" : 1000000019001,
  "articlesCount" : null,
  "featuredCategory" : false,
  "order" : "1",
  "child" : null,
  "isVisibleInHC" : true
}

Update a category

This API updates an existing category

PATCH /api/v1/kbCategory/([0-9]+)

OAuth Scope

Desk.articles.UPDATE

Request Example

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

  -d '{ "articleViewType" : "OVERVIEW", "reviewOwners" : [ ], "name" : "Knowledge base", "isReview" : false, "description" : "Knowledge base short description", "logo" : 10111111111, "parentCategoryId" : 1000000009271, "featuredCategory" : true, "isVisibleInHC" : true }'

Response Example

{
  "articleViewType" : "OVERVIEW",
  "level" : "2",
  "departmentId" : "1000000007245",
  "description" : "Knowledge base short description",
  "logoUrl" : "https://d3el7j01zd7apf.cloudfront.net/app/fonts/board.8269639bca192ef20035.svg",
  "childOrder" : null,
  "name" : "Knowledge base",
  "parentCategoryId" : 1000000009271,
  "id" : 1000000019001,
  "articlesCount" : null,
  "featuredCategory" : true,
  "order" : "1",
  "child" : null,
  "isVisibleInHC" : true
}

Move a category to trash

This API moves a category to trash

DELETE /api/v1/kbCategory/([0-9]+)

OAuth Scope

Desk.articles.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/kbCategory/([0-9]+)
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Get review configuration and review owners

This API fetches review configurations and review owners for the given departments

Query Params

Param Name
Data Type
Description
departmentIdList

String

department list string

GET /api/v1/kbCategoryReview

OAuth Scope

Desk.articles.READ

Request Example

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

Response Example

{
  "1301000000006907" : {
    "reviewOwners" : [ 1301000000074032, 1301000000426312, 1301000002679001 ],
    "isReview" : "true"
  }
}

Upload logo image

This API is used to upload an image to be used as logo

File Params

file

Content-Type:multipart/form-data

POST /api/v1/kbCategoryLogo

OAuth Scope

Desk.articles.CREATE

Request Example

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

Response Example

{
  "id" : "2029254000000178001"
}

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

ReadOnly

ID of the contract

associatedSLAId

long

Optional

ID of the SLA associated with the contract

accountId

long

Optional

ID of the account associated with the contract

departmentId

long

Optional

Department to which the contract belongs

productId

long

Optional

ID of the product associated with the contract

contractNumber

string

Optional

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

notifyOn

date

ReadOnly

The date when the contract expiry notification must be sent

startDate

date

Optional

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

createdBy

string

ReadOnly

User who created the contract

modifiedBy

string

ReadOnly

User who modified the contract

createdTime

timestamp

ReadOnly

Time of creating the contract

modifiedTime

timestamp

ReadOnly

Time of modifying the contract

contractName

string

Optional

Name of the contract

description

string

Optional

A short description of the contract

customFields

list

Optional

User-defined fields associated with the contract

Example

{ "associatedSLAId" : "5000000007671", "modifiedTime" : "2018-01-15T11:13:04.000Z", "productId" : "5000000009328", "endDate" : "2019-01-10", "customFields" : { "myCustomField1" : "hello" }, "departmentId" : "5000000007235", "notifyBefore" : "5", "contractNumber" : "101", "description" : null, "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", "startDate" : "2018-01-10" }



Get a contract

This API fetches a single contract from your helpdesk.

GET api/v1/contracts/{{contract_id}}

OAuth Scope

Desk.settings.READ

Request Example

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

Response Example

{
  "associatedSLAId" : "5000000007671",
  "modifiedTime" : "2018-01-15T11:13:04.000Z",
  "productId" : "5000000009328",
  "endDate" : "2019-01-10",
  "customFields" : {
    "myCustomField1" : "hello"
  },
  "departmentId" : "5000000007235",
  "notifyBefore" : "5",
  "contractNumber" : "101",
  "description" : null,
  "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",
  "startDate" : "2018-01-10"
}

List all contracts

To get a list of contracts

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

Number of contracts to fetch

viewId

integer

ID of the view to apply while fetching the resources

departmentId
see documentation

long

ID of the department from which the contracts must be fetched

long

ID of the account associated with the contract

ownerId

long

ID of contract owner

sortBy

string

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.

string

Allowed Value is: accounts

GET api/v1/contracts

OAuth Scope

Desk.settings.READ

Request Example

$ 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",
    "startDate" : "2018-10-10"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000265011",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-10",
    "departmentId" : "10000000010762",
    "contractName" : "New",
    "id" : "10000000270045",
    "ownerId" : "10000000012902",
    "startDate" : "2018-09-09"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272001",
    "contractStatus" : "ACTIVE",
    "productId" : null,
    "endDate" : "2018-12-11",
    "departmentId" : "10000000010762",
    "contractName" : "THIRD",
    "id" : "10000000272013",
    "ownerId" : "10000000012902",
    "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",
    "startDate" : "2018-09-11"
  }, {
    "associatedSLAId" : "10000000149109",
    "accountId" : "10000000272071",
    "contractStatus" : "EXPIRED",
    "productId" : null,
    "endDate" : "2018-09-12",
    "departmentId" : "10000000010762",
    "contractName" : "old",
    "id" : "10000000272083",
    "ownerId" : "10000000012902",
    "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",
    "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",
    "startDate" : "2018-11-11"
  } ]
}

Create a contract

This API creates a contract in your helpdesk.

POST /api/v1/contracts

OAuth Scope

Desk.settings.CREATE

Request Example

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

  -d '{ "associatedSLAId" : "10000000062047", "productId" : null, "endDate" : "2019-07-23", "customFields" : { "MyCustomField1" : "Some Value" }, "departmentId" : "10000000013228", "notifyBefore" : "3", "description" : "My Description", "contractNumber" : 9495, "ownerId" : "10000000012816", "notificationAgentIds" : [ "10000000012816" ], "accountId" : "10000000012985", "contractName" : "MyContractName", "startDate" : "2018-07-23" }'

Response Example

{
  "associatedSLAId" : "10000000062047",
  "modifiedTime" : "2018-07-24T07:31:57.075Z",
  "productId" : null,
  "endDate" : "2019-07-23",
  "customFields" : {
    "MyCustomField1" : "Some Value"
  },
  "departmentId" : "10000000013228",
  "notifyBefore" : "3",
  "contractNumber" : "9495",
  "description" : "My Description",
  "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",
  "startDate" : "2018-07-23"
}

Update a contract

This API updates the details of an existing contract.

PATCH /api/v1/contracts/{contract_id}

OAuth Scope

Desk.settings.UPDATE

Request Example

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

  -d '{ "associatedSLAId" : "10000000062047", "productId" : null, "endDate" : "2019-09-15", "customFields" : { "MyCustomField1" : "Some Updated Value" }, "departmentId" : "10000000013228", "notifyBefore" : "5", "description" : "My Description Updated", "contractNumber" : 9496, "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",
  "productId" : null,
  "endDate" : "2019-09-15",
  "customFields" : {
    "MyCustomField1" : "Some Updated Value"
  },
  "departmentId" : "10000000013228",
  "notifyBefore" : "5",
  "contractNumber" : "9496",
  "description" : "My Description Updated",
  "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",
  "startDate" : "2018-08-14"
}

Views

Views are customized displays of help desk data, which help customer service agents effectively organize their everyday work and deliver better customer service.

List all views

This API lists the different views configured for a specific module or for all modules in your help desk. Values allowed are: Tickets, Contacts, Accounts, Tasks, Products, and Contracts

Query Params

Param Name
Data Type
Description

string

Allowed values are : tickets, tasks,contacts, accounts,contacts, products ,activities,calls,events.

departmentId
see documentation

long

Allowed values are : Valid Department Id.

GET /api/v1/views

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

$ 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"
  } ]
}

Search across entities

This API returns information from all modules or a specific module, based on the value of the module query param.

Query Params

Param Name
Data Type
Description
searchStr

String

Keyword or phrase to search

module

String

Module to search in: tickets, accounts, contacts or tasks. The default response includes all modules.

departmentId

long

Department from which the entities need to be queried

from

int

From index, starts from 0

limit

int

No. of entities to fetch

sortBy

String

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.contacts.READ , Desk.tickets.READ , Desk.tasks.READ , Desk.search.READ

Request Example

$ 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" : [ {
    "customerResponseTime" : "2016-06-27T07:22:52.117Z",
    "productId" : "4000000013043",
    "contactId" : "4000000013012",
    "subject" : "Zylker ticket",
    "customFields" : {
      "featureRequest" : false,
      "region" : "Asia"
    },
    "module" : "tickets",
    "departmentId" : "4000000007043",
    "dueDate" : null,
    "channel" : "Phone",
    "onholdTime" : null,
    "threadCount" : "0",
    "priority" : null,
    "assigneeId" : "4000000008692",
    "closedTime" : null,
    "commentCount" : "0",
    "number" : "104",
    "phone" : null,
    "contact" : {
      "phone" : null,
      "name" : "Stephen",
      "id" : "4000000013012",
      "type" : null,
      "email" : null,
      "account" : {
        "website" : null,
        "name" : "Zylker Accounts",
        "id" : "4000000008850"
      }
    },
    "createdTime" : "2016-06-27T07:22:52.000Z",
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "id" : "4000000016009",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "email" : null,
    "status" : "Open"
  }, {
    "ticket" : null,
    "subject" : "Wifi adapter not working in zylker",
    "completedTime" : null,
    "customFields" : {
      "severity" : "High",
      "followUpDate" : "2016-07-07T19:30:00.000Z"
    },
    "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
  }
}

Tickets Search API

This API searches for tickets in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.

Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

CustomField param Example:
customField1=ModelName:F3*
customField2=phone:902*
customField3=permanentAddress: Wall Street*

Note:
wildcard match will not be available for the custom fields that are not of type string
Wildcard character question mark (?) is not supported
mobile and phone fields supports asterisk (*) at the beginning

Urlencoded Example:
customField1=ModelName%3AF3*
customField2=phone%3A902*
customField3=permanentAddress%3AWall%20Street*

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

departmentId

long

ID of the department from which the entity must be fetched. if not passed then searches in permitted departments
exact match

id

String

ID of the ticket
exact match

ticketNumber

String

Serial number of the ticket in the help desk
exact match

subject

String

subject of the ticket in the help desk
wildcard search

description

String

description of the ticket in the help desk
wildcard search

status

String

Status of the ticket. Includes the custom statuses that exist in your help desk
exact match

priority

String

Priority of the ticket
exact match

email

String

Email ID in the ticket
wildcard search

phone

String

Phone number in the ticket
wildcard search

channel

String

Channel through which the ticket was received
exact match

category

String

Category in the ticket
wildcard search

assigneeId

String

ID of the agent assigned to resolve the ticket
exact match

contactId

String

ID of the contact who raised the ticket
exact match

accountId

String

ID of the account associated with the ticket
exact match

productId

String

ID of the product associated with the ticket
exact match

contactName

String

Name of the contact who raised the ticket
wildcard search

accountName

String

Name of the account associated with the ticket
wildcard search

productName

String

Name of the product associated with the ticket
wildcard search

tag

String

Tag in the ticket
wildcard search

_all

String

Search throughout the ticket
wildcard search

customField1

String

Custom field in the ticket
wildcard search

customField2

String

Custom field in the ticket
wildcard search

customField3

String

Custom field in the ticket
wildcard search

customField4

String

Custom field in the ticket
wildcard search

customField5

String

Custom field in the ticket
wildcard search

customField6

String

Custom field in the ticket
wildcard search

customField7

String

Custom field in the ticket
wildcard search

customField8

String

Custom field in the ticket
wildcard search

customField9

String

Custom field in the ticket
wildcard search

customField10

String

Custom field in the ticket
wildcard search

customerResponseTimeRange

timestamp

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

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

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime,

customerResponseTime

GET /api/v1/tickets/search

OAuth Scope

Desk.tickets.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/search?limit=1&subject=analysis*
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "modifiedTime" : "2016-06-21T12:58:09.122Z",
    "subCategory" : "Sub General",
    "subject" : "Real Time analysis Requirement",
    "customFields" : {
    },
    "dueDate" : "2016-06-23T12:58:09.211Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "description" : "Hai This is description",
    "onholdTime" : null,
    "resolution" : null,
    "closedTime" : null,
    "isOverDue" : true,
    "responseDueDate" : null,
    "contact" : {
      "firstName" : "Jonathan",
      "lastName" : "Casie",
      "accountId" : "1892000000045028",
      "id" : "5000000009587",
      "email" : "casie@zylker.com",
      "account" : {
        "accountName" : "Zylker Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2016-06-21T12:50:04.000Z",
    "modifiedBy" : "1892000000056007",
    "id" : "1892000001054003",
    "department" : {
      "name" : "Testing",
      "id" : "5000000007235"
    },
    "email" : "carol@zylker.com",
    "customerResponseTime" : "2016-11-02T10:38:07.000Z",
    "productId" : null,
    "contactId" : "1892000000042032",
    "threadCount" : "0",
    "lastThread" : null,
    "priority" : "High",
    "classification" : null,
    "assigneeId" : "1892000000056007",
    "commentCount" : "0",
    "accountId" : null,
    "phone" : null,
    "assignee" : {
      "firstName" : "",
      "lastName" : "jade",
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
      "emailId" : "jade@zylker.com",
      "id" : "5000000009116",
      "zuid" : "10657727"
    },
    "category" : "General",
    "status" : "Open"
  } ],
  "count" : 1
}

Account Search API

This API searches for accounts in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

id

String

ID of the account
exact match

accountName

String

Name of the account
wildcard search

_all

String

Search throughout the account
wildcard search

customField1

String

Custom field in the account
wildcard search
e.g customField1=activeAccount:true

customField2

String

Custom field in the account
wildcard search

customField3

String

Custom field in the account
wildcard search

customField4

String

Custom field in the account
wildcard search

customField5

String

Custom field in the account
wildcard search

customField6

String

Custom field in the account
wildcard search

customField7

String

Custom field in the account
wildcard search

customField8

String

Custom field in the account
wildcard search

customField9

String

Custom field in the account
wildcard search

customField10

String

Custom field in the account
wildcard search

createdTimeRange

timestamp

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime,

accountName

GET /api/v1/accounts/search

OAuth Scope

Desk.contacts.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/search?limit=1&accountName=Zylker
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

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

Contact Search API

This API searches for contacts in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

id

String

ID of the contact
exact match

fullName

String

Full name of the contact
wildcard search

firstName

String

First name of the contact
wildcard search

lastName

String

Last name of the contact
wildcard search

email

String

Email ID of the contact
wildcard search

phone

String

Phone number of the contact
wildcard search

mobile

String

Mobile number of the contact
wildcard search

accountName

String

Name of the account associated with the Contact
wildcard search

_all

String

Search throughout the contact
wildcard search

customField1

String

Custom field in the Contact
wildcard search
e.g customField1=mappedWithAccount:true

customField2

String

Custom field in the contact
wildcard search

customField3

String

Custom field in the contact
wildcard search

customField4

String

Custom field in the contact
wildcard search

customField5

String

Custom field in the contact
wildcard search

customField6

String

Custom field in the contact
wildcard search

customField7

String

Custom field in the contact
wildcard search

customField8

String

Custom field in the contact
wildcard search

customField9

String

Custom field in the contact
wildcard search

customField10

String

Custom field in the contact
wildcard search

createdTimeRange

timestamp

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime,

lastName,

firstName

GET /api/v1/contacts/search

OAuth Scope

Desk.contacts.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/search?limit=1&lastName=Lawrence
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "lastName" : "Lawrence",
    "country" : null,
    "modifiedTime" : "2016-05-04T09:57:17.000Z",
    "secondaryEmail" : null,
    "city" : null,
    "customFields" : {
      "permanentAddress" : null,
      "lastContactedOn" : null
    },
    "description" : null,
    "title" : null,
    "type" : null,
    "ownerId" : "1892000000042001",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo",
    "twitter" : null,
    "street" : null,
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "state" : null,
    "id" : "1892000000042032",
    "email" : "support@zohodesk.com",
    "zip" : null,
    "facebook" : null,
    "mobile" : null,
    "firstName" : null,
    "accountId" : "1892000000975382",
    "phone" : "1 888 900 9646",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "account" : {
      "accountName" : "Zylker",
      "id" : "1892000000975382"
    }
  } ],
  "count" : 1
}

Article Search API

This API searches for help articles in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

id

String

ID of the articles
exact match

title

String

title of the help article
wildcard search

categoryName

String

Name of the Category
wildcard search

categoryId

long

ID of the Category

tag

String

Tag in the articles
wildcard search

createdTimeRange

timestamp

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime

GET /api/v1/articles/search

OAuth Scope

Desk.articles.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/articles/search?limit=1&categoryName=test
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "summary" : "test ",
    "modifiedtime" : "2017-11-30T09:26:03.000Z",
    "viewcount" : "0",
    "permission" : "ALL",
    "id" : "5000000009361",
    "title" : "test",
    "permalink" : "test",
    "category" : {
      "name" : "General",
      "id" : "5000000009268"
    },
    "vote" : {
      "like" : "0",
      "dislike" : "0"
    },
    "createdtime" : "2017-11-02T10:13:18.000Z",
    "status" : "Published"
  } ],
  "count" : 379
}

Task Search API

This API searches for tasks in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

departmentId

long

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

id

String

ID of the task
exact match

subject

String

subject of the task in the help desk
wildcard search

ticketNumber

String

ticket Number of the ticket that associated with the task
exact match

status

String

status of the task
exact match

priority

String

Priority of the task
exact match

_all

String

Search throughout the task
wildcard search

customField1

String

Custom field in the task
wildcard search

customField2

String

Custom field in the task
wildcard search

customField3

String

Custom field in the task
wildcard search

customField4

String

Custom field in the task
wildcard search

customField5

String

Custom field in the task
wildcard search

customField6

String

Custom field in the task
wildcard search

customField7

String

Custom field in the task
wildcard search

customField8

String

Custom field in the task
wildcard search

customField9

String

Custom field in the task
wildcard search

customField10

String

Custom field in the task
wildcard search

createdTimeRange

timestamp

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

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime,

GET /api/v1/tasks/search

OAuth Scope

Desk.tasks.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/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,
    "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
}

Products Search API

This API searches for products in your help desk. The values can be given comma separated, which denotes the search on the field is done using either of the values given.
Zoho Desk APIs support two types of search:exact match and wildcard match.
exact match returns resources only if the value passed exactly matches with a resource in the help desk.
wildcard match returns resources even if the value passed partially matches with a resource in the help desk.
To perform wildcard match, append an asterisk (*) after the value to search.

Query Params

Param Name
Data Type
Description
from

int

From index, starts from 0

limit

int

No. of entities to fetch

departmentId

long

ID of the department from which the entity must be fetched if not passed then searches in permitted departments
exact match

id

String

ID of the Product
exact match

productName

String

Name of the Product
wildcard search

productCode

String

Code of the product
wildcard search

contactId

String

ID of the contact associated with the product
exact match

accountId

String

ID of the account associated with the product
exact match

_all

String

Search throughout the product
wildcard search

customField1

String

Custom field in the product
wildcard search

customField2

String

Custom field in the product
wildcard search

customField3

String

Custom field in the product
wildcard search

customField4

String

Custom field in the product
wildcard search

customField5

String

Custom field in the product
wildcard search

customField6

String

Custom field in the product
wildcard search

customField7

String

Custom field in the product
wildcard search

customField8

String

Custom field in the product
wildcard search

customField9

String

Custom field in the product
wildcard search

customField10

String

Custom field in the product
wildcard search

createdTimeRange

timestamp

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

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

SortBy can be:
relevance,

modifiedTime,

createdTime,

productName

GET /api/v1/products/search

OAuth Scope

Desk.settings.READ , Desk.search.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/products/search?limit=1&productName=Search2
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-11-02T10:31:35.000Z",
    "productCode" : "Search2",
    "createdBy" : "5000000009116",
    "description" : null,
    "createdTime" : "2017-11-02T10:31:35.000Z",
    "modifiedBy" : "5000000009116",
    "departmentIds" : [ "5000000007235" ],
    "id" : "5000000009882",
    "productName" : "Search2"
  } ],
  "count" : 5
}

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

ReadOnly

ID of the time entry

ticketId

long

ReadOnly

ID of the ticket

requestChargeType

string

Optional

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

JSONObject

ReadOnly

Module to which the time entry is associated.

executedTime

timestamp

Optional

Time when work related to the time entry was started.

hoursSpent

integer

Optional

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

totalCost

double

ReadOnly

Total cost incurred

description

string

Optional

Description of the time entry

customFields

list

Optional

Custom fields related to the time entry.

createdTime

timestamp

ReadOnly

Time of creating the ticket time entry

modifiedTime

timestamp

ReadOnly

Time of modifying the ticket time entry

createdBy

string

ReadOnly

User who created the time entry.

modifiedBy

string

ReadOnly

User who modified the time entry.

invoiceId

long

Optional

ID of the invoice related to the time entry

Example

{ "owner" : { "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "0", "parent" : { "id" : "4000000031007", "type" : "TICKETS" }, "executedTime" : null, "customFields" : { }, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "createdTime" : "2016-05-30T09:58:08.149Z", "invoiceId" : "4000000008688123", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }



Get a Ticket Time Entry

This API fetches a time entry recorded for a ticket.

Query Params

Param Name
Data Type
Description

string

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 -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" : {
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Case"
  },
  "parent" : {
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "secondsSpent" : "21",
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "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.

Query Params

Param Name
Data Type
Description
module

string

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

isBillable

boolean

Key that returns if the time tracked is billable or not

from

integer

Index number, starting from which the time entries must be fetched

limit

integer

Number of time entries to fetch

orderBy

String

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

string

Secondary information related to the time entry. Value supported is owner.

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

OAuth Scope

Desk.tickets.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry?from=0&limit=10&include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time1"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time2"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "22",
    "parent" : {
      "id" : "4000000031007",
      "type" : "TICKETS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time3"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add a Ticket Time Entry

This API creates a time entry in your help desk

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

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time2" }, "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" : {
    "id" : "4000000031007",
    "type" : "TICKETS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time2"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update a Ticket Time Entry

This API updates an existing time entry

PATCH /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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" : {
    "associatedTicketId" : "4000000031007",
    "id" : "4000000031008",
    "type" : "TASKS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "invoiceId" : "4000000008688123",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete a Ticket Time Entry

This API deletes a time entry from your help desk

DELETE /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

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

Query Params

Param Name
Data Type
Description
module

string

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

isBillable

boolean

Key that returns if the time tracked is billable or not

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

OAuth Scope

Desk.tickets.READ

Request Example

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

Response Example

{
  "totalMins" : 5,
  "totalHours" : 12,
  "totalCosts" : 1000,
  "totalSeconds" : 24
}

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

Required

IDs of users to whom the approval must be submitted

subject

string

Required

Subject of the approval

status

string

Optional

Status of the approval

description

String

Optional

Description of the approval

requestedTime

timestamp

ReadOnly

Time when the approval was requested

processedTime

timestamp

ReadOnly

Time when the approval was processed

id

long

ReadOnly

ID of the approval

requester

object

ReadOnly

Details of user who requested for the approval

object

ReadOnly

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.

Query Params

Param Name
Data Type
Description
from

integer

Index number starting from which the approvals must be fetched

limit

integer

Number of approvals to fetch

status

string

Key that filters the approvals by status

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

OAuth Scope

Desk.tickets.READ

Request Example

$ 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" : "saran@zohocorp.com"
    },
    "requester" : {
      "firstName" : "",
      "lastName" : "saran",
      "photoUrl" : "https://desk.zoho.com/api/v1/agent/4000000012629/photo",
      "id" : "4000000012629",
      "email" : "saranraj@zoho.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.

GET /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.READ

Request Example

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

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

OAuth Scope

Desk.tickets.CREATE

Request Example

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

PATCH /api/v1/tickets/{ticket_id}/approvals/{approval_id}

OAuth Scope

Desk.tickets.UPDATE

Request Example

$ 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

ReadOnly

ID of the time entry

ticketId

long

ReadOnly

ID of the ticket

requestChargeType

string

Optional

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

JSONObject

ReadOnly

Module to which the time entry is associated.

executedTime

timestamp

Optional

Time when work related to the time entry was started.

hoursSpent

integer

Optional

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

totalCost

double

ReadOnly

Total cost incurred

description

string

Optional

Description of the time entry

customFields

list

Optional

Custom fields related to the time entry.

createdTime

timestamp

ReadOnly

Time of creating the ticket time entry

modifiedTime

timestamp

ReadOnly

Time of modifying the ticket time entry

createdBy

string

ReadOnly

User who created the time entry.

modifiedBy

string

ReadOnly

User who modified the time entry.

invoiceId

long

Optional

ID of the invoice related to the time entry

Example

{ "owner" : { "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "0", "parent" : { "associatedTicketId" : "4000000030017", "id" : "4000000031014", "type" : "TASKS" }, "executedTime" : null, "customFields" : { }, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "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.

Query Params

Param Name
Data Type
Description

string

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tasks.READ

Request Example

$ 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" : {
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Case"
  },
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000030017",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "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.

Query Params

Param Name
Data Type
Description
isBillable

boolean

Key that returns if the time tracked is billable or not.

from

integer

Index number, starting from which the time entries must be fetched

limit

integer

Number of time entries to fetch

orderBy

String

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

string

Secondary information related to the time entry. Value supported is owner.

GET /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.tasks.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntry?from=0&limit=10&include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time1"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time2"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "22",
    "parent" : {
      "associatedTicketId" : "4000000030017",
      "id" : "4000000031014",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time3"
    },
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "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

POST /api/v1/tasks/{task_id}/timeEntry

OAuth Scope

Desk.tasks.CREATE

Request Example

$ 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", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time2" }, "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" : {
    "associatedTicketId" : "4000000030017",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time2"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "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.

PATCH /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tasks.UPDATE

Request Example

$ 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" : {
    "associatedTicketId" : "4000000030017",
    "id" : "4000000031014",
    "type" : "TASKS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "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.

DELETE /api/v1/tasks/{task_id}/timeEntry/{timeEntry_id}

OAuth Scope

Desk.tasks.UPDATE

Request Example

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

Query Params

Param Name
Data Type
Description
isBillable

boolean

Key that returns if the time tracked is billable or not.

GET /api/v1/tasks/{task_id}/timeEntrySummation

OAuth Scope

Desk.tasks.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/4000000031007/timeEntrySummation
  -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

ReadOnly

ID of the time entry

ticketId

long

ReadOnly

ID of the ticket

requestChargeType

string

Optional

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

JSONObject

ReadOnly

Module to which the time entry is associated.

executedTime

timestamp

Optional

Time when work related to the time entry was started.

hoursSpent

integer

Optional

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

totalCost

double

ReadOnly

Total cost incurred

description

string

Optional

Description of the time entry

customFields

list

Optional

Custom fields related to the time entry.

createdTime

timestamp

ReadOnly

Time of creating the ticket time entry

modifiedTime

timestamp

ReadOnly

Time of modifying the ticket time entry

createdBy

string

ReadOnly

User who created the time entry.

modifiedBy

string

ReadOnly

User who modified the time entry.

invoiceId

long

Optional

ID of the invoice related to the time entry

Example

{ "owner" : { "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "0", "parent" : { "id" : "4000000031007", "type" : "TICKETS" }, "executedTime" : null, "customFields" : { }, "departmentId" : "4000000008694", "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : "4000000008688", "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.

Query Params

Param Name
Data Type
Description

string

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 -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" : {
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
    "name" : "Case"
  },
  "secondsSpent" : "21",
  "parent" : {
    "associatedTicketId" : "4000000031007",
    "id" : "4000000031010",
    "type" : "TASKS"
  },
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "departmentId" : "4000000008694",
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "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.

Query Params

Param Name
Data Type
Description
module

string

Module from which the time entries must be fetched. Values allowed are tickets and tasks.

departmentId

long

ID of the department

isBillable

boolean

Key that returns if the time tracked is billable or not

from

integer

Index number, starting from which the time entries must be fetched

limit

integer

Number of time entries to fetch

orderBy

String

Key that sorts the time entries in ascending or descending order, based on the executedTime attribute. Values allowed are ASC (default) and DESC.

string

Secondary information related to the time entry. Value supported is owner.

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

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntry?module=ticket&isBillable=true&from=0&limit=10&include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "departmentId" : "4000000008694",
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "21",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "departmentId" : "4000000008694",
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "invoiceId" : "40000000086881212",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "owner" : {
      "photoURL" : "https://contacts.zoho.com/file?t=user&ID=4851669",
      "name" : "Case"
    },
    "secondsSpent" : "22",
    "parent" : {
      "associatedTicketId" : "4000000031007",
      "id" : "4000000031010",
      "type" : "TASKS"
    },
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "departmentId" : "4000000008694",
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "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.

Query Params

Param Name
Data Type
Description
module

string

Module Preference. It can be either tickets tasks

isBillable

boolean

Key that returns if the time tracked is billable or not

departmentId

long

ID of the department

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

OAuth Scope

Desk.settings.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000031007/timeEntrySummation?module=ticket&isBillable=true
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"