Desk API Documentation
CURL
select client library
CURL
Java

Introduction

Zoho Desk APIs facilitate integration with other Zoho applications and third-party tools by adhering to RESTful principles. These APIs enable you to programmatically fetch and edit data in the different modules in Zoho Desk, such as Tickets, Contacts, Accounts and so on. All the APIs follow HTTP rules and error codes. To keep yourself updated about the changes in our APIs, follow the Zoho Desk Developer APIs forum.


API Root Endpoint

desk.zoho.com/api/v1

Getting Started

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

  1. Authorization - Authentication request token
  2. orgId -ID of the organization to access. All API endpoints except /organizations mandatorily require the orgId.

Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

HTTP Methods

Zoho Desk APIs enable data manipulation and retrieval through different HTTP methods.



Method Purpose
GET Retrieve resources
POST Create resources and perform resource actions
PUT Update resources
PATCH Partially update resources
DELETE Delete resources




Using the GET method, you can get a list of resources or details of a particular instance of a resource.
To get a list of tickets

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

To get the details of a ticket referred to by a specified ticket_id

$ curl -X GET https:// desk.zoho.com/api/v1/tickets/903000000000099
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Errors

Zoho Desk uses HTTP status codes to indicate success or failure of API calls. Status codes in the 2xx range indicate success, 4xx range indicate error in the information provided, and 5xx range indicate server side errors. The following table lists some commonly used HTTP status codes.

HTTP Status Codes

Status Code Description
200 OK
201 Created
204 No content
400 Bad request
401 Unauthorized
403 Forbidden (Unauthorised access)
404 URL not found
405 Method not allowed (Method called is not supported for the API invoked)
413 Payload Too Large
415 Unsupported Media Type
422 Unprocessable Entity
429 Too Many Requests
500 Internal error

Besides HTTP status codes and their corresponding error messages, error responses for Zoho Desk APIs also include a machine-parsable errorCode param to simplify error handling.

The different errorCodes and their uses are described below.


UNAUTHORIZED

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


INVALID_OAUTH

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


SCOPE_MISMATCH

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


OAUTH_ORG_MISMATCH

This errorCode value appears if the user chooses a different organization while generating the OAuthToken instead of the organization in which they want to perform the operation.


FORBIDDEN

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


LICENSE_ACCESS_LIMITED

This errorCode value appears if the user is unable to perform an action due to the limitations of the Zoho Desk edition in use

The possible values for the feature key are

  • AGENTS
  • LIGHT_AGENTS
  • TEAM

The possible values for the editionType key are

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


OAuth Org Mismatch Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8


Forbidden Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8


LicenseAccessLimited Error Response

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8


Url Not Found Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8


Method Not Allowed Error Response

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8


Resource Size Exceeded Error Response

HTTP/1.1 413 Payload Too Large
Content-Type: application/json;charset=UTF-8


Unsupported Media Type Error Response

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json;charset=UTF-8


Invalid Data Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8


Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8


Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8


Unprocessable Entity Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8


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(OAuth)

Zoho Desk's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization. This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. Each API request must include an OAuthToken to retrieve any resource from your Zoho Desk portal.

To view a sample reference code in Java to help you understand the OAuth authorization flow for Zoho Desk Rest APIs, click here.


Why should we use OAuth2.0?

  • Clients are not required to support password authentication or store user credentials.

  • Clients gain delegated access, i.e., access only to resources authenticated by the user.

  • Users can revoke the client's delegated access anytime.

  • OAuth2.0 access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.

How OAuth2.0 works?

Terminologies

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

Protected resources:

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

Resource server:

The Zoho Desk server that hosts protected resources.

Resource owner:

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

Client:

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

Client ID:

The consumer key generated from the connected application.

Client Secret:

The consumer secret generated from the connected application.

Authentication server:

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the Zoho Desk authorization server.

Authentication code:

The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens..

Tokens

Access Token:

A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to Zoho Desk APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.

Refresh Token:

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Sample Success Response

Step 1: Register your Application

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

Choose a client type

  • Java Script: Applications that run exclusively on a browser and are independent of a web server.

  • Web Based: Applications that are clients running on a dedicated HTTP server.

  • Mobile: Applications that are installed on smart phones and tablets.

  • Non-browser Mobile Applications: Applications for devices without browser provisioning such as smart TVs and printers.

  • Self Client: If your application is a stand-alone application that performs only back-end jobs like data-sync (without any manual intervention).

For more details, refer to OAuth Overview.

Choose Web based client and Enter the following details:

  • Client Name: The name of your application you want to register with Zoho.

  • Homepage URL: The URL of your web page.

  • Authorized Redirect URIs: A valid URL of your application to which Zoho Accounts redirects you with a grant token(code) after successful authentication.


On successful registration, you will be provided with a client ID and a client secret. These are your OAuth credentials.


Step2: Making the Authorization Request

To use the Zoho Desk APIs, the user must authenticate the application to make API calls on their behalf with an access token.

The access token, in return, must be obtained from a grant token (authorization code). The Zoho Desk APIs use the authorization code grant type to provide access to protected resources.

There are two ways in which you can generate the grant token based on the client type.

Web-based application

Web-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. For this client-type, you must use redirection-based code generation. In this authorization flow, obtain an authorization grant by invoking the authorization URI, that contains the parameters listed in the table below. Refer to the example to understand how to construct this authorization URI.


Parameter Description
client_id Client ID generated after registering the client.
response_type "code"
redirect_uri Redirect URI mentioned while registering the client.
scope The various scopes associated with Zoho Desk.You can use the list of scopes as per your requirement
access_type "offline"/"online". In cases where refresh tokens can't be stored, use online access_type. The default will be online
state State is an opaque value used by the client to maintain state between the request and callback.

After you invoke the authorization URI, a "user-consent" page opens.


When the user clicks Accept:

The application gets authorized. The grant token sent as a parameter in the redirect_uri.

A back-end script from your end needs to store the following details from the above URL.

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

The application exchanges the authorization code for an access token.


When the user clicks Reject:

The browser redirects to the redirect URI with the parameter error=access_denied, and your application is denied access to the user's data in Zoho Desk.


Note:

The grant token is valid only for one minute.


Generating OAuth Tokens Using Self Client

Use this method to generate the grant token if your application does not have a domain and a redirect URL.
You can also use this option when your application is a standalone server-side application performing a back-end job.

  1. Go to Zoho Developer Console.

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

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

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

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

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

  7. Enter a description and click Generate.

  8. The generated code for the specified scope is displayed. Copy the grant token.

Note:

Generating the grant token is a one-time process, provided you generate the access and refresh tokens within the time the grant token is valid for.

Authorization Grant API Url

