Search Records in Zoho CRM V8

Table of Contents

Note:

  • Each time the zoho.crm.v8.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.crm.v8.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. 

Overview

The search task retrieves records from the specified Zoho CRM module that match the provided search criteria, with support for optional parameters to refine and narrow down the results.

Use Case Scenario

If you want to retrieve all records from a custom module where the Email field is john@zylker.com. This can be done using the searchRecords task by specifying the module name and the appropriate search criteria. The steps to implement this are explained below.

Syntax

<variable> = zoho.crm.v8.searchRecords(<module_name>, <criteria>, <page>, <per_page>, <search_value>, <connection>);

where:

ParameterData typeDescription
<variable> KEY-VALUEHolds the response returned by Zoho CRM on successful task execution or error details on failure.
<module_name>TEXTSpecifies the API name of the Zoho CRM module from where the records will be fetched.
<criteria> TEXT

A conditional statement to filter and search records.

Format : (<colName> : <operator> : <colValue>)

The <colName> stands for the CRM field label name and <colValue> stands for its respective value. The <operator> can contain the following:

  • equals
  • not_equal
  • starts_with

You can search for a maximum of 10 criteria (with same or different columns) in the format:

((<colName> : <operator> : <colValue>) and (<colName> : <operator> : <colValue>) ...)

Note: Records with null (empty) values in the specified field are not returned when using the not-equal operator.

<page>

(optional)

NUMBER

Indicates the page index from where the records must be fetched.

Default: 1.

<per_page>

(optional)

NUMBER

Specifies the number of records that need to be fetched per page.

Default: 200.

Note: The <page> parameter must be specified in order to use this parameter.

<search_value>

(optional)

KEY-VALUE

Specifies additional filtering options that can be applied along with the search criteria.

Applicable keys and values :

  • converted - To get the list of converted records. Applicable values for this key are:
    • true - get only converted records
    • false(default value) - get only non-converted records
    • both - get all records
  • approved - To get the list of approved records.
    • true(default value) - get only approved records
    • false - get only records which are not approved
    • both - get all records

Note: The <page> and <per_page> params must be specified to be able to specify this param.

<connection>TEXT

Represents the link name of the connection which is connected to your Zoho CRM account.

Note:

  • The connection parameter is mandatory for Zoho Cliq and optional for all other Zoho products with CRM integration tasks.
  • The <page>, <per_page>, and <search_value> params must be specified to be able to specify this param.
  • You can also connect to the Zoho CRM Sandbox while authorizing a connection.
  • Add relevant scopes as mentioned in Zoho CRM Search Records API document while creating the connection.
  • Refer to the list of Zoho services that support the connections page.

1. Search records with a specific email address in a Custom Module

Let's say we need to fetch all records having email address as john@zylker.com from a Custom Module named Prospects from outside Zoho CRM. To achieve this, add the following script on to the Deluge Editor from where you want to achieve this functionality.

response = zoho.crm.v8.searchRecords("Prospects", "(Email:equals:john@zylker.com)");

where,

response
is the variable which holds the response returned by Zoho CRM. It represents the values obtained from searchRecords task.
"Prospects"
is the TEXT that represents API name of Zoho CRM custom module where the records will be searched.
"(Email:equals:john@zylker.com)"
is the TEXT that represents the search criteria.

2. Search Accounts which start with a specific alphabet

Let's say we need to fetch all Accounts which start with the letter “A”. To achieve this, add the following script on to the Deluge Editor from where you want to achieve this functionality.

response = zoho.crm.v8.searchRecords("Accounts", "(Account_Name:starts_with:A)");

where,

response
is the variable which holds the response returned by Zoho CRM.
"Accounts"
is the TEXT that represents API name of Zoho CRM module, where the records will be searched.
"(Account_Name:starts_with:A)"
is the TEXT that represents the search criteria.

Response Format

Success Response

The response returned is of the following format:

{
 "Owner": {
  "name": "Shawn",
  "id": "692969000000282009"
 },
 "Ownership": "Partnership",
 "Description": "King is a multinational electronics contract manufacturing company with its headquarters in Baltimore, United States.",
 "$currency_symbol": "£",
 "Account_Type": "Vendor",
 "Rating": null,
 "SIC_Code": null,
 "Shipping_State": null,
 "$review_process": null,
 "Website": "http://kingmanufacturing.com",
 "Employees": 445,
 "Last_Activity_Time": "2019-09-20T16:59:22+05:30",
 "Industry": "Manufacturing",
 "Record_Image": "b83c03d938532192b2b1e89e164541660da18ff54eb02d513fa420f3eec0a20ad87455d88e1382a62f16aed03199b1efe35b3305b5722ae8dcc35564beb9a3688291ad96e07fef07b52ad1e9d23b6160",
 "Modified_By": {
  "name": "Shawn",
  "id": "692969000000282009"
 },
 "$review": null,
 "Account_Site": null,
 "$process_flow": false,
 "Phone": "555-555-5555",
 "Billing_Country": "United States",
 "Account_Name": "King (Sample)",
 "id": "692969000000284943",
 "Account_Number": "0",
 "$approved": true,
 "Ticker_Symbol": null,
 "$approval": {
  "delegate": false,
  "approve": false,
  "reject": false,
  "resubmit": false
 },
 "Modified_Time": "2019-09-20T16:59:22+05:30",
 "Billing_Street": "228 Runamuck Pl #2808",
 "Created_Time": "2019-09-20T16:58:48+05:30",
 "$editable": true,
 "Billing_Code": "21224",
 "Parent_Account": null,
 "Shipping_City": null,
 "Shipping_Country": null,
 "Shipping_Code": null,
 "Billing_City": "Baltimore",
 "Billing_State": "MD",
 "Tag": [
 
 ],
 "Created_By": {
  "name": "Shawn",
  "id": "692969000000282009"
 },
 "Fax": null,
 "Annual_Revenue": 850000,
 "Shipping_Street": null
}

To get the IDs of records returned, execute the following script:

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

Failure Response

Following error response is provided if the module name is supplied incorrectly:

{
 "code":"INVALID_MODULE",
 "details":{},
 "message":"the module name given seems to be invalid",
 "status":"error"
}

The following error response is returned if the search parameter is specified incorrectly:

{
 "code":"INVALID_QUERY",
 "details":
 {
  "reason":"invalid operator found",
  "api_name":"id",
  "operator":"="
 },
 "message":"invalid query formed",
 "status":"error"
}