Choose where you’d like to start

Search Records in Zoho CRM

Table of Contents

Overview

Imagine that a user wishes to search for records in a particular module in CRM with a specific criteria. And to add to it, the user wants to be able to get this information from outside Zoho CRM. This can be achieved using this task by supplying the module name, the search criteria and additional optional parameters to refine and narrow down the search results.

Use Case Scenario

Let's say we need to fetch all records having email id as john@zylker.com from a custom module. This can be achieved by using the searchRecords task with the specified criteria and module name. Further details on how to execute this task are explained below.

Syntax

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

where:

ParamsData TypeDescription

<variable> 

KEY-VALUE

specifies the response returned by Zoho CRM. It represents the values fetched against the API names of its respective fields.

<module_name>

TEXT

is the API name of the Zoho CRM module from where the records will be fetched.

<criteria> 

TEXT

is a conditional statement of the following 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
  • 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: If a column contains null values, zoho.crm.searchRecords DOES NOT report them in a <> statement.

<page>

(optional)

NUMBER

To get the list of records based on pages.

Default: 1.

<per_page>

(optional)

NUMBER

Used to get the list of records available per page.

Default: 200.

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

<search_value>

(optional)

KEY-VALUE

To search for records using parameters in addition to criteria. Applicable keys are:

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

(optional)

TEXT

is the name of the connection

Note:
  • The field <connection> is not applicable in Zoho Creator.
  • The <page>, <per_page>, and <search_value> params must be specified to be able to specify this param.

Example 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 CustomModule1 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.searchRecords("CustomModule1", "(Email:equals:john@zylker.com)");

where:

response
is the variable which will hold the response returned by Zoho CRM. It represents the values of the fetched records.
"CustomModule1"
is the TEXT that represents the label name of Zoho CRM custom module where the records will be searched.
"(Email:equals:john@zylker.com)"
is the TEXT that represents the criteria

Example 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.searchRecords("Accounts", "(Account_Name:starts_with:A)");

where,

response
is the variable which will hold the response returned by Zoho CRM. It represents the requested record details.
"Accounts"
is the TEXT that represents the label name of Zoho CRM module, where the records will be searched.
"(Account_Name:starts_with:A)"
is the TEXT that represents the 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"}

  • Following error response is provided if the search parameter is supplied incorrectly

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

Related Links

Get Started Now

Execute