GET https://accounts.zoho.com/oauth/v2/auth

Query Params

?response_type=code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&state=-5466400890088961855


Step 3: Generating Tokens

Invoke a URL in the following format to exchange the authorization code (obtained at the end of the previous step) with an OAuthToken.

Parameter Description
code Authorization code obtained after generating the grant token.
client_id Client ID obtained after registering the client.
client_secret Client secret obtained after registering the client.
grant_type "authorization_code"
redirect_uri Redirect URI mentioned while registering the client.

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


Note:

Each access token is valid for only an hour and used only for the operations defined in the scope.

Refresh token does not expire. Use it to refresh access tokens when they expire.

You can only generate a maximum of five refresh tokens in a minute.

Access Token API Url

POST https://accounts.zoho.com/oauth/v2/token

Query Params

?code=1000.fadbca4c2be2f08b0ce82a54f4313.ba5325853af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/oauthgrant


Response Example

Step 4: Refreshing your Access Tokens

Access tokens generally expire in one hour, which means a new access token has to be generated to keep the process going. You can eliminate the need to perform the entire procedure to generate access tokens, by using refresh tokens. Once the access token expires, the refresh token can be used to generate a new access token.

Refresh token can be obtained only when access_type is set to offline while creating the access token.

Refer to the example to understand how an access token can be obtained using the refresh token.


Note:

  • A "User" in an organization can have a maximum of 20 refresh tokens. And each refresh token can have a maximum of 30 active access tokens (non expired).

  • When a user creates a 31st access token, the system deletes the first created access token. Similarly, when the user creates the 21st refresh token, the system deletes the first created refresh token.

  • You can only generate a maximum of five refresh tokens in a minute.

  • We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your Desk account.

Access Token From Refresh token API Url

POST https://accounts.zoho.com/oauth/v2/token

Query Params

?refresh_token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&grant_type=refresh_token

Response Example

Step 5: Revoking Tokens

If you want to revoke your refresh token, Make a POST request with the following URL:

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Refer to the example to understand how a refresh token can be revoked.


Revoking Token API Url

POST https://accounts.zoho.com/oauth/v2/token/revoke

Query Params

?token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e

Using OAuth Token In API Calls

To invoke Zoho Desk's APIs, pass the access token in the Authorization parameter in the header, as shown in the example.


Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

Response Example

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8

OAuth Scopes

The various scopes accessible using Zoho Desk's APIs are as follows:

ScopeName Description

Desk.tickets.ALL

Grants read and write access to tickets and related data.

Desk.tickets.READ

Grants read access to tickets and related data.

Desk.tickets.WRITE

Grants write access to tickets.

Desk.tickets.UPDATE

Grants update access to tickets and related data.

Desk.tickets.CREATE

Grants access to create tickets

Desk.tickets.DELETE

Grants access to delete tickets

Desk.contacts.READ

Grants read access to contacts, accounts and related data

Desk.contacts.WRITE

Grants write access to contacts, accounts and related data

Desk.contacts.UPDATE

Grants update access to contacts, accounts and related data

Desk.contacts.CREATE

Grants access to create contacts and accounts

Desk.tasks.ALL

Grants read and write access to tasks and related data

Desk.tasks.WRITE

Grants write access to tasks and related data

Desk.tasks.READ

Grants read access to tasks and related data

Desk.tasks.CREATE

Grants access to create tasks

Desk.tasks.UPDATE

Grants update access to tasks and related data

Desk.tasks.DELETE

Grants access to delete tasks

Desk.basic.READ

Grants read access to basic data, such as organizations, agents and departments

Desk.basic.CREATE

Grants access to create basic data, such as organizations, agents and departments

Desk.settings.ALL

Grants read and write access to settings data

Desk.settings.WRITE

Grants write access to settings data

Desk.settings.READ

Grants read access to settings data

Desk.settings.CREATE

Grants access to create new settings data

Desk.settings.UPDATE

Grants access to update existing settings data

Desk.settings.DELETE

Grants access to delete settings data

Desk.search.READ

Grants access to search for data

Desk.events.ALL

Grants read and write access to the events subscription

Desk.events.READ

Grants read access to the events subscription

Desk.events.WRITE

Grants write access to the events subscription

Desk.events.CREATE

Grants access to create events subscription

Desk.events.UPDATE

Grants update access to the events subscription

Desk.events.DELETE

Grants delete access to the events subscription

Desk.articles.READ

Grants read access to articles

Desk.articles.CREATE

Grants access to create articles

Desk.articles.UPDATE

Grants update access to articles

Desk.articles.DELETE

Grants delete access to articles

Organization Binding

Any OAuth token generated is linked to a Zoho Desk organization. This step of associating the token and the organization, which happens in the backend while getting authorization consent from the end user, is called organization binding.


If the end-user has only one Zoho Desk organization (portal), the OAuth token is linked to it automatically. If they have multiple organizations, they must manually select the one with which the token must be linked, as illustrated in the following image.


After they click the Submit button, the OAuth token is generated with the organization information bound to it.


Zoho Desk APIs automatically extract organization information from OAuth tokens. Therefore, it is not necessary to add the extra orgId query parameter in an API call or pass it in the API's header. However, if you choose to do so, make sure that the value of orgId is same as that of the portal bound with the OAuth token. If the IDs do not match, the API call fails, and the OAUTH_ORG_MISMATCHerror message is returned.


Webhook

Zoho Desk supports webhooks that asynchronously deliver information on events that occur in the help desk. These events include actions, such as creating or updating a ticket, contact, or account, and so on. For information on how to include Zoho Desk webhooks in your service, refer to this document.

Phone Bridge

The Zoho PhoneBridge feature connects your PBX system and your Zoho Desk portal that holds all the important details of your customers. With this feature, Zoho Desk offers you a platform to manage incoming and outgoing calls on your computer. Additionally, you can view the name, phone number, and overall customer happiness score of your customers when they call. To know more about this please refer this document

Help Center

Your help center is one of the key channels through which customers can seek support. This portal provides your customers with access to major help modules, such as your knowledge base, user community, live chat, and ticket submission form. A well-designed and well-maintained help center ensures good self-service capabilities for your customers and lesser burden on your support agents. To know more about this please refer this document

Java SDK

The Zoho Desk Java SDK helps you create client Java applications that can be integrated with your Zoho Desk portal. This SDK makes it easy to access and use Zoho Desk APIs where necessary. In other words, it serves as a wrapper for the REST APIs, making it easy to use Zoho Desk's functionalities in your custom applications. To know more about this SDK please refer this document

Organizations

