Desk API Documentation

Introduction

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


API Root Endpoint

https://desk.zoho.com/api/v1

Getting Started

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

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

Example

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

Authentication

All Zoho Desk APIs need an authtoken for authentication.

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

  1. Browser method
  2. API method

Browser Method

Obtaining an authtoken using a browser is a simple task. Login to your Zoho Account and visit the following URL.


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

API Method

Submit an HTTP POST request to the following URL.


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


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


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


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


Parameter Description
SCOPE ZohoSupport/supportapi
EMAIL_ID Your Zoho ID or Email ID
PASSWORD Your Zoho password or your TFA*

* To know more about TFA and creating application password, click here.

Points To Note

  • You can manage (regenerate or delete) the active authtokens created for different Zoho Services, in this link.
  • Authtokens are not deleted unless you delete them from the Zoho Accounts page. You do not need to create multiple authtokens to send out requests.
  • Authtokens carry important information about your identity. Therefore, make sure to keep them secure and secret.
  • You cannot obtain an authtoken via the Zoho Accounts API if you login to Zoho Desk with your Google, Yahoo, or other third-party accounts.

Sample Success Response

# #Mon Jul 25 11:55:51 IST 2016
AUTHTOKEN = cb3ba8197c840d0d61f2398cdb5b6d95
RESULT=TRUE

Sample Error Response

# #Mon Jul 25 11:55:51 IST 2016
CAUSE=INVALID_API_AUTHTOKEN_SCOPE,
RESULT=FALSE

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-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

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-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

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 found
400 Bad request
401 Unauthorized (Invalid authtoken)
403 Forbidden (Unauthorised access)
404 URL not found
405 Method not allowed (Method called is not supported for the API invoked)
500 Internal error

Request Example

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


Response Example

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8


{

"message": "Error while Processing Request."

}

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.

Organizations

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

ATTRIBUTES

Attribute Name
Data Type
Description
companyName

string

Required

Actual company name of the organization/business

organizationName

string

Required

Portal name of the organization as it appears in Zoho Desk , it contains lower case letters and numbers only

phoneNumber

string

Required

Phone number of the organization

id

long

ReadOnly

Unique ID of the Organization

isDefault

boolean

ReadOnly

Field that returns if the organization is the default organization of a user

isAdminInOrg

boolean

ReadOnly

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

portalURL

string

ReadOnly

URL of the organization

logoURL

string

ReadOnly

URL of the organization's logo image file

Example

{ "isDefault" : false, "phoneNumber" : "9884358080", "organizationName" : "zohocorp", "companyName" : "zohoDesk", "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do", "id" : 3981311, "logoURL" : "http://localimg.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true }



Get an Organization

This API fetches the details of an organization from your helpdesk.

GET /api/v1/organizations/{organization_Id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "isDefault" : false,
  "phoneNumber" : "9884358080",
  "organizationName" : "zohocorp",
  "companyName" : "zohoDesk",
  "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do",
  "id" : 3981311,
  "logoURL" : "http://localimg.zohostatic.com/support/1284527/images/portalLogo.png",
  "isAdminInOrg" : true
}

Get all Organizations

This API lists all organizations to which the current user belongs

GET /api/v1/organizations

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/organizations
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "isDefault" : "false",
    "phoneNumber" : "9884358081",
    "organizationName" : "zohocorp",
    "companyName" : "zohoDesk",
    "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do",
    "id" : "3981311",
    "logoURL" : "http://localimg.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true
  }, {
    "isDefault" : "true",
    "phoneNumber" : "9884358080",
    "organizationName" : "zohotech",
    "companyName" : "zohoCrmPlus",
    "portalURL" : "http://desk.zoho.com/support/zohotech/ShowHomePage.do",
    "id" : "3981312",
    "logoURL" : "http://localimg.zohostatic.com/support/1284527/images/portalLogo.png",
    "isAdminInOrg" : true
  } ]
}

Tickets

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

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

Id of the ticket

subject

string

Required

Ticket subject

departmentId
see documentation

long

Required

Department to which the ticket belongs

referred object

Required

Contact who raised the ticket

productId

referred object

Optional

Product to which the ticket is mapped

list

Optional

list of attachments ,refer uploads api to create attachment

email

string

Optional

Email ID in the ticket

phone

string

Optional

Phone number in the ticket

description

string

Optional

Ticket description

status

string

Optional

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

statusType

string

ReadOnly

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

assigneeId

long

Optional

ID of agent to whom the ticket is assigned

category

string

Optional

Ticket category

subCategory

string

Optional

Ticket subcategory

resolution

string

Optional

Resolution status of the ticket

dueDate

timestamp

Optional

Ticket dueDate

priority

string

Optional

Ticket priority

channel

string

Optional

Channel through which the ticket originated.The channels supported are EMAIL, TWITTER, TWITTER_DM, FACEBOOK, WEB, ONLINE_CHAT, OFFLINE_CHAT, FORUMS, TWILIO, ZTI, CUSTOMERPORTAL, FEEDBACK, FEEDBACK_WIDGET

classification

string

Optional

Ticket classification

customFields

list

Optional

Custom fields in the ticket

webUrl

string

Optional

URL to access the resource

createdTime

timestamp

ReadOnly

Time of ticket creation

modifiedTime

timestamp

ReadOnly

Time of ticket modification

timeEntryCount

integer

ReadOnly

No. of time entries associated with the ticket

approvalCount

integer

ReadOnly

No. of approvals associated with the ticket

commentCount

integer

ReadOnly

No. of comments in the ticket

attachmentCount

integer

ReadOnly

No. of attachments in the ticket

taskCount

integer

ReadOnly

No. of tasks associated with the ticket

threadCount

integer

ReadOnly

No. of threads associated with the ticket

product

Product

ReadOnly

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

closedTime

timestamp

ReadOnly

Time of ticket closure

ticketNumber

integer

ReadOnly

Ticket Number

contact

Contact

ReadOnly

Contact who raised the ticket. You obtain this information using the include:contact query param

customerResponseTime

timestamp

ReadOnly

Time of customer response

sharedDepartments

list

Optional

Department details to which a ticket has been shared

Example

