Search Records In Zoho Desk

Table of Contents

Note:

  • Each time the zoho.desk.searchRecords 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.searchRecords 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. 

Description

This task is used to fetch records that match a specified criteria.

Syntax

<variable> = zoho.desk.searchRecords(<orgID>, <module_name>, <query>, <fromIndex>, <limit>, <connection>);

where,

ParamsData typeDescription
<variable>KEY-VALUEspecifies the variable which will hold the response returned by Zoho Desk.
<orgID>NUMBERspecifies the organization ID of the account in which the record will be searched. This can be found in Zoho Desk Settings > Developer Space > API.  

<module_name> TEXT

specifies the module in which the records need to be searched.

The following is the list of supported modules.

  • Tickets
  • Accounts
  • Contacts
  • Articles
  • Tasks
  • Products

<query> 

(optional)*

KEY-VALUE

specifies the search criteria. The search criteria are given as key-value pairs, with keys as query param names given in the Zoho Desk API.

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

<from>

(optional)*

NUMBER

specifies the start index of the record from which the records will be searched. The index starts from 0.

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

<limit>

(optional)*

NUMBER

specifies the number of records that will be fetched.
Range: 1-100 records
Default: 10 records

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

<connection>

(optional)*

TEXT

specifies the name of the connection.

The scopes needed to be selected are   
- Desk.search.READ 
- Desk.articles.READ
- Desk.tasks.READ 
- Desk.tickets.READ 
- Desk.settings.READ 
- Desk.contacts.READ 

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

Examples

Example 1 -

The following example searches for the records whose subject contains - Deluge in the Zoho Desk module - Tickets.

searchValue = {"subject":"Deluge"}; 
response = zoho.desk.searchRecords(641XXXXXX, "tickets", searchValue, 0, 5, "desk_connection");

where,

response
is the variable which will hold the KEY-VALUE response returned by Zoho Desk. It represents the records fetched.
641XXXXXX
is the NUMBER that represents the organization ID
"tickets"
is the TEXT that represents the name of the module in which the records need to be searched
searchValue
is the KEY-VALUE variable that holds the search criteria
"subject"
is the TEXT that represents the field name as specified by the Zoho Desk API.
0
is the NUMBER that represents the start index from which the records need to be searched for.
5
is the NUMBER that represents the number of records that need to be fetched.
"desk_connection"
is the TEXT that represents the name of the connection.

Example 2 -

The following example searches for the records in the Zoho Desk module – Tickets, where the subject contains "Deluge" and the phone number is present.

searchValue = {"subject":"Deluge", "phone":"1111*****"};
response = zoho.desk.searchRecords(641XXXXXX, "tickets", searchValue, 0, 5, "desk_connection");

where,

response
is the variable which will hold the KEY-VALUE response returned by Zoho Desk. It represents the records fetched.
641XXXXXX
is the NUMBER that represents the organization ID
"tickets"
is the TEXT that represents the name of the module in which the records need to be searched
searchValue
is the KEY-VALUE variable that holds the search criteria
"subject"
is the TEXT that represents the field name as specified by the Zoho Desk API.
"phone"
is an additional TEXT field used in the search criteria, representing the phone number field.
0
is the NUMBER that represents the start index from which the records need to be searched for.
5
is the NUMBER that represents the number of records that need to be fetched.
"desk_connection"
is the TEXT that represents the name of the connection.

Response Format

Success response