In Zoho Desk, each business is categorized as an organization. If you have multiple businesses, set each business up as an individual organization by creating a new signup and generating a unique organization ID. All APIs except the ones directly related to organizations must include the organization ID in the header in this format: orgId:{organization_id}

ATTRIBUTES

Attribute Name
Data Type
Description
companyName

string

Actual name of the organization/business

portalName

string

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

phoneNumber

string

Phone number of the organization

edition

string

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

id

long

Unique ID of the organization

isDefault

boolean

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

isAdminInOrg

boolean

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

portalURL

string

URL of the help desk portal

logoURL

string

URL of the image file displaying the organization's logo

alias

string

Alternative name for the help desk portal

employeeCount

string

Number of employees in the organization

description

string

Brief description of the organization

mobile

string

Mobile number of the organization

website

string

Website of the organization

fax

string

Fax number of the organization

primaryContact

string

Primary contact person in the organization

street

string

Street in which the organization's office is located

city

string

City in which the organization's office is located

state

string

State in which the organization's office is located

zip

string

Zip code of the organization's address

country

string

Country in which the organization's office is located

currencyLocale

string

Currency locale in which the organization operates

currencySymbol

string

Currency symbol used in the organization

Example

{ "zip" : "68838-2640", "country" : "United States", "website" : "www.zylker.com", "city" : "Bernierview", "companyName" : "Zylker INC.", "mobile" : "9848022338", "description" : "We are Zylker Support.", "edition" : "ENTERPRISE", "currencySymbol" : "$", "employeeCount" : "10", "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true, "isDefault" : "false", "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8", "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

optional,
default : false

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

GET /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

OrganizationAPI organization = ZDesk.getOrganizationAPIInstance(mailId);
GetOrganizationFilter filter = new GetOrganizationFilter.Builder().setIncludeCustomDomain(includeCustomDomain).build();
Organization response = organization.getOrganization( organizationId, filter );

Response Example

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

Get all organizations

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

GET /api/v1/organizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

OrganizationAPI organization = ZDesk.getOrganizationAPIInstance(mailId);
List<Organization> response = organization.getOrganizations( );

Response Example

{
  "data" : [ {
    "zip" : "68838-2640",
    "country" : "United States",
    "website" : "www.zylker.com",
    "city" : "Bernierview",
    "companyName" : "Zylker INC.",
    "mobile" : "9848022338",
    "description" : "We are Zylker Support.",
    "edition" : "ENTERPRISE",
    "currencySymbol" : "$",
    "employeeCount" : "10",
    "logoURL" : "https://desk.zoho.com/api/v1/organizations/3981311/logo?no-cache=ffc59c3ba6585c12fb306f5174948ff6",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
    "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",
    "city" : "Port Cierra",
    "companyName" : "Nshlerin LLC.",
    "mobile" : "987654321",
    "description" : "We are Nshlerin Support.",
    "edition" : "PROFESSIONAL",
    "currencySymbol" : "$",
    "employeeCount" : "20",
    "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true,
    "isDefault" : "false",
    "faviconURL" : "https://desk.zoho.com/api/v1/organizations/5988319/favicon?no-cache=b31a9627de49fge046fcab71sf3359eq",
    "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"
  } ]
}

Get accessible organizations

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

GET /api/v1/accessibleOrganizations

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

Update organization

This API updates the details of an organization.

Attributes

Param Name
Data Type
Description
companyName

string

optional,
max chars : 50

Actual name of the organization/business

portalName

string

optional,
max chars : 100

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

phoneNumber

string

optional,
max chars : 30

Phone number of the organization

edition

string

optional,
max chars : 100

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

alias

string

optional,
max chars : 50

Alternative name for the help desk portal

employeeCount

string

optional,
max chars : 19

Number of employees in the organization

description

string

optional,
max chars : 250

Brief description of the organization

mobile

string

optional,
max chars : 30

Mobile number of the organization

website

string

optional,
max chars : 50

Website of the organization

fax

string

optional,
max chars : 100

Fax number of the organization

primaryContact

string

optional,
max chars : 100

Primary contact person in the organization

street

string

optional,
max chars : 50

Street in which the organization's office is located

city

string

optional,
max chars : 50

City in which the organization's office is located

state

string

optional,
max chars : 50

State in which the organization's office is located

zip

string

optional,
max chars : 100

Zip code of the organization's address

country

string

optional,
max chars : 50

Country in which the organization's office is located

currencyLocale

string

optional,
max chars : 100

Currency locale in which the organization operates

PATCH /api/v1/organizations/{organization_Id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

{
  "zip" : "68838-2640",
  "country" : "United States",
  "website" : "www.zylker.com",
  "city" : "Bernierview",
  "companyName" : "Zylker Desk",
  "mobile" : "9848022338",
  "description" : "We are Zylker Support.",
  "edition" : "ENTERPRISE",
  "currencySymbol" : "$",
  "employeeCount" : "10",
  "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png",
  "isAdminInOrg" : true,
  "isDefault" : "false",
  "faviconURL" : "https://desk.zoho.com/api/v1/organizations/3981311/favicon?no-cache=d61a9627de49ffe046fcab71af3359e8",
  "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

string

optional,
max chars : 100

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

fileSize

string

optional,
max chars : 100

Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.

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

OAuth Scope

Request Example

  • CURL

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

Response Example

200

Update organization favicon

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

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

Request Example

  • CURL

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

Response Example

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

Delete organization favicon

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

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

Response Example

204

Update default organization

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

Attributes

Param Name
Data Type
Description
id

long

required

Unique ID of the organization to be marked as default org

POST /api/v1/organizations/markDefault

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Agents

Agents are the customer service executives in your organization. They are the primary users of the helpdesk software, using which they interact with contacts and resolve tickets.

ATTRIBUTES

Attribute Name
Data Type
Description
emailId

string

Email ID of the agent

status

string

Activation status of the agent: ACTIVE or DISABLED

lastName

string

Last name of the agent

firstName

string

First name of the agent

name

string

Full name of the agent

phone

string

Phone number of the agent

mobile

string

Mobile number of the agent

extn

string

Extension number of the agent

associatedDepartmentIds

list

Departments with which the agent is associated

associatedChatDepartmentIds

list

Chat departments with which the agent is associated

id

long

ID of the agent

zuid

long

Zoho user ID of the agent

roleId

long

Role ID of the agent

profileId

long

Profile ID of the agent

photoURL

string

URL of the image file displaying the agent's photo

isConfirmed

boolean

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

rolePermissionType

string

The Role Permission type of Agent

aboutInfo

string

Agent's about info

channelExpert

list

The channels handled for the Agent

countryCode

string

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

timeZone

string

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

langCode

string

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

Example

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



Get agent

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

Query Params

Param Name
Data Type
Description

string

optional,
max chars : 100

Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, and associatedChatDepartments. You can include all four values by separating them with commas in the API request.

GET /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

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

Response Example

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

List agents

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the agents must be fetched

limit

integer

optional,
range : 0-200

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

status

string

optional,
max chars : 100

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

departmentIds
see documentation

long

optional

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

profileIds
see documentation

long

optional

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

long

optional

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

rolePermissionType

string

optional,
max chars : 100

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

isConfirmed

boolean

optional

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

isLightAgent

boolean

optional

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

string

optional,
max chars : 100

Secondary information related to agents, Values allowed are profile, role. You can include all two values by separating them with commas in the API request.

searchStr

string

optional,
max chars : 100

String to search for agents by first name, last name, or email ID. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for agents whose first name, last name, or email ID start with the string, 2) *string* - Searches for agents whose first name, last name, or email ID contain the string, 3) string - Searches for agents whose first name, last name, or email ID is an exact match for the string

fieldName

string

optional,
max chars : 100

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

sortOrder

string

optional,
max chars : 100

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

GET /api/v1/agents

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

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

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

Get agents count

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

Query Params

Param Name
Data Type
Description
status

string

optional,
max chars : 100

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

isConfirmed

boolean

optional

Filters Confirmed & Unconfirmed agents

includeLightAgent

boolean

optional

Count light agent.

GET /api/v1/agents/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "count" : 5
}