{ "modifiedTime" : "2016-06-21T13:16:14.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Welcome to Zoho Support. You've got a sample Request!", "customFields" : { "MyDateTime" : null, "MyInteger" : null, "MyPickList12" : null, "12121" : null, "MyEmail" : null, "MyText" : null, "mypercent12" : "0.0", "Date" : null, "qqweq" : "false", "MyPhone" : null, "Multiselct" : "mano", "datetime" : null, "MyDate" : null, "qqq1" : null, "121212" : null, "MyUrl" : null, "MyPickList" : "asdadada", "MyPercent" : "0.0", "myfield" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hello!<br /><br />I am glad to assist you deliver more happiness in every support request. You are receiving this request, since I emailed you at support@manojportal.zohosupport.com.<br />Now that you had received your first request, did you notice that it has been assigned to you?<br /><br /><ul><li>You can respond to me by hitting &#39;reply&#39; right away, or</li><li>Give me a call on the number displayed under contact area from the right stack.</li></ul><br />Remember, the request is due in 48 hours from now! So ensure you reply and close this request sooner, since every ticking minute will increase the average response time of your helpdesk.<br />Whatever action you perform, be rest assured that you can always track them under the request&#39;s history. <br /><br />Thank you for choosing Zoho Support,<br />Lawrence<br />Customer Support Executive", "resolution" : null, "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "contact" : { "lastName" : "Lawrence", "firstName" : null, "phone" : "1 888 900 9646", "id" : "1892000000042032", "type" : null, "email" : "support@zohosupport.com", "account" : { "website" : null, "accountName" : "qeqwewe", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "email" : "as@qwer.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "product" : null, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "1", "category" : "manoj", "status" : "Open" }



Get a ticket

This API fetches a single ticket from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : contacts, products. You can inlcude both by separating them with a comma in the query param.

GET /api/v1/tickets/{ticket_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237?include=contacts,products
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "modifiedTime" : "2016-06-21T13:16:14.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Welcome to Zoho Support. You've got a sample Request!",
  "customFields" : {
    "MyDateTime" : null,
    "MyInteger" : null,
    "MyPickList12" : null,
    "12121" : null,
    "MyEmail" : null,
    "MyText" : null,
    "mypercent12" : "0.0",
    "Date" : null,
    "qqweq" : "false",
    "MyPhone" : null,
    "Multiselct" : "mano",
    "datetime" : null,
    "MyDate" : null,
    "qqq1" : null,
    "121212" : null,
    "MyUrl" : null,
    "MyPickList" : "asdadada",
    "MyPercent" : "0.0",
    "myfield" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "Hello!<br /><br />I am glad to assist you deliver more happiness in every support request. You are receiving this request, since I emailed you at support@manojportal.zohosupport.com.<br />Now that you had received your first request, did you notice that it has been assigned to you?<br /><br /><ul><li>You can respond to me by hitting &#39;reply&#39; right away, or</li><li>Give me a call on the number displayed under contact area from the right stack.</li></ul><br />Remember, the request is due in 48 hours from now! So ensure you reply and close this request sooner, since every ticking minute will increase the average response time of your helpdesk.<br />Whatever action you perform, be rest assured that you can always track them under the request&#39;s history. <br /><br />Thank you for choosing Zoho Support,<br />Lawrence<br />Customer Support Executive",
  "resolution" : null,
  "closedTime" : null,
  "approvalCount" : "1",
  "timeEntryCount" : "3",
  "contact" : {
    "lastName" : "Lawrence",
    "firstName" : null,
    "phone" : "1 888 900 9646",
    "id" : "1892000000042032",
    "type" : null,
    "email" : "support@zohosupport.com",
    "account" : {
      "website" : null,
      "accountName" : "qeqwewe",
      "id" : "1892000000975382"
    }
  },
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "email" : "as@qwer.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "product" : null,
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "category" : "manoj",
  "status" : "Open"
}

List all tickets

This API lists all tickets in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

No. of tickets to fetch

departmentId
see documentation

long

Department from which the tickets need to be queried

assignee

string

Filter by ticket assignee. Values allowed are Unassigned or valid asigneeIds. You can include multiple values by separating them with a comma

channel

string

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

status

string

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

sortBy

string

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

receivedInDays

integer

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

string

Allowed Values are : contacts, products. You can include both by separating them with a comma in the query param.

GET /api/v1/tickets

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets?include=contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "ticketNumber" : "101",
    "customerResponseTime" : "2013-11-04T11:21:07.912Z",
    "statusType" : "Open",
    "productId" : null,
    "contactId" : "1892000000042032",
    "subject" : "Welcome to Zoho Support. You've got a sample Request!",
    "dueDate" : "2016-06-21T16:16:16.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Email",
    "threadCount" : "121",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "closedTime" : null,
    "commentCount" : "1",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
    "contact" : {
      "firstName" : "",
      "lastName" : "Lawrence",
      "phone" : "1 888 900 9646",
      "id" : "1892000000042032",
      "type" : null,
      "email" : "support@zohosupport.com",
      "account" : {
        "website" : null,
        "accountName" : "qeqwewe",
        "id" : "1892000000975382"
      }
    },
    "createdTime" : "2013-11-04T11:21:07.000Z",
    "id" : "1892000000042034",
    "email" : "example@example.com",
    "status" : "On Hold"
  }, {
    "ticketNumber" : "176",
    "customerResponseTime" : "2014-03-22T05:05:08.471Z",
    "statusType" : "Closed",
    "productId" : null,
    "contactId" : "1892000000045028",
    "subject" : "from forum",
    "dueDate" : "2016-06-01T14:04:07.000Z",
    "departmentId" : "1892000000006907",
    "channel" : "Forums",
    "threadCount" : "72",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "closedTime" : null,
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38",
    "contact" : {
      "firstName" : "",
      "lastName" : "as",
      "phone" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "manojkumar.s+4444@zohocorp.com",
      "account" : {
        "website" : "qwe.com",
        "accountName" : "Man_Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-06T09:49:50.000Z",
    "id" : "1892000000094004",
    "email" : "example@example.com",
    "status" : "Closed"
  }, {
    "ticketNumber" : "189",
    "customerResponseTime" : "2014-03-21T09:13:36.713Z",
    "statusType" : "Open",
    "productId" : null,
    "contactId" : "1892000000045028",
    "subject" : "qwqw",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "threadCount" : "1",
    "priority" : null,
    "assigneeId" : "1892000000042001",
    "closedTime" : null,
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330f12bc1247d9ebddaeb9d937cbad750b0284bc7232b3a",
    "contact" : {
      "firstName" : "",
      "lastName" : "as",
      "phone" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "manojkumar.s+4444@zohocorp.com",
      "account" : {
        "website" : "qwe.com",
        "accountName" : "Man_Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:13:36.000Z",
    "id" : "1892000000137001",
    "email" : "example@example.com",
    "status" : "Open"
  }, {
    "ticketNumber" : "191",
    "customerResponseTime" : "2014-03-21T10:54:21.802Z",
    "statusType" : "Open",
    "productId" : null,
    "contactId" : "1892000000045028",
    "subject" : "TB Action 222",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Chat",
    "threadCount" : "19",
    "priority" : "-None-",
    "assigneeId" : "1892000000042001",
    "closedTime" : null,
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38",
    "contact" : {
      "firstName" : "",
      "lastName" : "as",
      "phone" : null,
      "id" : "1892000000045028",
      "type" : null,
      "email" : "manojkumar.s+4444@zohocorp.com",
      "account" : {
        "website" : "qwe.com",
        "accountName" : "Man_Account",
        "id" : "1892000000980421"
      }
    },
    "createdTime" : "2014-03-21T09:16:03.000Z",
    "id" : "1892000000137057",
    "email" : "example@example.com",
    "status" : "Open"
  }, {
    "ticketNumber" : "195",
    "customerResponseTime" : "2014-03-24T13:49:20.241Z",
    "statusType" : "Open",
    "productId" : null,
    "contactId" : "1892000000093203",
    "subject" : "manoj",
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "channel" : "Facebook",
    "threadCount" : "6",
    "priority" : null,
    "assigneeId" : null,
    "closedTime" : "2014-03-24T13:51:18.000Z",
    "commentCount" : "0",
    "phone" : null,
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d9bc650b028dd03b38",
    "contact" : {
      "firstName" : "",
      "lastName" : "अजय कुमार",
      "phone" : null,
      "id" : "1892000000093203",
      "type" : null,
      "email" : null,
      "account" : {
      }
    },
    "createdTime" : "2014-03-24T13:49:20.000Z",
    "id" : "1892000000143237",
    "email" : "example@example.com",
    "status" : "Open"
  } ]
}

Create a ticket

This API creates a ticket in your helpdesk.

POST /api/v1/tickets

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "subCategory" : "Sub General", "productId" : "", "contactId" : "1892000000042032", "subject" : "Welcome to Zoho Support. You've got a sample Request!", "customFields" : { "MyDateTime" : "", "datetime" : "", "MyInteger" : "", "MyPickList" : "asdadada", "Date" : "", "qqweq" : "false" }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hai This is Description", "priority" : "High", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "manoj", "email" : "example@example.com", "status" : "Open" }'

Response Example

{
  "modifiedTime" : "2016-06-21T12:50:04.000Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Welcome to Zoho Support. You've got a sample Request!",
  "customFields" : {
    "MyDateTime" : null,
    "MyInteger" : null,
    "MyPickList12" : null,
    "12121" : null,
    "MyEmail" : null,
    "MyText" : null,
    "mypercent12" : null,
    "Date" : null,
    "qqweq" : "false",
    "MyPhone" : null,
    "Multiselct" : null,
    "datetime" : null,
    "MyDate" : null,
    "qqq1" : null,
    "121212" : null,
    "MyUrl" : null,
    "MyPickList" : "asdadada",
    "MyPercent" : null,
    "myfield" : null
  },
  "dueDate" : "2016-06-21T18:50:04.573Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "Hai This is description",
  "resolution" : null,
  "closedTime" : null,
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "example@example.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "category" : "manoj",
  "status" : "Open"
}

Update a ticket

This API updates an existing ticket.

PATCH /api/v1/tickets/{ticket_id}

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/3000000024409
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "subCategory" : "Sub General", "productId" : "", "contactId" : "1892000000042032", "subject" : "Welcome to Zoho Support. You've got a sample Request!", "customFields" : { "MyDateTime" : "", "datetime" : "", "MyInteger" : "123", "MyPickList" : "example data", "Date" : "", "qqweq" : "false" }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Phone", "description" : "Sample Ticket", "priority" : "Low", "classification" : "", "assigneeId" : "1892000000056007", "phone" : "1 888 900 9646", "category" : "manoj", "email" : "example@example.com", "status" : "Open" }'

Response Example

{
  "modifiedTime" : "2016-06-21T12:58:09.122Z",
  "ticketNumber" : "773",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Welcome to Zoho Support. You've got a sample Request!",
  "customFields" : {
    "MyDateTime" : null,
    "MyInteger" : "123",
    "MyPickList12" : null,
    "12121" : null,
    "MyEmail" : null,
    "MyText" : null,
    "mypercent12" : null,
    "Date" : null,
    "qqweq" : "false",
    "MyPhone" : null,
    "Multiselct" : null,
    "datetime" : null,
    "MyDate" : null,
    "qqq1" : null,
    "121212" : null,
    "MyUrl" : null,
    "MyPickList" : "example data",
    "MyPercent" : null,
    "myfield" : null
  },
  "dueDate" : "2016-06-23T12:58:09.211Z",
  "departmentId" : "1892000000006907",
  "channel" : "Phone",
  "description" : "Sample Ticket",
  "resolution" : null,
  "closedTime" : null,
  "approvalCount" : "0",
  "timeEntryCount" : "0",
  "createdTime" : "2016-06-21T12:50:04.000Z",
  "id" : "1892000001054003",
  "email" : "example@example.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "1",
  "priority" : "Low",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "0",
  "taskCount" : "0",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "0",
  "category" : "manoj",
  "status" : "Open"
}

Merge two tickets

This API merges two different tickets.

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000008749/merge
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

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

Response Example

{
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Welcome to Zoho Support. You've got a sample Request!",
  "customFields" : {
    "MyDateTime" : null,
    "MyInteger" : null,
    "MyPickList12" : null,
    "12121" : null,
    "MyEmail" : null,
    "MyText" : null,
    "mypercent12" : "0.0",
    "Date" : null,
    "qqweq" : "false",
    "MyPhone" : null,
    "Multiselct" : "mano",
    "datetime" : null,
    "MyDate" : null,
    "qqq1" : null,
    "121212" : null,
    "MyUrl" : null,
    "MyPickList" : "example data",
    "MyPercent" : "0.0",
    "myfield" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "42000000006907",
  "channel" : "Email",
  "description" : "Example data",
  "resolution" : null,
  "closedTime" : null,
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "4000000008749",
  "email" : "example@example.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "42000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "42000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "category" : "manoj",
  "status" : "Open"
}

Move ticket

This API moves a ticket from one department to another.

Query Params

Param Name
Data Type
Description
departmentId
see documentation

long

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

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000093303/move?departmentId=1892000000082069
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Split tickets

This API splits a thread into a ticket.

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000047005/threads/1892000000133023/split
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "modifiedTime" : "2016-06-21T10:16:15.000Z",
  "ticketNumber" : "101",
  "subCategory" : "Sub General",
  "statusType" : "Open",
  "subject" : "Welcome to Zoho Support. You've got a sample Request!",
  "customFields" : {
    "MyDateTime" : null,
    "MyInteger" : null,
    "MyPickList12" : null,
    "12121" : null,
    "MyEmail" : null,
    "MyText" : null,
    "mypercent12" : "0.0",
    "Date" : null,
    "qqweq" : "false",
    "MyPhone" : null,
    "Multiselct" : "mano",
    "datetime" : null,
    "MyDate" : null,
    "qqq1" : null,
    "121212" : null,
    "MyUrl" : null,
    "MyPickList" : "example data",
    "MyPercent" : "0.0",
    "myfield" : null
  },
  "dueDate" : "2016-06-21T16:16:16.000Z",
  "departmentId" : "1892000000006907",
  "channel" : "Email",
  "description" : "example ticket",
  "resolution" : null,
  "closedTime" : null,
  "approvalCount" : "0",
  "timeEntryCount" : "3",
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "id" : "1892000000042034",
  "email" : "example@example.com",
  "customerResponseTime" : "2013-11-04T11:21:07.912Z",
  "productId" : null,
  "contactId" : "1892000000042032",
  "threadCount" : "121",
  "priority" : "High",
  "classification" : null,
  "assigneeId" : "1892000000056007",
  "commentCount" : "1",
  "taskCount" : "1",
  "phone" : "1 888 900 9646",
  "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
  "attachmentCount" : "1",
  "category" : "manoj",
  "status" : "Open"
}

Update many tickets

This API updates multiple tickets at once.

POST /api/v1/tickets/updateMany

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

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

Response Example

200

Mark spam

This API marks a ticket as spam.

POST /api/v1/tickets/markSpam

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/markSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

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

Response Example

200

Create a ticket comment

This API adds a comment to a ticket. To include an @mention, follow this format: zsu[@user:{zuid}]zsu.

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "isPublic" : "true", "content" : "zsu[@user:11550965]zsu hai mail sending is not working !!!!" }'

Response Example

{
  "modifiedTime" : null,
  "commentedTime" : "2017-01-24T14:06:58.193Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "content" : "zsu[@user:11550965]zsu hai mail sending is not working !!!!",
  "commenterId" : "4000000008692"
}

Update a ticket comment

This API updates an existing comment. To include an @mention, follow this format: zsu[@user:{zuid}]zsu.

PATCH api/v1/tickets/{ticket_id}/comments/{comment_id}

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "content" : "Edited comment." }'

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.163Z",
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "commenterId" : "4000000008692",
  "content" : "Edited comment."
}

Delete a ticket comment

This API deletes an existing comment.

DELETE api/v1/tickets/{ticket_id}/comments/{comment_id}

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Get a ticket comment

This API fetches a comment from a ticket.

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "modifiedTime" : "2017-01-24T14:12:45.000Z",
  "commentedTime" : "2017-01-24T14:06:58.000Z",
  "isPublic" : true,
  "id" : "4000000529001",
  "commenterId" : "4000000008692",
  "content" : "Edited comment."
}

