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

Curl Java PHP Csharp Python Node JS Ruby JavaScript

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);

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

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