Get agent details by agentId

This API fetches details of agents via the agent IDs passed in the API request.

Query Params

Param Name
Data Type
Description
agentIds

long

required

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
List<Agent> response = agent.getAgentsByIds(agentIds );

Response Example

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

Get My Information

This API fetches details of the currently logged in agent.

Query Params

Param Name
Data Type
Description

string

optional,
max chars : 100

Secondary information related to the agent. Values allowed are profile, role, associatedDepartments, and associatedChatDepartments. You can pass multiple values by separating them with commas in the query param

GET /api/v1/myinfo

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

AgentAPI agent = ZDesk.getAgentAPIInstance(mailId);
Agent response = agent.getMyInfo( include );

Response Example

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

Activate agents

This API activates agents in your help desk.

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

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/activate

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Deactivate agent

This API deactivates an agent in your help desk.

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

Response Example

204

Reinvite unconfirmed agents

This API sends reinvitation mails to unconfirmed agents.

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/reinvite

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Add agent

This API adds an agent to your help desk.


Keep in mind the following points while adding an agent:

  1. The 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"
    6. For the Agent profile and Personal Team role, pass "rolePermissionType":"AgentTeamPersonal"

Attributes

Param Name
Data Type
Description
emailId

string

required,
max chars : 100

Email ID of the agent

lastName

string

required,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

required

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

required,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 255

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

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

timeZone

string

optional,
max chars : 100

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

langCode

string

optional,
max chars : 100

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

POST /api/v1/agents

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL
  • Java

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

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

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

Response Example

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

Update agent

This API updates details of an agent.

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

Attributes

Param Name
Data Type
Description
emailId

string

optional,
max chars : 100

Email ID of the agent

lastName

string

optional,
max chars : 50

Last name of the agent

firstName

string

optional,
max chars : 50

First name of the agent

phone

string

optional,
max chars : 100

Phone number of the agent

mobile

string

optional,
max chars : 100

Mobile number of the agent

extn

string

optional,
max chars : 100

Extension number of the agent

associatedDepartmentIds

list

optional

Departments with which the agent is associated

associatedChatDepartmentIds

list

optional

Chat departments with which the agent is associated

rolePermissionType

string

optional,
max chars : 100

The Role Permission type of Agent

aboutInfo

string

optional,
max chars : 255

Agent's about info

channelExpert

list

optional

The channels handled for the Agent

countryCode

string

optional,
max chars : 100

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

timeZone

string

optional,
max chars : 100

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

langCode

string

optional,
max chars : 100

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

PATCH /api/v1/agents/{agent_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

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

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

Response Example

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

Delete unconfirmed agents

This API deletes unconfirmed agents from your help desk.

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

POST /api/v1/agents/deleteUnconfirmed

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Delete confirmed agent

This API deletes a confirmed agent from your help desk.

Attributes

Param Name
Data Type
Description
anonymizedName

string

optional,
max chars : 50

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

isAnonymize

boolean

optional

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL

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

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

Response Example

204

Anonymize deleted agent

This API removes the identification details of a deleted agent.

Attributes

Param Name
Data Type
Description
anonymizedName

string

optional,
max chars : 50

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Upload my photo

This API sets the profile photo for the currently logged in agent.

Note: To upload your photo generate OAuthToken for the scope: Desk.settings.UPDATE,profile.userphoto.UPDATE or Desk.basic.UPDATE,profile.userphoto.UPDATE

File Params

userPhoto

Content-Type:multipart/form-data

Image file containing the agent's photo. Maximum file size allowed is 500KB; maximum file limit is one; and extensions allowed are: .jpg, .png, .gif, and .jpeg.

POST /api/v1/uploadMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

Response Example

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

Get agent photo

This API gets the profile photo for the given agent id.

Note: To get agent photo generate OAuthToken for the scope: Desk.settings.READ,profile.userphoto.READ or Desk.basic.READ,profile.userphoto.READ

Query Params

Param Name
Data Type
Description
fileSize

string

optional,
max chars : 100

Size of the image file to download. Values allowed are THUMBNAIL (image with reduced dimensions and size) and ACTUAL (image with actual dimensions and size). The default value is ACTUAL.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

200

Delete My Photo

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

POST /api/v1/deleteMyPhoto

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

Response Example

204

Get My Preferences

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

GET /api/v1/myPreferences

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

Update My Preferences

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

Attributes

Param Name
Data Type
Description
namePattern

List

optional

Pattern that defines how the names should be displayed

currentDepartment

long

optional

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

PATCH /api/v1/myPreferences

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

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

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

Response Example

204

Get agent by email ID

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

Schedule reassignment for deactivated or deleted agents

This API schedules reassignment of tickets, tasks, and automations belonging to a deleted/deactivated agent to another agent within the same department.

Attributes

Param Name
Data Type
Description
agentReassignment

list

required

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

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Profiles

Profiles control the user permissions to access help desk modules, records, fields in a record, and other utilities, such as import, export, send email, etc. Users associated with a profile can access only the functions that are assigned to that profile.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

Name of the profile

description

string

Description of the profile

isVisible

boolean

If the profile is visible in UI

type

string

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

default

boolean

If the profile is system generated

id

long

Id of the profile

permissions

object

Details of the permissions for the profile

Example

{ "default" : true, "permissions" : { "crmInteg" : { "crmContactsActivityEvents" : false, "crmAccountsActivityEvents" : false, "crmAccountsActivityTasks" : false, "crmAccountsInfo" : false, "crmContactsActivityCalls" : false, "crmAccountsNotes" : false, "crmAccountsActivityCalls" : false, "crmContactsInfo" : false, "crmContactsNotes" : false, "crmContactsActivityTasks" : false, "crmAccountsPotentials" : false, "crmContactsPotentials" : false }, "reports" : { "view" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "tickets" : { "mergeTickets" : true, "changeOwner" : true, "import" : true, "handleUnassigned" : true, "edit" : true, "closeTicket" : true, "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, "edit" : true, "create" : true, "delete" : true, "moderate" : true }, "products" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "agents" : { "overview" : true, "import" : false, "edit" : false, "create" : true, "delete" : true, "viewAllFields" : true }, "kbCategory" : { "view" : true, "editAllArticles" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "setup" : { "timeTracking" : true, "fetchAcrossDepartment" : true, "globalReports" : true, "exportPortalUsers" : true, "layouts" : true, "automation" : true, "featureConfig" : true, "customerHappiness" : true, "department" : true, "portal" : true, "webForm" : true, "rebranding" : true, "email" : true, "tabsAndFields" : true, "exportUsers" : true, "teams" : true, "social" : true, "templates" : true, "moveRecords" : true, "permission" : true, "signUpApproval" : true, "community" : true, "importHistory" : true, "manageAgents" : true, "portalUsers" : true, "managerDashboard" : true, "googleAnalytics" : true, "chat" : true, "telephony" : true }, "financeInteg" : { "sendInvoice" : false, "createEstimate" : false, "createContact" : false, "viewInvoice" : false, "createInvoice" : false, "sendEstimate" : false, "viewEstimate" : false }, "accounts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "timeEntry" : { "view" : true, "edit" : true, "create" : true, "delete" : true }, "contacts" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true }, "tasks" : { "view" : true, "import" : true, "edit" : true, "create" : true, "delete" : true, "export" : true } }, "name" : "Support Administrator", "description" : "Set the privileges for support administrators.", "id" : "5000000015288", "isVisible" : true, "type" : "Administrator" }



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

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

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

searchStr

string

optional,
max chars : 100

String to search for profile by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for profiles whose name or description start with the string, 2) *string* - Searches for profiles whose name or description contain the string, 3) string - Searches for profiles whose name or description is an exact match for the string