List all ticket comments

This API lists all comments in a ticket.

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

No. of comments to fetch

sortBy

string

Sort by the commentedTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2017-01-24T14:12:45.000Z",
    "commentedTime" : "2017-01-24T14:06:58.000Z",
    "isPublic" : true,
    "id" : "4000000529001",
    "content" : "Edited comment.",
    "commenterId" : "4000000008692"
  }, {
    "modifiedTime" : null,
    "commentedTime" : "2017-01-24T14:14:37.000Z",
    "isPublic" : false,
    "id" : "4000000529007",
    "content" : "Second Ticket Comment.",
    "commenterId" : "4000000008692"
  } ]
}

Threads

Threads are conversations that occur between agents and customers. A thread can originate from multiple channels, such as FACEBOOK, TWITTER, EMAIL, TWITTER_DM, WEB, ONLINE_CHAT, OFFLINE_CHAT, FORUMS, TWILIO, ZTI, CUSTOMERPORTAL, FEEDBACK, FEEDBACK_WIDGET.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the thread

channel

string

Required

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

status

string

ReadOnly

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

content

string

Required

Content of the thread

contentType

string

Optional

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

isForward

boolean

Optional

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

inReplyToThreadId

long

Optional

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

list

Optional

List of attachments, applicable only for EMAIL

createdTime

timestamp

ReadOnly

Time of thread creation

direction

string

Optional

Returns whether the thread is incoming or outgoing

twitterProfile

string

ReadOnly

Twitter handle of the contact.

facebookProfile

string

ReadOnly

Facebook profile of the contact.

fromEmailAddress
see documentation

string

Optional

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

to

string

Optional

To ID in the thread, applicable only for EMAIL

cc

string

Optional

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

bcc

string

Optional

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

phoneno

string

ReadOnly

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

responderId

long

ReadOnly

ID of agent who replied to the thread

summary

string

ReadOnly

Summary of the thread

attachments

object

ReadOnly

Attachments in the thread

hasAttach

boolean

Optional

States whether the thread has attachments

list

ReadOnly

Actions available from the present state which will be included based on present status.It is a collection of all actions and each action has a rel,href and method.The respective links and methods to be invoked will be available under the 'href' and 'method' key for each action.

Example

