Skip to product menu
Zoho crm
Skip to main content
Zoho crm

Search Records Using External ID

Purpose

To retrieve the records that match your search criteria using external fields.

Request Details

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/search

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, Notes, and Activities

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

X-EXTERNAL: {module_API_name}.{external_field_API_name}

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
(and)
scope=ZohoSearch.securesearch.READ

Possible module names

leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, notes and activities

Possible operation types

ALL - Full access to the record
READ - Get records from the module

Using the external value and the "in" operator in "criteria"

  • Parameter:criteria=(External_Contact_ID:in:usercontact2,usercontact123)

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/search?criteria=(External_Contact_ID:in:usercontact2,usercontact123)&fields=External_Contact_ID,Email"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"
3.0.0
CopiedString moduleAPIName = "Leads";

//Get instance of RecordOperations Class
RecordOperations recordOperations = new RecordOperations();

ParameterMap paramInstance = new ParameterMap();

paramInstance.add(SearchRecordsParam.CRITERIA, "((Last_Name:starts_with:Last Name) and (Company:starts_with:fasf\\(123\\) K))");

paramInstance.add(SearchRecordsParam.EMAIL, "raja@gmail.com");

paramInstance.add(SearchRecordsParam.PHONE, "234567890");

paramInstance.add(SearchRecordsParam.WORD, "First Name Last Name");

paramInstance.add(SearchRecordsParam.CONVERTED, "both");

paramInstance.add(SearchRecordsParam.APPROVED, "both");

paramInstance.add(SearchRecordsParam.PAGE, 1);

paramInstance.add(SearchRecordsParam.PER_PAGE, 2);
HeaderMap headerInstance = new HeaderMap();
//Call searchRecords method that takes moduleAPIName and ParameterMap Instance as parameter
APIResponse < ResponseHandler > response = recordOperations.searchRecords(moduleAPIName, paramInstance,headerInstance);
3.0.0
Copied//Get instance of RecordOperations Class that takes moduleAPIName as parameter
 $recordOperations = new RecordOperations();
 $paramInstance = new ParameterMap();
 $paramInstance->add(SearchRecordsParam::criteria(), "((Last_Name:starts_with:Last Name) or (Company:starts_with:fasf\\(123\\) K))");
 $paramInstance->add(SearchRecordsParam::email(), "abc@xyz.com");
 $paramInstance->add(SearchRecordsParam::phone(), "234567890");
 $paramInstance->add(SearchRecordsParam::word(), "First Name Last Name");
 $paramInstance->add(SearchRecordsParam::converted(), "both");
 $paramInstance->add(SearchRecordsParam::approved(), "both");
  $paramInstance->add(SearchRecordsParam::page(), 1);
 $paramInstance->add(SearchRecordsParam::perPage(), 2);