GET /api/v1/profiles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
List<Profile> response = profile.getProfiles(default, visible, searchStr );

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

Get profile count

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

Query Params

Param Name
Data Type
Description
visible

boolean

optional

Key that filters profiles according to their visibility in the UI

default

boolean

optional

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

GET /api/v1/profiles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "count" : 8
}

Get profile

This API fetches the details of a particular profile.

GET /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile response = profile.getProfile( profileId );

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,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "4000000008464",
  "isVisible" : true,
  "type" : "Administrator"
}

Clone profile

This API replicates an existing profile.

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 50

Name of the profile to be created

description

String

optional

Description of the profile to be created

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

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL

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

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

Response Example

{
  "default" : false,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "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,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Admin Advisors",
  "description" : "Advisors from management to assist the Support Administrators.",
  "id" : "5000000046001",
  "isVisible" : true,
  "type" : "Custom"
}

Update profile

This API updates the details of an existing profile.

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 50

Name of the profile

description

string

optional,
max chars : 3200

Description of the profile

permissions

object

optional

Details of the permissions for the profile

PATCH /api/v1/profiles/{profile_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile profileObj = new Profile();
profileObj.setName(name);
profileObj.setDescription(description);
Profile response = profile.updateProfile( profileId, profileObj );

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,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : false
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "import" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : true,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : true,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : true,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : true,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : false,
      "googleAnalytics" : false,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Agent Advisors",
  "description" : "Advisors from CRM to assist the Support Agents.",
  "id" : "4000000018001",
  "isVisible" : true,
  "type" : "Custom"
}

Delete profile

This API deletes a profile from your help desk.

Attributes

Param Name
Data Type
Description
transferToProfileId

long

required

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
boolean response = profile.deleteProfile( profileId, transferToProfileId );

Response Example

204

Get my profile details

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

GET /api/v1/myProfile

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : true,
      "changeOwner" : true,
      "import" : true,
      "handleUnassigned" : true,
      "edit" : true,
      "closeTicket" : true,
      "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,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  },
  "name" : "Support Administrator",
  "description" : "Set the privileges for support administrators.",
  "id" : "35483000000008343",
  "isVisible" : true,
  "type" : "Administrator"
}

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

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
Profile response = profile.getMyProfilePermissions( );

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,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "moderate" : true
    },
    "products" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : true,
      "delete" : true,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "setup" : {
      "timeTracking" : true,
      "fetchAcrossDepartment" : true,
      "globalReports" : true,
      "exportPortalUsers" : true,
      "layouts" : true,
      "automation" : true,
      "featureConfig" : true,
      "customerHappiness" : true,
      "department" : true,
      "portal" : true,
      "webForm" : true,
      "rebranding" : true,
      "email" : true,
      "tabsAndFields" : true,
      "exportUsers" : true,
      "teams" : true,
      "social" : true,
      "templates" : true,
      "moveRecords" : true,
      "permission" : true,
      "signUpApproval" : true,
      "community" : true,
      "importHistory" : true,
      "manageAgents" : true,
      "portalUsers" : true,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : true,
      "telephony" : true
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : true,
      "create" : true,
      "delete" : true
    },
    "contacts" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : true,
      "edit" : true,
      "create" : true,
      "delete" : true,
      "export" : true
    }
  }
}

List agents by profile

This API lists agents mapped to a particular profile.

Query Params

Param Name
Data Type
Description
active

boolean

optional

Activation status of the agents to list

confirmed

boolean

optional

Confirmation status of the agents to list

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

ProfileAPI profile = ZDesk.getProfileAPIInstance(mailId);
GetAgentsByProfileFilter filter = new GetAgentsByProfileFilter.Builder().setActive(active).build();
List<Agent> response = profile.getAgentsByProfile( profileId, filter );

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

Request Example

  • CURL

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

Response Example