{ "hasAttach" : true, "summary" : "Sample Content", "attachments" : [ { "size" : "1913", "name" : "example3", "id" : "1892000001083005", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "channel" : "FORUMS", "createdTime" : "2014-03-21T08:46:48.248Z", "id" : "1892000000135387", "fromEmailAddress" : "testemail@test.com", "actions" : [ ], "content" : "<body>\n Sample Content\n</body>", "status" : "SUCCESS", "direction" : "in" }



Get a thread

This API fetches a single thread from your helpdesk.

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000135387
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "cc" : "",
  "summary" : "Sent using Zoho Mail",
  "attachments" : [ {
    "size" : "1913",
    "name" : "example3",
    "id" : "1892000001083005",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "bcc" : "",
  "channel" : "EMAIL",
  "isPrivate" : false,
  "content" : "<body>\n <div>\n  <div style=\"font-size: 10.0pt;font-family: Verdana , Arial , Helvetica , sans-serif;\">\n   <br />\n   <br />\n   <div>\n    <p style=\"color: rgb(170,170,170);\">Sent using Zoho Mail</p>\n   </div>\n  </div>\n </div>\n</body>",
  "isForward" : false,
  "hasAttach" : true,
  "createdTime" : "2016-06-02T18:17:55.000Z",
  "to" : "someexample@example.com",
  "id" : "1892000000135387",
  "fromEmailAddress" : "someexample@example.com",
  "actions" : [ ],
  "status" : "SUCCESS",
  "direction" : "in"
}

List all threads

This API lists all threads in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

The from index of the threads

limit

integer

The number of threads in the case to be displayed

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/threads
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "hasAttach" : false,
    "channel" : "FEEDBACK",
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "id" : "1892000000413186",
    "fromEmailAddress" : "Agent1<support@zohosupport.com>",
    "actions" : [ ],
    "status" : "SUCCESS",
    "direction" : "in"
  }, {
    "summary" : "Sample Thread",
    "cc" : "",
    "bcc" : "",
    "attachments" : [ {
      "size" : "1234",
      "name" : "atach.png",
      "id" : "1892000000042043"
    } ],
    "channel" : "EMAIL",
    "isPrivate" : false,
    "isForward" : false,
    "responderId" : "1892000000042001",
    "createdTime" : "2016-05-25T10:06:09.686Z",
    "id" : "1892000001004072",
    "to" : "example2@example.com",
    "fromEmailAddress" : "example@example.com",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/resendFailedThread?threadId=1892000001083008"
    } ],
    "status" : "FAILED",
    "direction" : "out"
  }, {
    "hasAttach" : false,
    "summary" : "This is my Sample FB Post edited",
    "responderId" : "2150000000043591",
    "channel" : "FACEBOOK",
    "createdTime" : "2016-07-25T10:04:43.739Z",
    "id" : "2150000002498038",
    "actions" : [ {
      "method" : "POST",
      "rel" : "send",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
    }, {
      "method" : "DELETE",
      "rel" : "delete",
      "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
    } ],
    "status" : "DRAFT",
    "facebookProfile" : "Ashok Zoho",
    "direction" : "out"
  }, {
    "hasAttach" : false,
    "channel" : "FEEDBACK",
    "createdTime" : "2015-03-25T13:40:23.031Z",
    "id" : "1892000000413189",
    "fromEmailAddress" : "Agent1<support@zohosupport.com>",
    "actions" : [ ],
    "status" : "PENDING",
    "direction" : "in"
  } ]
}

Send Email Reply

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

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "channel" : "EMAIL", "to" : "example2@example.com", "isPrivate" : true, "fromEmailAddress" : "example@example.com", "contentType" : "plainText", "content" : "Sample Thread", "isForward" : "true", "uploads" : [ "1312123141313" ] }'

Response Example

{
  "summary" : "Sample Thread",
  "cc" : "",
  "bcc" : "",
  "attachments" : [ {
    "size" : "1234",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "channel" : "EMAIL",
  "isPrivate" : true,
  "content" : "Sample Thread",
  "isForward" : true,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "example2@example.com",
  "fromEmailAddress" : "example@example.com",
  "actions" : [ ],
  "status" : "PENDING",
  "direction" : "out"
}

Draft Email Reply

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

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "channel" : "EMAIL", "to" : "example2@example.com", "fromEmailAddress" : "example@example.com", "contentType" : "plainText", "content" : "Sample Thread", "isForward" : "true", "uploads" : [ "1312123141313" ] }'

Response Example

{
  "summary" : "Sample Thread",
  "cc" : "",
  "bcc" : "",
  "attachments" : [ {
    "size" : "1234",
    "name" : "atach.png",
    "id" : "1892000000042043",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content"
  } ],
  "channel" : "EMAIL",
  "content" : "Sample Thread",
  "isForward" : false,
  "hasAttach" : true,
  "responderId" : "1892000000042001",
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "example2@example.com",
  "fromEmailAddress" : "example@example.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "status" : "DRAFT",
  "direction" : "out"
}

Update Draft

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

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

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "channel" : "EMAIL", "to" : "example2@example.com", "fromEmailAddress" : "support@portal.zohosupport.com", "contentType" : "plainText", "content" : "Sample Thread" }'

Response Example

{
  "summary" : "Hello Thread summary",
  "cc" : "",
  "bcc" : "",
  "channel" : "EMAIL",
  "content" : "Hello Sample Thread",
  "isForward" : false,
  "hasAttach" : false,
  "responderId" : "1892000000042001",
  "createdTime" : "2016-05-25T10:06:09.686Z",
  "id" : "1892000001004072",
  "to" : "example2@example.com",
  "fromEmailAddress" : "support@portal.zohosupport.com",
  "actions" : [ {
    "method" : "POST",
    "rel" : "send",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072"
  }, {
    "method" : "DELETE",
    "rel" : "delete",
    "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072"
  } ],
  "status" : "DRAFT",
  "direction" : "out"
}

Delete an attachment

This API deletes the draft attachment in a thread.

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

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Ticket Attachments

Ticket attachments are the files you attach to a ticket to aid quick resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the attachment

creatorId

long

ReadOnly

ID of user who added the attachment

createdTime

timestamp

ReadOnly

Time of file attachment

name

string

ReadOnly

Name of the attachment

isPublic

boolean

ReadOnly

Visibility setting of the attachment

size

long

ReadOnly

Size of the attachment

Example

{ "size" : "1079", "creatorId" : "1892000000047001", "name" : "095342.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : true, "id" : "1892000000047041" }



List all attachments

This API lists all attachments in a ticket.

Query Params

Param Name
Data Type
Description
sortBy

string

Sort by the createdTime attribute. The default sorting order is ascending. A - prefix denotes descending order of sorting.

from

integer

from Index

range

integer

the number of attachments to be displayed

isPublic

Boolean

To get the Public or Private or All Attachment

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

Request Example

$ curl -X GET https://support.zoho.com/api/v1/tickets/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "size" : "1079",
    "creatorId" : "1892000000047001",
    "name" : "095342.txt",
    "createdTime" : "2013-11-06T10:25:03.000Z",
    "isPublic" : true,
    "id" : "1892000000047041"
  }, {
    "size" : "135222",
    "creatorId" : "1892000000047001",
    "name" : "bsnl-feb14.pdf",
    "createdTime" : "2014-03-05T06:16:15.000Z",
    "isPublic" : true,
    "id" : "1892000000089041"
  }, {
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "FieldUtil.java",
    "createdTime" : "2016-06-21T10:15:34.000Z",
    "isPublic" : false,
    "id" : "1892000001052021"
  }, {
    "size" : "97951",
    "creatorId" : "1892000000042001",
    "name" : "FieldUtil.java",
    "createdTime" : "2016-06-21T10:15:49.000Z",
    "isPublic" : false,
    "id" : "1892000001052025"
  } ]
}

Download an attachment

This API displays the content of the attachment.

Query Params

Param Name
Data Type
Description
inline

boolean

Display content inline

GET api/v1/tickets/{ticket_id}/attachment/{attachment_id}/content

Request Example

$ curl -X GET https://support.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001008043/content
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Create an attachment

This API attaches a file to a ticket.

File Params

file

Content-Type:multipart/form-data

File to attach to the ticket

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

Request Example

$ curl -X POST https://support.zoho.com/api/v1/tickets/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "size" : "32",
  "creatorId" : "1892000000042001",
  "name" : "example.txt",
  "createdTime" : "2016-05-30T08:32:51.338Z",
  "isPublic" : false,
  "id" : "1892000001010001"
}

Update an attachment

This API updates an existing attachment.

PATCH api/v1/tickets/{ticket_id}/attachments/{attachment_id}

Request Example

$ curl -X PATCH https://support.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "isPublic" : true }'

Response Example

200

Delete an attachment

This API deletes an attachment from a ticket.

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

Request Example

$ curl -X DELETE https://support.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Ticket TimeEntry

Ticket Time Entry refers to the time taken by an agent to resolve a ticket.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

Id of the timeEntry

ticketId

long

ReadOnly

Id of the ticket

requestChargeType

string

Optional

Values available are Customer Service Product Consultation, Upgrade Request and Service and Maintenance

ownerId

string

Optional

Owner of time entry

executedTime

timestamp

Optional

Execution time

hoursSpent

integer

Optional

Hours spent on the ticket

minutesSpent

integer

Optional

Minutes spent on the ticket

secondsSpent

integer

Optional

Seconds spent on the ticket

agentCostPerHour

double

Optional

Cost of an agent per hour

additionalCost

double

Optional

Additional cost incurred

totalCost

double

ReadOnly

Total cost incurred

description

string

Optional

Description of the time entry

customFields

list

Optional

Custom Fields in the time entry

createdTime

timestamp

ReadOnly

Time of creating the ticket time entry

modifiedTime

timestamp

ReadOnly

Time of modifying the ticket time entry

createdBy

string

ReadOnly

User who created the Time Entry

modifiedBy

string

ReadOnly

User who modified the Time Entry

Example