$headerInstance = new HeaderMap();
//Call searchRecords method
$response = $recordOperations->searchRecords($moduleAPIName,$paramInstance,$headerInstance);
3.0.0
Copied//Get instance of RecordOperations Class
RecordOperations recordOperations = new RecordOperations();
ParameterMap paramInstance = new ParameterMap();
paramInstance.Add(SearchRecordsParam.CRITERIA, "((Last_Name:starts_with:Last Name) and (Company:starts_with:fasf\\(123\\) K))");
paramInstance.Add(SearchRecordsParam.EMAIL, "abc@zoho.com");
paramInstance.Add(SearchRecordsParam.PHONE, "234567890");
paramInstance.Add(SearchRecordsParam.WORD, "First Name Last Name");
paramInstance.Add(SearchRecordsParam.CONVERTED, "both");
paramInstance.Add(SearchRecordsParam.APPROVED, "both");
paramInstance.Add(SearchRecordsParam.PAGE, 1);
paramInstance.Add(SearchRecordsParam.PER_PAGE, 2);
HeaderMap headerInstance = new HeaderMap();
//Call SearchRecords method that takes moduleAPIName and ParameterMap Instance as parameter
APIResponse<ResponseHandler>response = recordOperations.SearchRecords(moduleAPIName, paramInstance,headerInstance);
3.0.0
Copied# Get instance of RecordOperations Class
record_operations = RecordOperations()
# Get instance of ParameterMap Class
param_instance = ParameterMap()
# Possible parameters for Search Records operation
param_instance.add(SearchRecordsParam.email, 'user@zoho.com')
param_instance.add(SearchRecordsParam.phone, '234567890')
param_instance.add(SearchRecordsParam.word, 'First Name Last Name')
param_instance.add(SearchRecordsParam.approved, 'both')
param_instance.add(SearchRecordsParam.converted, 'both')
param_instance.add(SearchRecordsParam.page, 1)
param_instance.add(SearchRecordsParam.per_page, 20)
# Encoding must be done for parentheses or comma
param_instance.add(SearchRecordsParam.criteria, '((Last_Name:starts_with:Last Name) and (Company:starts_with:fasf\\(123\\) K))')
header_instance = HeaderMap()
# Call searchRecords method that takes ParameterMap Instance and moduleAPIName as parameter
response = record_operations.search_records(module_api_name, param_instance,header_instance)
1.0.0
Copied//Get instance of RecordOperations Class
let recordOperations = new RecordOperations();
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters for Search Records operation */
await paramInstance.add(SearchRecordsParam.EMAIL, "abc@zoho.com");
await paramInstance.add(SearchRecordsParam.PHONE, "234567890");
await paramInstance.add(SearchRecordsParam.WORD, "First Name Last Name");
await paramInstance.add(SearchRecordsParam.CONVERTED, "both");
await paramInstance.add(SearchRecordsParam.APPROVED, "both");
await paramInstance.add(SearchRecordsParam.PAGE, 1);
await paramInstance.add(SearchRecordsParam.PER_PAGE, 2);
//Encoding must be done for parentheses or comma
await paramInstance.add(SearchRecordsParam.CRITERIA, "((Last_Name:starts_with:Last Name) or (Company:starts_with:fasf\\(123\\) K))");
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
//Call searchRecords method that takes ParameterMap Instance and moduleAPIName as parameter
let response = await recordOperations.searchRecords(moduleAPIName, paramInstance,headerInstance);
2.0.0
Copied# Get instance of RecordOperations Class
ro = Record::RecordOperations.new
# Get instance of ParameterMap Class
pm = ParameterMap.new
# record_id = 3524033000005495066
# Possible parameters for Search Records operation
# Encoding must be done for parentheses or comma
pm.add(Record::RecordOperations::SearchRecordsParam.criteria, 'Last_Name:starts_with:a')

# pm.add(Record::RecordOperations::GetRecordParam.converted,"false")
# field_names =["Company","Email"]
# field_names.each do |field_name|
# pm.add(Record::::RecordOperations::GetRecordParam.fields,field_name)
# end
# Get instance of HeaderMap Class
hm = HeaderMap.new
# Call searchRecords method that takes ParameterMap Instance and moduleAPIName as parameter
response = ro.search_records(module_api_name,pm,hm)
1.0.0
Copied//Get instance of RecordOperations Class
let recordOperations = new ZCRM.Record.Operations();
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters for Search Records operation */
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.EMAIL, "abc@gmail.com");
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.PHONE, "234567890");
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.WORD, "First Name Last Name");
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.CONVERTED, "both");
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.APPROVED, "both");
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.PAGE, 1);
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.PER_PAGE, 2);
//Encoding must be done for parentheses or comma
await paramInstance.add(ZCRM.Record.Model.SearchRecordsParam.CRITERIA, "((Last_Name:starts_with:Last Name) or (Company:starts_with:fasf\\(123\\) K))");
//Call searchRecords method that takes ParameterMap Instance and moduleAPIName as parameter
let response = await recordOperations.searchRecords(moduleAPIName, paramInstance);

Show full

Show less

Sample Response

Copied{
    "data": [
        {
            "Email": "crm@external1.com",
            "External_Contact_ID": "usercontact123",
            "id": "111111000000146004"
        },
        {
            "Email": "crm@external.com",
            "External_Contact_ID": "usercontact2",
            "id": "111111000000101018"
        }
    ],
    "info": {
        "per_page": 200,
        "count": 2,
        "page": 1,
        "more_records": false
    }
}

Show full

Show less

Using the external value and the "equals" operator in "criteria"

  • Parameter:criteria=(External_Contact_ID:equals:usercontact123)

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/search?criteria=(External_Contact_ID:equals:usercontact2)&fields=External_Contact_ID,Email"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

Sample Response

Copied{
    "data": [
        {
            "Email": "crm@external1.com",
            "External_Contact_ID": "usercontact123",
            "id": "111111000000146004"
        }
    ],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.