{
  "default" : true,
  "permissions" : {
    "crmInteg" : {
      "crmContactsActivityEvents" : false,
      "crmAccountsActivityEvents" : false,
      "crmAccountsActivityTasks" : false,
      "crmAccountsInfo" : false,
      "crmContactsActivityCalls" : false,
      "crmAccountsNotes" : false,
      "crmAccountsActivityCalls" : false,
      "crmContactsInfo" : false,
      "crmContactsNotes" : false,
      "crmContactsActivityTasks" : false,
      "crmAccountsPotentials" : false,
      "crmContactsPotentials" : false
    },
    "reports" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tickets" : {
      "mergeTickets" : false,
      "changeOwner" : false,
      "import" : false,
      "handleUnassigned" : false,
      "edit" : false,
      "closeTicket" : false,
      "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
    },
    "agents" : {
      "overview" : true,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "viewAllFields" : true
    },
    "kbCategory" : {
      "view" : true,
      "editAllArticles" : false,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "setup" : {
      "timeTracking" : false,
      "fetchAcrossDepartment" : true,
      "globalReports" : false,
      "exportPortalUsers" : false,
      "layouts" : false,
      "automation" : false,
      "featureConfig" : false,
      "customerHappiness" : false,
      "department" : false,
      "portal" : false,
      "webForm" : false,
      "rebranding" : false,
      "email" : false,
      "tabsAndFields" : false,
      "exportUsers" : false,
      "teams" : true,
      "social" : false,
      "templates" : false,
      "moveRecords" : false,
      "permission" : false,
      "signUpApproval" : false,
      "community" : false,
      "importHistory" : false,
      "manageAgents" : false,
      "portalUsers" : false,
      "managerDashboard" : true,
      "googleAnalytics" : true,
      "chat" : false,
      "telephony" : false
    },
    "financeInteg" : {
      "sendInvoice" : false,
      "createEstimate" : false,
      "createContact" : false,
      "viewInvoice" : false,
      "createInvoice" : false,
      "sendEstimate" : false,
      "viewEstimate" : false
    },
    "accounts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "timeEntry" : {
      "view" : true,
      "edit" : false,
      "create" : false,
      "delete" : false
    },
    "contacts" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    },
    "tasks" : {
      "view" : true,
      "import" : false,
      "edit" : false,
      "create" : false,
      "delete" : false,
      "export" : true
    }
  },
  "name" : "Light Agent",
  "description" : "Set the privilege for light agents",
  "id" : "15000000012421",
  "isVisible" : true,
  "type" : "Light"
}

Roles

Role refers to the user role that can be defined in Zoho Desk. Roles help define organization-wide hierarchy. Users at a higher hierarchy can always access all the records of at a lower hierarchy. For example, a Support Manager can access all the Agents' records, whereas Agents can access only their records.

ATTRIBUTES

Attribute Name
Data Type
Description
name

string

Name of the role

description

string

A short description of the role

isVisible

boolean

Key that denotes if the role is visible in the UI

isDefault

boolean

Key that denotes if the role is the default role

shareDataWithPeers

boolean

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

id

long

ID of the role

reportsTo

long

ID of the role to which the current role reports

immediateSubRoles

list

IDs of roles that directly report to the current role

Example

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



List roles

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

Query Params

Param Name
Data Type
Description
from

integer

optional,
range : >=0

Index number, starting from which the roles must be listed

limit

integer

optional,
range : 0-500

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

isVisible

boolean

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

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

searchStr

string

optional,
max chars : 100

String to search for roles by name or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for roles whose name or description start with the string, 2) *string* - Searches for roles whose name or description contain the string, 3) string - Searches for roles whose name or description is an exact match for the string

GET /api/v1/roles

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
GetRolesFilter filter = new GetRolesFilter.Builder().setIsDefault(isDefault).build();
List<Role> response = role.getRoles( from, limit, filter );

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

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Map<String, Object> response = role.getAgentsByRole( roleId );

Response Example

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

Create role

This API creates a role in your help desk.

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

required

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

reportsTo

long

optional

ID of the role to which the current role reports

POST /api/v1/roles

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL
  • Java

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role roleObj = new Role();
roleObj.setName(name);
roleObj.setDescription(description);
Role response = role.createRole( roleObj );

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.

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 50

Name of the role

description

string

optional,
max chars : 3200

A short description of the role

shareDataWithPeers

boolean

optional

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

reportsTo

long

optional

ID of the role to which the current role reports

PATCH /api/v1/roles/{role_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role roleObj = new Role();
roleObj.setName(name);
roleObj.setDescription(description);
Role response = role.updateRole( roleId, roleObj );

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.

Attributes

Param Name
Data Type
Description
transferToRoleId

long

required

Transfer the child-roles to the given role

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL
  • Java

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
boolean response = role.deleteRole( roleId, transferToRoleId );

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

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
Role response = role.getRole( roleId );

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

optional

Key that filters roles according to their visibility in the UI

isDefault

boolean

optional

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

GET /api/v1/roles/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "count" : 5
}

Get personal role

This API fetches the details of the personal role configured in your help desk. Agents with personal role can view only the tickets assigned to them and unassigned tickets.

GET /api/v1/personalRole

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

List roles by role IDs

This API lists details of the roles whose IDs are passed in the API request.

Query Params

Param Name
Data Type
Description

long

required

Comma separated role ids. Maximum allowed count is 50

GET /api/v1/rolesByIds

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

RoleAPI role = ZDesk.getRoleAPIInstance(mailId);
List<Role> response = role.getRolesByIds(roleIds );

Response Example

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

Teams

A team is a group of agents/users in a department. Just like how you can assign tickets or tasks to agents, you can also assign tickets and tasks to teams.

ATTRIBUTES

Attribute Name
Data Type
Description
name

String

Name of the team

description

String

A short description of the team

departmentId

Long

ID of the department to which the team belongs

list

List of sub-teams within the team

list

List of roles to add to the team

rolesWithSubordinates

list

List of roles with subordinates to add to the team

list

List of agents to add to the team

derivedAgents

list

List of agents derived with the properties set for the team

Example

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



Create team

This API creates a team in your help desk portal.

Attributes

Param Name
Data Type
Description
name

String

required

Name of the team

description

String

optional

A short description of the team

departmentId

Long

required

ID of the department to which the team belongs

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

POST /api/v1/teams

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL
  • Java

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team teamObj = new Team();
teamObj.setName(name);
teamObj.setDescription(description);
Team response = team.createTeam( teamObj );

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.

Attributes

Param Name
Data Type
Description
name

String

optional

Name of the team

description

String

optional

A short description of the team

subTeams

list

optional

List of sub-teams within the team

roles

list

optional

List of roles to add to the team

rolesWithSubordinates

list

optional

List of roles with subordinates to add to the team

agents

list

optional

List of agents to add to the team