{ "secondsSpent" : "0", "executedTime" : null, "customFields" : { }, "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : null, "createdTime" : "2016-05-30T09:58:08.149Z", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }



Get a Ticket Time Entry

This API fetches a time entry from your help desk

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000033010
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "secondsSpent" : "21",
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "createdTime" : "2016-06-16T07:24:44.000Z",
  "id" : "4000000033001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

List Ticket Time Entries

This API fetches all time entries associated with a ticket

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

Number of time entries to be fetched

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry?from=0&limit=10
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "secondsSpent" : "21",
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time1"
    },
    "minutesSpent" : "23",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:24:44.000Z",
    "id" : "4000000033001",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  }, {
    "secondsSpent" : "21",
    "executedTime" : "2016-06-24T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time2"
    },
    "minutesSpent" : "34",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "10.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000012090",
    "createdTime" : "2016-06-16T07:46:39.000Z",
    "id" : "4000000033006",
    "requestChargeType" : "Product Consultation",
    "additionalCost" : "10.0",
    "totalCost" : "45.72"
  }, {
    "secondsSpent" : "22",
    "executedTime" : "2016-06-13T19:30:00.000Z",
    "customFields" : {
      "timeEntryName" : "time3"
    },
    "minutesSpent" : "22",
    "creatorId" : "4000000008692",
    "agentCostPerHour" : "20.0",
    "description" : "Time Entry description",
    "hoursSpent" : "32",
    "ownerId" : "4000000008692",
    "createdTime" : "2016-06-16T07:49:52.000Z",
    "id" : "4000000033011",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "657.46"
  } ]
}

Add a Ticket Time Entry

This API creates a time entry in your help desk

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

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "secondsSpent" : "21", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time2" }, "minutesSpent" : "23", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }'

Response Example

{
  "secondsSpent" : "21",
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time2"
  },
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "createdTime" : "2016-06-21T05:52:00.828Z",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Update a Ticket Time Entry

This API updates an existing time entry

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

Request Example

$ curl -X PUT https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "description" : "Time Entry description", "requestChargeType" : "Customer Service" }'

Response Example

{
  "secondsSpent" : "21",
  "executedTime" : "2016-06-22T20:30:00.000Z",
  "customFields" : {
    "timeEntryName" : "time1"
  },
  "minutesSpent" : "23",
  "creatorId" : "4000000008692",
  "agentCostPerHour" : "3.0",
  "description" : "Time Entry description",
  "hoursSpent" : "3",
  "ownerId" : "4000000008692",
  "createdTime" : "2016-06-21T05:52:00.000Z",
  "id" : "4000000045001",
  "requestChargeType" : "Customer Service",
  "additionalCost" : "10.0",
  "totalCost" : "20.17"
}

Delete a Ticket Time Entry

This API deletes a time entry from your help desk

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

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Contacts

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

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the contact

customFields

object

Optional

User-defined fields

lastName

string

Required

Last name of the contact

firstName

string

Optional

First name of the contact

facebook

string

Optional

Facebook ID of the contact

twitter

string

Optional

Twitter ID of the contact

secondaryEmail

string

Optional

Secondary email ID of the contact

email

string

Optional

Email ID of the contact

phone

string

Optional

Phone number of the contact

mobile

string

Optional

Mobile number of the contact

city

string

Optional

Contact's city of residence

country

string

Optional

Contact's country of residence

state

string

Optional

Contact's state of residence

street

string

Optional

Contact's address

zip

string

Optional

Zip code

description

string

Optional

Contact description

title

string

Optional

Contact title

type

string

Optional

Contact type

ownerId

long

Optional

Contact owner

long

Optional

Account to which the contact is mapped

zohoCRMContact

object

ReadOnly

Contact details fetched from Zoho CRM

customerHappiness

object

ReadOnly

Average customer happiness rating of the contact

createdTime

timestamp

ReadOnly

Time of contact creation

modifiedTime

timestamp

ReadOnly

Time of contact modification

Example

{ "zip" : null, "lastName" : "_ 16_2_2015_20_19_5_1424098145192", "modifiedTime" : "2015-03-02T14:49:32.000Z", "country" : null, "secondaryEmail" : null, "city" : null, "customFields" : { "text custom _ 8_9_2015_10_28_39_1441688319934" : null, "text custom _ 29_9_2015_21_15_0_1443541500315" : null, "text custom _ 9_7_2015_20_41_5_1436454665096" : null, "text custom _ 8_7_2015_13_34_50_1436342690695" : null }, "facebook" : null, "mobile" : null, "description" : null, "ownerId" : "3263000000057001", "type" : null, "title" : null, "accountId" : null, "firstName" : "karthick", "twitter" : null, "phone" : "123", "street" : null, "createdTime" : "2015-02-16T14:46:24.000Z", "zohoCRMContact" : { "id" : "5000000014010", "type" : "potentials" }, "state" : null, "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "id" : "3263000000064001", "email" : "meikandamoorthi.n+16_2_2015_20_20_26_1424098226529@zohocorp.com" }



Get a contact

This API fetches a single contact from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : accounts

GET /api/v1/contacts/{contact_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000000042032
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "zip" : null,
  "lastName" : "Lawrence",
  "modifiedTime" : "2016-05-04T09:57:17.000Z",
  "country" : null,
  "secondaryEmail" : null,
  "city" : null,
  "customFields" : {
    "Mypercent" : "0.0",
    "MyDatetime" : null,
    "Mydecimal" : "0.0",
    "MyInt" : null,
    "Mydate" : null,
    "MyBox" : "false",
    "MyText" : null,
    "MultiselectPickList" : null
  },
  "facebook" : null,
  "mobile" : null,
  "description" : null,
  "ownerId" : "1892000000042001",
  "type" : null,
  "title" : null,
  "accountId" : "1892000000975382",
  "firstName" : null,
  "twitter" : null,
  "phone" : "1 888 900 9646",
  "street" : null,
  "createdTime" : "2013-11-04T11:21:07.000Z",
  "zohoCRMContact" : {
    "id" : "5000000014010",
    "type" : "contacts_leads"
  },
  "customerHappiness" : {
    "badPercentage" : "22",
    "okPercentage" : "31",
    "goodPercentage" : "47"
  },
  "state" : null,
  "id" : "1892000000042032",
  "email" : "support@zohosupport.com"
}

List all contacts

This API lists all contacts in your helpdesk.

Query Params

Param Name
Data Type
Description

list

Allowed values are : accounts

from

integer

From index

limit

string

No. of contacts to fetch

sortBy

string

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

GET /api/v1/contacts

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "lastName" : "User",
    "accountId" : "1892000000091433",
    "firstName" : "Support",
    "secondaryEmail" : null,
    "phone" : "555555",
    "zohoCRMContact" : null,
    "id" : "1892000000772003",
    "customerHappiness" : {
      "badPercentage" : "0",
      "okPercentage" : "0",
      "goodPercentage" : "0"
    },
    "ownerId" : null,
    "type" : null,
    "email" : "su@example.com"
  }, {
    "lastName" : "Agent",
    "accountId" : "1892000000052077",
    "firstName" : null,
    "secondaryEmail" : null,
    "phone" : null,
    "zohoCRMContact" : {
      "id" : "1892000000772030",
      "type" : "contacts_leads"
    },
    "id" : "1892000000772001",
    "customerHappiness" : {
      "badPercentage" : "22",
      "okPercentage" : "31",
      "goodPercentage" : "47"
    },
    "ownerId" : null,
    "type" : null,
    "email" : "agent23@example.com"
  } ]
}

Create a contact

This API creates a contact in your helpdesk.

POST /api/v1/contacts

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "zip" : "123902", "lastName" : "New NAme1", "country" : "India", "secondaryEmail" : "hajk@hajk.com", "city" : "Chennai", "facebook" : "MYACCOUNT", "mobile" : "29010", "description" : "hsjflksjfklsj", "ownerId" : "1892000000056007", "type" : "paidUser", "title" : "The contact", "accountId" : "1892000000052077", "firstName" : "New Contact", "twitter" : "MYTWITTEr", "phone" : "91020", "street" : "halo street", "state" : "TamilNadu", "email" : "hallo@hallo.com" }'

Response Example

{
  "zip" : "123902",
  "lastName" : "New NAme1",
  "modifiedTime" : "2016-07-26T13:11:02.000Z",
  "country" : "India",
  "secondaryEmail" : "hajk@hajk.com",
  "city" : "Chennai",
  "customFields" : {
    "Mypercent" : null,
    "MyDatetime" : null,
    "Mydecimal" : null,
    "MyInt" : null,
    "Mydate" : null,
    "MyBox" : "false",
    "MyText" : null,
    "MultiselectPickList" : null
  },
  "facebook" : "MYACCOUNT",
  "mobile" : "29010",
  "description" : "hsjflksjfklsj",
  "ownerId" : "1892000000056007",
  "type" : "paidUser",
  "title" : "The contact",
  "accountId" : "1892000000052077",
  "firstName" : "New Contact\t",
  "twitter" : "MYTWITTEr",
  "phone" : "91020",
  "street" : "halo street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "TamilNadu",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "hallo@hallo.com"
}

