Fetch records from Zoho Desk

Table of Contents

Note:

  • Each time the zoho.desk.getRecords integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.desk.getRecords integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

This task is used to fetch records from the specified Zoho Desk module.

Syntax

<variable> = zoho.desk.getRecords(<orgId>, <module_name>, <fromIndex>, <limit>, <query_value>, <connection>);

where,

ParameterData typeDescription
<variable>KEY-VALUEVariable which will hold the response returned by Zoho Desk. It represents the list of records fetched.
<orgId>NUMBERspecifies the organization ID of the account from which the records will be fetched. This can be found in Zoho Desk Settings > Developer Space > API.  

<module_name> TEXT

specifies the module from which the records will be fetched.

The following is the list of supported modules.

  • Agents
  • Departments
  • Tickets
  • Contacts
  • Accounts
  • Tasks
  • Products
  • Contracts

<from>

(optional)

NUMBER

specifies the index of the record from which the records will be fetched.

Note: 

  • This is a mandatory param when used in Zoho Creator.
  • The default value for this param is 1

<limit>

(optional)

NUMBER

specifies the number of records which will be fetched.

Note: 

  • This is a mandatory param when used in Zoho Creator.
  • The default value for this param is 10

<query_value>

(optional)

KEY-VALUE

Query to include secondary information related to the selected module.

To learn about the applicable values, click here and go to <ModuleName> -> List all <ModuleName>

To ignore the secondary information, specify empty map. 
For ex: { "" : "" } 

Note: This is a mandatory param when used in Zoho Creator.

<connection>

(optional)*

TEXT

specifies the name of the connection

The scopes which need to be selected are:  
- Desk.basic.READ 
- Desk.tasks.READ 
- Desk.tickets.READ 
- Desk.settings.READ 
- Desk.contacts.READ 

Note: This is a mandatory param when used in Zoho Creator.

Example

The following script fetches all the records from Zoho Desk module - Contacts.

queryValue = {"":""}; 
response = zoho.desk.getRecords(641XXXXXX, "contacts", 1, 10, queryValue, "desk_connection");

where,

response
variable which will hold the response returned by Zoho Desk. It represents the list of all the records fetched from the specified Zoho Desk module.
641XXXXXX
is the NUMBER that represents the organization ID.
"contacts"
is the TEXT that represents the name of the module from which the records need to be fetched.
1
is the NUMBER that represents the start index from which the records are to be fetched
10
is the NUMBER that represents the number of records to be fetched
"desk_connection"
is the TEXT that represents the name of the connection.

Sample Response

Success Response

  • The success response returned is of the following format.

       {
       "data": [
       {
       "firstName": "Ben",
       "lastName": "Williams",
       "email": "ben@zylker.com",
       "secondaryEmail": null,
       "mobile": null,
       "phone": "+1 678 XXX XXXX",
       "type": null,
       "ownerId": "168XXXXXXXXXXXX005",
       "accountId": "168XXXXXXXXXXXX097",
       "photoURL": null,
       "zohoCRMContact": {
       "id": "230XXXXXXXXXXXXX044",
       "type": "new"
       },
       "customerHappiness": {
       "badPercentage": "0",
       "okPercentage": "0",
       "goodPercentage": "0"
       },
       "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Contacts/dv/bf5c8fXXXXXXXXXXXXXXXXX411872c0a55fabae67fb0",
       "id": "168XXXXXXXXXXXX001"
       },
       {
       "firstName": Tom,
       "lastName": "Lewis",
       "email": tom@zylker.com,
       "secondaryEmail": null,
       "mobile": null,
       "phone": "+1 678 XXX XXXX",
       "type": null,
       "ownerId": "168XXXXXXXXXXXX002",
       "accountId": null,
       "photoURL": null,
       "zohoCRMContact": {
       "id": "230XXXXXXXXXXXXX020",
       "type": "contacts"
       },
       "customerHappiness": {
       "badPercentage": "0",
       "okPercentage": "0",
       "goodPercentage": "0"
       },
       "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Contacts/dv/bf5c8fXXXXXXXXXXXXXXXXX6519df7cc50d48844902f0",
       "id": "168XXXXXXXXXXXX040"
       }
       ]
       }
       oURL": null,
       "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Contacts/dv/bf5c8fXXXXXXXXXXXXXXXXX6519df7cc50d48844902f0",
       "id": "168XXXXXXXXXXXX001"
       }
       ]
       }

To fetch the ID of records from the response, use the following snippet:

var1 = <response_variable>.getJson("data"); 
var2 = var1.toJsonList(); 
for each var3 in var2 
  { 
    info var3.getJson("id"); 
  }

Failure Response

  • The failure response returned for incorrect or non-existent organization ID is of the following format.

       {
       "errorCode":"UNPROCESSABLE_ENTITY",
       "message":"The value passed for the 'orgId' parameter is invalid."
       }

  • The failure response returned for an incorrect or non-existent record ID is of the following format.

       {
       "errorCode":"URL_NOT_FOUND",
       "message":"The URL you requested could not be found."
       }

Related links