PATCH /api/v1/teams/{team_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team teamObj = new Team();
teamObj.setName(name);
teamObj.setDescription(description);
Team response = team.updateTeam( team_id, teamObj );

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 and on hold tickets and tasks of the deleted team to a different team, pass the ticketNewTeam, taskNewTeam, ticketNewAgent, and taskNewAgent team parameters in the API request. If you do not want to assign the tickets to another team, pass the values of ticketNewTeam and ticketNewAgent as null. However, in the case of tasks, either taskNewTeam or taskNewAgent must have a valid value. Both parameters cannot be passed as null.

Attributes

Param Name
Data Type
Description
ticketNewTeam

long

required

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

ticketNewAgent

long

required

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

taskNewTeam

long

required

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

taskNewAgent

long

required

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

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

OAuth Scope

Desk.settings.DELETE , Desk.basic.DELETE

Request Example

  • CURL
  • Java

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
boolean response = team.deleteTeam( team_id, ticketNewAgent, ticketNewTeam, taskNewTeam, taskNewAgent );

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

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
Team response = team.getTeam( team_id );

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

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.listTeamsInCurrentAgentAssociatedDept( );

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.

Query Params

Param Name
Data Type
Description

string

optional,
max chars : 100

Secondary information related to the team. Values allowed are profile, role. You can include all two values by separating them with commas in the API request.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

List associable teams

This API lists the other teams that can be added as sub-teams to the current team.

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<String> response = team.getSubTeamsIds( team_id );

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

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.listAssociatedTeamsForAgent( agent_id );

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

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

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

TeamAPI team = ZDesk.getTeamAPIInstance(mailId);
List<Team> response = team.getTeamsInDepartment( department_id );

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

ID of the department

name

string

Name of the department

nameInCustomerPortal

string

Display name of the department in the help center

description

string

A short description of the department

isVisibleInCustomerPortal

boolean

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

isEnabled

boolean

Key that denotes if the department is enabled or not

isAssignToTeamEnabled

boolean

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

hasLogo

boolean

Key that denotes if the department has a logo or not

creatorId

long

ID of user who created the department

createdTime

timestamp

Time of creating the department

associatedAgentIds

list

IDs of agents associated with the department

isDefault

boolean

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

chatStatus

string

Chat status of the departments: AVAILABLE, DISABLED, NOT_CREATED

Example

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



Get department

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

GET /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department response = department.getDepartment( departmentId );

Response Example

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

List departments

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

Query Params

Param Name
Data Type
Description
isEnabled

boolean

optional

Key that filters departments based on their enabled status

from

integer

optional,
range : >=0

Index number, starting from which the departments must be fetched

searchStr

string

optional,
max chars : 100

String to search for departments by name, help center name, or description. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for departments whose name, help center name, or description start with the string, 2) *string* - Searches for departments whose name, help center name, or description contain the string, 3) string - Searches for departments whose name, help center name, or description is an exact match for the string

limit

integer

optional,
range : 0-200

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

chatStatus

string

optional,
max chars : 100

Key that filters departments based on their chat status. Values allowed are AVAILABLE, DISABLED, NOT_CREATED, and ${UNAVAILABLE}. ${UNAVAILABLE} refers to departments which are not available for chat.

GET /api/v1/departments

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
GetDepartmentsFilter filter = new GetDepartmentsFilter.Builder().setChatStatus(chatStatus).build();
List<Department> response = department.getDepartments( from, limit, filter );

Response Example

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

List agents in department

This API lists the agents in a department.

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the agents must be listed

limit

integer

optional,
range : 0-200

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

status

string

optional,
max chars : 100

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

isLightAgent

boolean

optional

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

isConfirmed

boolean

optional

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

searchStr

string

optional,
max chars : 100

String to search for agents by first name, last name, or email ID. The string must contain at least one character. Three search methods are supported: 1) string* - Searches for agents whose first name, last name, or email ID start with the string, 2) *string* - Searches for agents whose first name, last name, or email ID contain the string, 3) string - Searches for agents whose first name, last name, or email ID is an exact match for the string

fieldName

string

optional,
max chars : 100

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

sortOrder

string

optional,
max chars : 100

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL
  • Java

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

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
GetAgentsInDepartmentFilter filter = new GetAgentsInDepartmentFilter.Builder().setFieldName(fieldName).build();
List<Agent> response = department.getAgentsInDepartment( departmentId, from, limit, filter );

Response Example

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

Get department count

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

Query Params

Param Name
Data Type
Description
isEnabled

boolean

optional

Key that filters departments based on their enabled status

GET /api/v1/departments/count

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "count" : 5
}

Get department details by department IDs

This API fetches the details of the departments whose IDs are passed in the API request.

Query Params

Param Name
Data Type
Description
departmentIds

long

required

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

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

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

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

Check for duplicate departments

This API checks if multiple departments have the same name.

Query Params

Param Name
Data Type
Description
departmentName

string

required,
max chars : 150

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

GET /api/v1/departments/checkExists

OAuth Scope

Desk.settings.READ , Desk.basic.READ

Request Example

  • CURL

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

Response Example

{
  "isDepartmentNameExist" : true
}

Add department

This API adds a department to your help desk portal.

Attributes

Param Name
Data Type
Description
name

string

required,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

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

isAssignToTeamEnabled

boolean

optional

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

associatedAgentIds

list

required

IDs of agents associated with the department

POST /api/v1/departments

OAuth Scope

Desk.settings.CREATE , Desk.basic.CREATE

Request Example

  • CURL
  • Java

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

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department departmentObj = new Department();
departmentObj.setName(name);
departmentObj.setDescription(description);
departmentObj.setNameInCustomerPortal(nameInCustomerPortal);
Department response = department.createDepartment( departmentObj );

Response Example

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

Update department

This API updates the details of an existing department.

Attributes

Param Name
Data Type
Description
name

string

optional,
max chars : 150

Name of the department

nameInCustomerPortal

string

optional,
max chars : 150

Display name of the department in the help center

description

string

optional,
max chars : 500

A short description of the department

isVisibleInCustomerPortal

boolean

optional

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

isAssignToTeamEnabled

boolean

optional

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

associatedAgentIds

list

optional

IDs of agents associated with the department

PATCH /api/v1/departments/{department_id}

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL
  • Java

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

DepartmentAPI department = ZDesk.getDepartmentAPIInstance(mailId);
Department departmentObj = new Department();
departmentObj.setNameInCustomerPortal(nameInCustomerPortal);
Department response = department.updateDepartment( departmentId, departmentObj );

Response Example

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

Disable department

This API disables a department in your help desk portal.

Attributes

Param Name
Data Type
Description
agentNewDepartment

Long

required

Agents move to new department ID

emailNewDepartment

Long

optional

Email move to new department ID

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Enable department

This API enables a department in your help desk portal.

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

Response Example

204

Associate agents to department

This API associates agents to a department.

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Dissociate agents from department

This API dissociates agents from a department.