Update a contact

This API updates details of an existing contact.

PATCH /api/v1/contacts/{contact_id}

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/1892000001128052
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "zip" : "123902", "lastName" : "New NAme2", "country" : "India", "secondaryEmail" : "hajk@hajk.com", "city" : "Chennai", "facebook" : "MYACCOUT", "mobile" : "29010", "description" : "hsjflksjfklsj", "ownerId" : "1892000000888059", "type" : "paidUser", "title" : "The contact", "accountId" : "1892000000052090", "firstName" : "New Contact1", "twitter" : "MYTWITTEr", "phone" : "9102slkj0", "street" : "halo street", "state" : "TamilNadu", "email" : "hallo@hllo.com" }'

Response Example

{
  "zip" : "123902",
  "lastName" : "New NAme2",
  "modifiedTime" : "2016-07-26T13:16:19.215Z",
  "country" : "India",
  "secondaryEmail" : "hajk@hajk.com",
  "city" : "Chennai",
  "customFields" : {
    "Mypercent" : "0.0",
    "MyDatetime" : null,
    "Mydecimal" : "0.0",
    "MyInt" : null,
    "Mydate" : null,
    "MyBox" : "false",
    "MyText" : null,
    "MultiselectPickList" : null
  },
  "facebook" : "MYACCOUT",
  "mobile" : "29010",
  "description" : "hsjflksjfklsj",
  "ownerId" : "1892000000888059",
  "type" : "paidUser",
  "title" : "The contact",
  "accountId" : "1892000000052090",
  "firstName" : "New Contact1",
  "twitter" : "MYTWITTEr",
  "phone" : "9102slkj0",
  "street" : "halo street",
  "createdTime" : "2016-07-26T13:11:02.000Z",
  "zohoCRMContact" : null,
  "state" : "TamilNadu",
  "id" : "1892000001128052",
  "customerHappiness" : {
    "badPercentage" : "0",
    "okPercentage" : "0",
    "goodPercentage" : "0"
  },
  "email" : "hallo@hllo.com"
}

List tickets by contact

This API lists tickets received from a specific contact.

Query Params

Param Name
Data Type
Description
departmentId

long

Department from which the tickets need to be queried

from

Integer

From index

limit

Integer

No of tickets to be fetched

sortBy

string

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

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000000042032/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "ticketNumber" : "149",
    "customerResponseTime" : "2017-11-03T07:03:09.203Z",
    "productId" : "18944000000424033",
    "contactId" : "18944000000421011",
    "subject" : "Welcome to Zoho Support. You've got a sample Request",
    "dueDate" : "2017-11-04T07:03:09.000Z",
    "departmentId" : "18944000000092305",
    "channel" : "Email",
    "threadCount" : "7",
    "lastThread" : null,
    "priority" : "Medium",
    "assigneeId" : null,
    "closedTime" : null,
    "commentCount" : "0",
    "phone" : "9876543321",
    "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe",
    "createdTime" : "2017-10-12T13:11:50.000Z",
    "id" : "18944000000336005",
    "email" : "support@zohosupport.com",
    "status" : "Open"
  } ]
}

Accounts

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

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the account

customFields

list

Optional

User-defined fields associated with the account

accountName

string

Required

Name of the account

email

string

Optional

Email ID of the account

website

string

Optional

Website of the account

fax

string

Optional

Fax number of the account

ownerId

long

Optional

ID of account owner

associatedSLAIds

list

Optional

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

industry

string

Optional

Industry in which the account operates

city

string

Optional

City in which the account is based

country

string

Optional

Country in which the account is based

state

string

Optional

State in which the account is based

street

string

Optional

Address of the account

code

string

Optional

Zip code

description

string

Optional

A short description of the account

phone

string

Optional

Phone number of the account

annualrevenue

double

Optional

Annual revenue of the account

createdTime

timestamp

ReadOnly

Time of account creation

modifiedTime

timestamp

ReadOnly

Time of account modification

Example

{ "country" : null, "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : null, "code" : null, "accountName" : "new account name _ 16_2_2015_21_57_56_1424104076448", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "text custom _ 5_8_2015_14_2_23_1438763543159" : null, "text custom _ 9_4_2015_0_2_1_1428517921395" : null, "text custom _ 9_7_2015_20_41_5_1436454665096" : null, "text custom _ 8_7_2015_10_0_31_1436329831511" : null, "text custom _ 8_9_2015_13_11_52_1441698112987" : null, "text custom _ 8_7_2015_13_34_50_1436342690695" : null, "text custom _ 7_5_2015_18_27_21_1431003441176" : null }, "description" : null, "industry" : null, "ownerId" : "3263000000057001", "phone" : "1000", "street" : null, "annualrevenue" : null, "createdTime" : "2015-02-16T16:57:44.000Z", "id" : "3263000000074571", "state" : null, "fax" : null, "email" : null }



Get an account

This API fetches an account from your helpdesk.

GET /api/v1/accounts/{account_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "accountName" : "new account name _ 16_2_2015_21_57_56_1424104076448",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "text custom _ 5_8_2015_14_2_23_1438763543159" : null,
    "text custom _ 9_4_2015_0_2_1_1428517921395" : null,
    "text custom _ 9_7_2015_20_41_5_1436454665096" : null,
    "text custom _ 8_7_2015_10_0_31_1436329831511" : null,
    "text custom _ 8_9_2015_13_11_52_1441698112987" : null,
    "text custom _ 8_7_2015_13_34_50_1436342690695" : null,
    "text custom _ 7_5_2015_18_27_21_1431003441176" : null
  },
  "description" : null,
  "industry" : null,
  "ownerId" : "3263000000057001",
  "phone" : "1000",
  "street" : null,
  "annualrevenue" : null,
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

List all accounts

This API lists all accounts in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

No. of accounts to fetch

sortBy

string

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

GET /api/v1/accounts

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "website" : "112121",
    "accountName" : "Admin Account",
    "phone" : "121212",
    "id" : "1892000000052077",
    "email" : "admin@zohocorp.com"
  }, {
    "website" : "1211212",
    "accountName" : "Agent Account",
    "phone" : "11211",
    "id" : "1892000000052090",
    "email" : "agent@zohocorp.com"
  } ]
}

Create an account

This API creates an account in your helpdesk.

POST /api/v1/accounts

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "accountName" : "new account name _ 16_2_2015_21_57_56_1424104076448", "phone" : "1000" }'

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "accountName" : "new account name _ 16_2_2015_21_57_56_1424104076448",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "text custom _ 5_8_2015_14_2_23_1438763543159" : null,
    "text custom _ 9_4_2015_0_2_1_1428517921395" : null,
    "text custom _ 9_7_2015_20_41_5_1436454665096" : null,
    "text custom _ 8_7_2015_10_0_31_1436329831511" : null,
    "text custom _ 8_9_2015_13_11_52_1441698112987" : null,
    "text custom _ 8_7_2015_13_34_50_1436342690695" : null,
    "text custom _ 7_5_2015_18_27_21_1431003441176" : null
  },
  "description" : null,
  "industry" : null,
  "ownerId" : "3263000000057001",
  "phone" : "1000",
  "street" : null,
  "annualrevenue" : null,
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Update an account

This API updates details of an existing account.

PATCH /api/v1/accounts/{account_id}

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/3263000000074571
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "accountName" : "new Agent for details _ 16_2_2015_21_57_56_1424104076448", "phone" : "1000" }'

Response Example

{
  "country" : null,
  "modifiedTime" : "2015-03-02T14:49:18.000Z",
  "website" : null,
  "code" : null,
  "accountName" : "new Agent for details _ 16_2_2015_21_57_56_1424104076448",
  "city" : null,
  "associatedSLAIds" : [ 3263000000057, 3000000057001 ],
  "customFields" : {
    "text custom _ 5_8_2015_14_2_23_1438763543159" : null,
    "text custom _ 9_4_2015_0_2_1_1428517921395" : null,
    "text custom _ 9_7_2015_20_41_5_1436454665096" : null,
    "text custom _ 8_7_2015_10_0_31_1436329831511" : null,
    "text custom _ 8_9_2015_13_11_52_1441698112987" : null,
    "text custom _ 8_7_2015_13_34_50_1436342690695" : null,
    "text custom _ 7_5_2015_18_27_21_1431003441176" : null
  },
  "description" : null,
  "industry" : null,
  "ownerId" : "3263000000057001",
  "phone" : "1000",
  "street" : null,
  "annualrevenue" : null,
  "createdTime" : "2015-02-16T16:57:44.000Z",
  "state" : null,
  "id" : "3263000000074571",
  "fax" : null,
  "email" : null
}