The success response will be returned in the following format:

  •   {
      "data": [
      {
      "ticketNumber": "687",
      "modifiedTime": "2019-03-04T07:30:44.000Z",
      "subCategory": null,
      "statusType": "Open",
      "subject": "Query in Deluge script",
      "customFields": {
      "Mailing Zip": null,
      "TAM": null,
      "Quote number": null,
      "TestData": null,
      "LightAgents": null,
      "attachmentLinks": null,
      "Contract Type": null,
      "Serial Number": null,
      "Mailing Country": null,
      "Total Age": null,
      "Start Date": "2019-03-03",
      "bugID": null,
      "PreviousTicketOwner": null,
      "Managed Firewall": null,
      "Manufacturer": null,
      "Sales Lead?": "true",
      "advisory": null,
      "LIS Customer": null,
      "Single Date": null,
      "DateCF": null,
      "Event_Scheduled": null,
      "Office Name": null,
      "previousClosedTime": null,
      "Incoming Count": null,
      "offbusinesshour": "false",
      "SAM": null,
      "Every issue no.": null,
      "Setup Sub Category": null,
      "TicketOwnerUpdatedTime": null,
      "Every issue link": null,
      "PotentialId": null,
      "TestNumber": null,
      "Ticket type": null,
      "Invoice Number": null,
      "Access Information": null,
      "NewTicketNumber": null,
      "Type of Category": null,
      "account type": null,
      "Service Frequency": null,
      "SalesLead_alertSend": "true",
      "SATcase Serial Number": null,
      "Mailing City": null,
      "Mailing State": null,
      "OldTicketNumber": null,
      "Department Responsible": null,
      "Mailing Street": null,
      "Model": null,
      "TestDate": null,
      "Outgoing Count": null,
      "NewContact": "false"
      },
      "dueDate": null,
      "departmentId": "168XXXXXXXXXXXX907",
      "channel": "Twitter",
      "isRead": true,
      "description": null,
      "onholdTime": null,
      "resolution": null,
      "sharedDepartments": [
      
      ],
      "closedTime": null,
      "isOverDue": false,
      "responseDueDate": null,
      "contact": {
      "lastName": "230XXXXXXXXXXXX077",
      "secondaryEmail": null,
      "customFields": {
      
      },
      "mobile": null,
      "type": null,
      "ownerId": null,
      "firstName": "James",
      "accountId": "168XXXXXXXXXXXX093",
      "photoURL": null,
      "phone": null,
      "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Contacts/dv/bf5c8f5ad85afXXXXXXXXXXXXXXXXXXXX416f91661cfb15",
      "zohoCRMContact": {
      "id": "230XXXXXXXXXXXXX027",
      "type": "new"
      },
      "customerHappiness": {
      "badPercentage": "0",
      "okPercentage": "0",
      "goodPercentage": "0"
      },
      "id": "168XXXXXXXXXXXX109",
      "email": null,
      "account": {
      "website": null,
      "accountName": "JC",
      "phone": null,
      "customFields": {
      
      },
      "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Accounts/dv/bf5c8f5ad85afXXXXXXXXXXXXXXXXXXXXd98648cf73bac9a",
      "id": "168XXXXXXXXXXXX093",
      "email": null
      }
      },
      "createdTime": "2019-03-04T07:30:43.000Z",
      "modifiedBy": "168XXXXXXXXXXXX005",
      "id": "168XXXXXXXXXXXX107",
      "department": {
      "name": "smith",
      "id": "168XXXXXXXXXXXX6907"
      },
      "email": null,
      "customerResponseTime": "2019-03-04T07:30:43.000Z",
      "productId": null,
      "contactId": "168XXXXXXXXXXXX109",
      "threadCount": "0",
      "lastThread": null,
      "team": null,
      "priority": null,
      "classification": null,
      "assigneeId": "168XXXXXXXXXXXX8005",
      "commentCount": "0",
      "accountId": "168XXXXXXXXXXXX093",
      "phone": null,
      "webUrl": "https://desk.zoho.com/support/smith/ShowHomePage.do#Cases/dv/bf5c8f5ad85afXXXXXXXXXXXXXXXXXXXX7d9b02e22471ff",
      "teamId": null,
      "assignee": {
      "photoURL": null,
      "firstName": "DRE",
      "lastName": "smith",
      "emailId": "smith@zylker.com",
      "id": "168XXXXXXXXXXXX005",
      "zuid": "72XXXX48"
      },
      "category": null,
      "status": "Open"
      }
      ],
      "count": 1
      }

To extract the IDs of the records returned, execute the following:

 for each rec in <response>
 {
 info rec.get("id");
 }

Failure response

  • The failure response will be returned in the following format:

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

Related Links