Attributes

Param Name
Data Type
Description
agentIds

list

required

Ids of Agents

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

OAuth Scope

Desk.settings.UPDATE , Desk.basic.UPDATE

Request Example

  • CURL

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

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

Response Example

204

Channels

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

ATTRIBUTES

Attribute Name
Data Type
Description
type

string

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

name

string

Name of the channel

code

string

Unique Identifier Code of the channel

appName

string

Name of the application that handles the channel

photoURL

string

Photo URL of the channel

departmentId

string

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

acceptsReplies

string

Specifies whether the channel accepts replies for tickets or threads

replyConfig

JSONObject

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

mappedIntegration

string

Type of integration, only if the type is INSTANT_MESSAGE

Example

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



Get a Channel

This API gets fetches details of a given channel.

GET /api/v1/channels/{channel_code}?orgId={org_id}

OAuth Scope

Desk.basic.READ

Request Example

  • CURL
  • Java

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

ChannelAPI channel = ZDesk.getChannelAPIInstance(mailId);
Channel response = channel.getChannelByCode( channelCode );

Response Example

{
  "photoURL" : "https://desk.localzoho.com/api/v1/channels/sales_whatsapp_account/photo?orgId=60856948",
  "code" : "SALES_WHATSAPP_ACCOUNT",
  "appName" : "Sales Whatsapp Account",
  "departmentId" : "76389000000006907",
  "name" : "Sales Whatsapp Account",
  "externalId" : "109000000002003",
  "replyConfig" : {
    "updateRecords" : false,
    "acceptsAttachments" : false,
    "contentTypes" : [ "text/plain" ],
    "includeQuotedMessage" : false
  },
  "type" : "INSTANT_MESSAGE",
  "acceptsReplies" : true
}

List configured channels

This API fetches currently installed channels including System, Channel integration and Instant Messaging channels

GET /api/v1/channels

OAuth Scope

Desk.basic.READ

Request Example

  • CURL
  • Java

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

ChannelAPI channel = ZDesk.getChannelAPIInstance(mailId);
List<Channel> response = channel.getChannels( );

Response Example

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

Tickets

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

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ID of the ticket

subject

string

Subject of the ticket

departmentId
see documentation

long

ID of the department to which the ticket belongs

referred object

ID of the contact who raised the ticket. If a value is not available for this key, make sure to include the contact JSON object. If neither attribute is available, an error message regarding the unavailability of the contactId message is returned.

Contact

Details of the contact who raised the ticket. This object is used for automatically creating a contact when a ticket is received. If the email ID of the contact already exists in your portal, the corresponding contactId is used for creating the ticket. Else, a contact is first created and the contactId of the new contact is mapped to the ticket. The user’s profile and field permissions are considered in the contact creation process. Either the lastName or the email attribute must be present in the object.

productId

referred object

ID of the product to which the ticket is mapped

list

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

email

string

Email ID in the ticket

phone

string

Phone number in the ticket

description

string

Description in the ticket

status

string

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

statusType

string

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

assigneeId

long

ID of agent to whom the ticket is assigned

category

string

Category of the ticket

subCategory

string

Subcategory of the ticket

resolution

string

Resolution notes recorded in the ticket

dueDate

timestamp

Due date for resolving the ticket

priority

string

Priority of the ticket

language

string

Language preference to set for the ticket

responseDueDate

string

Date on or before which a response must be sent for the ticket

channel

string

Channel through which the ticket originated.

channelCode

string

Code of the ticket's source channel

object

Details of the ticket source from channel

classification

string

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

customFields
deprecated

JSONObject

Custom fields in the ticket

JSONObject

Custom fields in the ticket

webUrl

string

URL to access the resource

createdTime

timestamp

Time of creating the ticket

modifiedTime

timestamp

Time of modifying the ticket

timeEntryCount

integer

Number of time entries recorded in the ticket

approvalCount

integer

Number of approvals associated with the ticket

commentCount

integer

Number of comments in the ticket

attachmentCount

integer

Number of attachments in the ticket

taskCount

integer

Number of tasks associated with the ticket

threadCount

integer

Number of threads associated in the ticket

isDeleted

boolean

Key that returns if the ticket is deleted or not

isTrashed

boolean

Field that denotes whether the ticket is in trash

Product

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

closedTime

timestamp

Time of closing the ticket

ticketNumber

integer

Index/Serial number of the ticket

customerResponseTime

timestamp

Time of receiving customer response

isRead

boolean

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

object

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

teamId

long

ID of the team assigned to resolve the ticket

isFollowing

boolean

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

department

object

Details of the department to which the ticket belongs

object

Details of the team assigned to resolve the ticket

channelRelatedInfo

object

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

list

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

list

Comma-separated array of skill IDs to be mapped with a ticket. The order of IDs (with the first ID given the highest priority) will determine how assignments are calculated.

Example

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



Get a ticket

This API fetches a single ticket from your helpdesk.

Query Params

Param Name
Data Type
Description

string

optional,
max chars : 100

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

GET /api/v1/tickets/{ticket_id}

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL
  • Java

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

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
Ticket response = ticket.getTicket( ticketId, include );

Response Example

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

List all tickets

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

Query Params

Param Name
Data Type
Description
from

integer

optional

Index number, starting from which the tickets must be fetched

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

optional

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

optional

Departments from which the tickets need to be queried

long

optional

ID of the view to apply while fetching the resources

assignee

string

optional,
max chars : 100

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

channel

string

optional,
max chars : 100

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

status

string

optional,
max chars : 100

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

sortBy

string

optional,
max chars : 100

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

receivedInDays

integer

optional

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

string

optional,
max chars : 100

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.

fields

string

optional,
max chars : 100

Key that returns the values of mentioned fields (both pre-defined and custom) in your portal. All field types except multi-text are supported. Standard, non-editable fields are supported too. These fields include: statusType, webUrl, layoutId. Maximum of 30 fields is supported as comma separated values.

priority

string

optional,
max chars : 100

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

GET /api/v1/tickets

OAuth Scope

Desk.tickets.READ

Request Example

  • CURL
  • Java

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

TicketAPI ticket = ZDesk.getTicketAPIInstance(mailId);
GetTicketsFilter filter = new GetTicketsFilter.Builder().setDepartmentId(departmentId).build();
List<Ticket> response = ticket.getTickets( from, limit, sortBy, isAscending, include, filter );

Response Example

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

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

optional

Index number, starting from which the tickets must be listed

limit

integer

optional,
range : 1-100

Number of tickets to fetch

departmentId
see documentation

long

optional

ID of the department from which the tickets must be fetched

assignee

string

optional,
max chars : 100

assignee - Key that fil