Tasks

Tasks are work activities assigned to agents. It is not mandatory for tasks to be related to only ticket resolution.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the task

customFields

list

Optional

User-defined fields related to the task

departmentId
see documentation

long

Required

Department associated with the task

subject

string

Required

Subject of the task

long

Optional

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

dueDate

timestamp

Optional

Due date for completing the task

ownerId

string

Optional

Owner of the task

category

string

Optional

Category of the task

status

string

Optional

Status of task completion

priority

string

Optional

Priority of the task

description

string

Optional

Description of the task

createdTime

timestamp

ReadOnly

Time of task creation

modifiedTime

timestamp

ReadOnly

Time of task modification

creatorId

string

ReadOnly

ID of user who created the task

ticket

Ticket

ReadOnly

Ticket associated with the task

Example

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "customFields" : { }, "subject" : "NEw Task", "completedTime" : null, "departmentId" : "3000000007043", "dueDate" : "2016-07-29T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "createdTime" : "2016-07-26T17:32:11.000Z", "id" : "3000000018001", "category" : null, "ticketId" : "3000000008753", "status" : "Not Started" }



Get a task

This API fetches a single task from your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : tickets

GET api/v1/tasks/{task_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks/3000000018001?include=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "modifiedTime" : "2016-07-26T17:32:11.000Z",
  "ticket" : {
    "ticketNumber" : "101",
    "contact" : {
      "firstName" : null,
      "lastName" : "Lawrence",
      "id" : "3000000008749"
    },
    "id" : "3000000008753"
  },
  "customFields" : {
  },
  "subject" : "NEw Task",
  "completedTime" : null,
  "departmentId" : "3000000007043",
  "dueDate" : "2016-07-29T16:16:16.000Z",
  "creatorId" : "3000000008692",
  "description" : null,
  "ownerId" : null,
  "priority" : "Normal",
  "createdTime" : "2016-07-26T17:32:11.000Z",
  "id" : "3000000018001",
  "category" : null,
  "ticketId" : "3000000008753",
  "status" : "Not Started"
}

List all tasks

This API lists all the tasks in your helpdesk.

Query Params

Param Name
Data Type
Description

string

Allowed values are : tickets

from

integer

From index

limit

integer

No. of tasks to fetch

departmentId
see documentation

long

Department from which the tasks need to be queried

sortBy

string

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

GET api/v1/tasks

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-13T06:45:56.000Z",
    "subject" : "qweqweqe",
    "completedTime" : null,
    "dueDate" : "2013-12-28T06:30:00.000Z",
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : null,
    "ownerId" : "1892000000056007",
    "priority" : "Low",
    "isCommented" : true,
    "createdTime" : "2013-12-19T12:02:23.000Z",
    "id" : "1892000000055041",
    "category" : "Meeting",
    "ticketId" : "1892000001125055",
    "status" : "Not Started"
  }, {
    "modifiedTime" : "2014-03-21T11:31:55.000Z",
    "subject" : "qwqq",
    "completedTime" : null,
    "dueDate" : "2014-03-28T06:30:00.000Z",
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : null,
    "ownerId" : "1892000000042001",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2014-03-21T11:31:03.000Z",
    "id" : "1892000000138005",
    "category" : null,
    "ticketId" : "1892000000094004",
    "status" : "Not Started"
  }, {
    "modifiedTime" : "2014-05-26T07:26:46.000Z",
    "subject" : "asasas",
    "completedTime" : null,
    "dueDate" : null,
    "departmentId" : "1892000000006907",
    "creatorId" : "1892000000042001",
    "description" : "sasa",
    "ownerId" : "1892000000042001",
    "priority" : "High",
    "isCommented" : false,
    "createdTime" : "2014-05-26T07:26:46.000Z",
    "id" : "1892000000272001",
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  } ]
}

Create a task

This API adds a task in your helpdesk.

POST api/v1/tasks

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "subject" : "New Testing Task", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "category" : null, "priority" : "High", "status" : "In Progress" }'

Response Example

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

Update a task

This API updates an existing task.

PATCH api/v1/tasks/{task_id}

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/3000000054002
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

  -d '{ "subject" : "New TESTSTS Task", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "category" : null, "priority" : "High", "status" : "In Progress" }'

Response Example

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

List tasks by ticket

This API lists all tasks related to a particular ticket.

Query Params

Param Name
Data Type
Description
from

integer

From index

isCompleted

boolean

Completion status of the task

limit

integer

No. of tasks to fetch

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

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2016-07-14T08:22:16.000Z",
    "customFields" : {
    },
    "subject" : "New Testing Task",
    "departmentId" : "3000000007043",
    "dueDate" : "2016-07-21T16:16:16.000Z",
    "creatorId" : "3000000008692",
    "description" : null,
    "ownerId" : null,
    "priority" : "Normal",
    "createdTime" : "2016-07-14T08:22:16.000Z",
    "id" : "3000000053002",
    "category" : "null",
    "ticketId" : "3000000008753",
    "status" : "In Progress"
  } ]
}

Agents

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

ATTRIBUTES

Attribute Name
Data Type
Description
emailId

string

Required

Email ID of the agent

status

string

ReadOnly

Activation status of the agent: ACTIVE or DISABLED

lastName

string

Required

Last name of the agent

firstName

string

Optional

First name of the agent

phone

string

Optional

Phone number of the agent

mobile

string

Optional

Mobile number of the agent

extn

string

Optional

Extn number of the agent

associatedDepartmentIds

list

Required

Departments with which the agent is associated

associatedChatDepartmentIds

list

Optional

Chat departments with which the agent is associated

id

long

ReadOnly

ID of the agent

zuid

long

ReadOnly

Zoho user ID of the agent

roleId

long

ReadOnly

Role ID of the agent

profileId

long

ReadOnly

Profile ID of the agent

photoURL

string

ReadOnly

Photo URL of the agent

isConfirmed

boolean

ReadOnly

Confirmation status of the agent

countryCode

string

Optional

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

langCode

string

Optional

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

Example

{ "lastName" : "manoj (kumar)", "extn" : "3298", "roleId" : "1892000000056099", "langCode" : "fr_FR", "mobile" : "", "emailId" : "manojkumar.s+admin@zohocorp.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10687231", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ], "firstName" : "", "photoURL" : null, "phone" : "12121", "profileId" : "1892000000056091", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000056007", "status" : "ACTIVE" }



Get an agent

This API fetches the details of an agent from your helpdesk.

GET /api/v1/agents/{agent_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents/4000000008688
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "lastName" : "manoj (kumar)",
  "extn" : "3298",
  "roleId" : "1892000000056099",
  "langCode" : "fr_FR",
  "mobile" : "",
  "emailId" : "manojkumar.s+admin@zohocorp.com",
  "associatedChatDepartmentIds" : [ ],
  "zuid" : "10687231",
  "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
  "firstName" : "",
  "photoURL" : null,
  "phone" : "12121",
  "profileId" : "1892000000056091",
  "countryCode" : "en_US",
  "isConfirmed" : true,
  "id" : "4000000008688",
  "status" : "ACTIVE"
}

List all agents

This API lists all agents in your helpdesk.

Query Params

Param Name
Data Type
Description
from

integer

From index

limit

integer

No. of agents to fetch

status

string

Filter agents based on activation status: ACTIVE or DISABLED. By default, this query param fetches all agents.

GET /api/v1/agents

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "lastName" : "manoj (kumar)",
    "extn" : "3298",
    "roleId" : "1892000000056099",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "manojkumar.s+admin@zohocorp.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10687231",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "12121",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "isConfirmed" : true,
    "id" : "1892000000056007",
    "status" : "ACTIVE"
  }, {
    "lastName" : "manojkumar.s+manojtest",
    "extn" : "3298",
    "roleId" : "1892000000056899",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "manojkumar.s+manojtest@zohocorp.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10657727",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ],
    "firstName" : "",
    "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727",
    "phone" : "",
    "profileId" : "1892000000056091",
    "countryCode" : "en_US",
    "isConfirmed" : true,
    "id" : "1892000000042001",
    "status" : "ACTIVE"
  }, {
    "lastName" : "stephen",
    "extn" : "3298",
    "roleId" : "1892000000056004",
    "langCode" : "en_US",
    "mobile" : "",
    "emailId" : "stephen.kirubaharan+1@zohocorp.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : "10713988",
    "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ],
    "firstName" : "",
    "photoURL" : null,
    "phone" : "68779989",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "isConfirmed" : true,
    "id" : "1892000000070001",
    "status" : "DISABLED"
  }, {
    "lastName" : "kumar",
    "extn" : "3298",
    "roleId" : "1892000000056004",
    "langCode" : "ja_JP",
    "mobile" : "",
    "emailId" : "asmanojkumar.msec@zohocorp.com",
    "associatedChatDepartmentIds" : [ ],
    "zuid" : null,
    "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ],
    "firstName" : "manoj",
    "photoURL" : null,
    "phone" : "",
    "profileId" : "18920000000232043",
    "countryCode" : "en_US",
    "isConfirmed" : false,
    "id" : "1892000000888059",
    "status" : "ACTIVE"
  } ]
}

Departments

Departments are the organizational divisions configured in your helpdesk.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the department

name

string

Required

Department name

nameInCustomerPortal

string

Optional

Display name of the department

description

string

Optional

Description of the department

isVisibleInCustomerPortal

boolean

Required

Visibility of the department in the customer portal

isEnabled

boolean

Optional

Activation status of the department

hasLogo

boolean

ReadOnly

States whether the department has a logo

creatorId

long

ReadOnly

ID of user who created the department

associatedAgentIds

list

Required

IDs of agents associated with the department

Example

{ "hasLogo" : true, "isVisibleInCustomerPortal" : true, "isEnabled" : true, "name" : "newdept", "creatorId" : "1892000000042001", "description" : null, "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "id" : "1892000000082069", "nameInCustomerPortal" : "manojportal" }



Get a department

This API fetches information on a single department.

GET /api/v1/departments/{department_id}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "hasLogo" : false,
  "isVisibleInCustomerPortal" : true,
  "isEnabled" : true,
  "creatorId" : "1892000000042001",
  "name" : "Department 1",
  "description" : null,
  "associatedAgentIds" : [ "1892000000070001", "1892000000042001", "1892000000348003", "1892000000232001", "1892000000888059", "1892000000056007", "1892000000297589", "1892000000292001", "1892000000779002", "1892000000047001", "1892000000043001", "1892000000396001", "1892000000653051", "1892000000634001" ],
  "id" : "1892000000006907",
  "nameInCustomerPortal" : "Department 1"
}

List all departments

This API lists all departments in your helpdesk.

Query Params

Param Name
Data Type
Description
isEnabled

boolean

Activation status of the department

GET /api/v1/departments

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/departments
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "isDefault" : true,
    "hasLogo" : false,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "creatorId" : "1892000000042001",
    "name" : "Department 1",
    "description" : null,
    "associatedAgentIds" : [ "1892000000070001", "1892000000042001", "1892000000348003", "1892000000232001", "1892000000888059", "1892000000056007", "1892000000297589", "1892000000292001", "1892000000779002", "1892000000047001", "1892000000043001", "1892000000396001", "1892000000653051", "1892000000634001" ],
    "id" : "1892000000006907",
    "nameInCustomerPortal" : "Department 1"
  }, {
    "isDefault" : false,
    "hasLogo" : false,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "creatorId" : "1892000000042001",
    "name" : "newdept",
    "description" : "Dept example",
    "associatedAgentIds" : [ "1892000000888059", "1892000000056007", "1892000000042001" ],
    "id" : "1892000000082069",
    "nameInCustomerPortal" : "newdept"
  } ]
}

Uploads

Uploads are temporary attachments that exist with a ticket for just 24 hours.

ATTRIBUTES

Attribute Name
Data Type
Description
id

long

ReadOnly

ID of the attachment

creatorId

long

ReadOnly

ID of user who added the attachment

createdTime

timestamp

ReadOnly

Time of file attachment

name

string

ReadOnly

Name of the attachment

isPublic

boolean

ReadOnly

Visibility setting of the attachment

size

long

ReadOnly

Size of the attachment

Example

{ "size" : "4769", "creatorId" : "4000000008692", "name" : "zoho.jpeg", "createdTime" : "2016-06-23T07:31:42.000Z", "isPublic" : false, "id" : "4000000055001" }



Upload a file

This API uploads a file.

File Params

file

Content-Type:multipart/form-data

File to attach

POST /api/v1/uploads

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/uploads
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "size" : "4769",
  "creatorId" : "4000000008692",
  "name" : "zoho.jpeg",
  "createdTime" : "2016-06-23T07:31:42.000Z",
  "isPublic" : false,
  "id" : "4000000055001"
}

Download a file

This API displays the content of an attachment.

Query Params

Param Name
Data Type
Description
inline

boolean

Display content inline

GET api/v1/uploads/{attachment_id}/content

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/uploads/1892000001008043/contents
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

200

Search across entities

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

Query Params

Param Name
Data Type
Description
searchStr

String

Keyword or phrase to search

module

String

Module to search in: Tickets, Accounts, Contacts or Tasks. The default response includes all modules.

departmentId

long

Department from which the entities need to be queried

from

int

From index, starts from 0

limit

int

No. of entities to fetch

sortBy

String

Sort by a specific attribute: relevance or modifiedTime

GET /api/v1/search?searchStr={searchStr}&departmentId={departmentId}&from={from}&limit={limit}&sortBy={sortField}

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/search?searchStr=zylker&from=0&limit=10&sortBy=modifiedTime
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "customerResponseTime" : "2016-06-27T07:22:52.117Z",
    "productId" : "4000000013043",
    "contactId" : "4000000013012",
    "subject" : "Zylker ticket",
    "customFields" : {
      "featureRequest" : false,
      "region" : "Asia"
    },
    "module" : "tickets",
    "departmentId" : "4000000007043",
    "dueDate" : null,
    "channel" : "Phone",
    "threadCount" : "0",
    "priority" : null,
    "assigneeId" : "4000000008692",
    "closedTime" : null,
    "commentCount" : "0",
    "number" : "104",
    "phone" : null,
    "contact" : {
      "phone" : null,
      "name" : "Stephen",
      "id" : "4000000013012",
      "type" : null,
      "email" : null,
      "account" : {
        "website" : null,
        "name" : "Zylker Accounts",
        "id" : "4000000008850"
      }
    },
    "createdTime" : "2016-06-27T07:22:52.000Z",
    "id" : "4000000016009",
    "email" : null,
    "status" : "Open"
  }, {
    "ticket" : null,
    "subject" : "Wifi adapter not working in zylker",
    "completedTime" : null,
    "customFields" : {
      "severity" : "High",
      "followUpDate" : "2016-07-07T19:30:00.000Z"
    },
    "module" : "tasks",
    "dueDate" : "2016-06-27T19:30:00.000Z",
    "description" : null,
    "ownerId" : "4000000008692",
    "priority" : "High",
    "isCommented" : false,
    "createdBy" : "4000000008692",
    "contact" : null,
    "createdTime" : "2016-06-27T06:39:48.000Z",
    "id" : "4000000013065",
    "category" : null,
    "ticketId" : null,
    "status" : "Not Started"
  }, {
    "website" : null,
    "phone" : null,
    "accountName" : "Zylker India",
    "customFields" : {
      "city" : "Delhi",
      "state" : "India"
    },
    "module" : "accounts",
    "id" : "4000000013027",
    "email" : null
  }, {
    "lastName" : "Stephen",
    "accountId" : "4000000008850",
    "firstName" : "Henry",
    "phone" : null,
    "customFields" : {
      "customerSince" : "2011",
      "editionUsed" : "Professional"
    },
    "module" : "contacts",
    "fullName" : "Henry Stephen",
    "id" : "4000000013012",
    "ownerId" : "4000000008692",
    "email" : null,
    "account" : {
      "website" : null,
      "name" : "Zylker India",
      "id" : "4000000008850"
    }
  } ],
  "count" : {
    "tickets" : 1,
    "accounts" : 1,
    "tasks" : 1,
    "contacts" : 1
  }
}

MailReplyAddress

MailReplyAddress refers to the email ID from which replies are sent to customers.

Example

{ "address" : "techsupport@gmail.com", "displayName" : "Tech", "departmentId" : "4000000007043", "id" : "4000000026003", "isActive" : true }



List all MailReplyAddresses

This API lists all mailreplyaddresses configured in your helpdesk.

Query Params

Param Name
Data Type
Description
departmentId

long

Department from which the addresses need to be queried

isActive

boolean

Activation status of the reply email ID

GET /api/v1/mailReplyAddress

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress?departmentId=4000000007043
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 50c9bb96b17694d63cd0f03eadbe4ae5"

Response Example

{
  "data" : [ {
    "address" : "support3@anish.zohosupport.com",
    "displayName" : "Support3",
    "departmentId" : "4000000007043",
    "id" : "4000000025003",
    "isActive" : true
  }, {
    "address" : "market@zohosupport.com",
    "displayName" : "Marketing",
    "departmentId" : "4000000007043",
    "id" : "4000000026001",
    "isActive" : false
  }, {
    "address" : "techsupport@gmail.com",
    "displayName" : "Tech",
    "departmentId" : "4000000007043",
    "id" : "4000000026003",
    "isActive" : true
  } ]
}