Get Records Using External ID

Purpose

To fetch the records in a module using external IDs.

Request Details

Request URL

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

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Meetings, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, 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}

Possible module names

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

Possible operation types

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

Sample Request

Curl Java PHP Csharp Python Node JS Ruby JavaScript

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/{external_field_value}"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: {base_module_API_name}.{external_field_API_name}"

3.0.0

CopiedString moduleAPIName = "Leads";

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

ParameterMap paramInstance = new ParameterMap();

paramInstance.add(GetRecordsParam.APPROVED, "both");
//		
//		paramInstance.add(GetRecordsParam.CONVERTED, "both");

//		paramInstance.add(GetRecordsParam.CVID, "3477061000000087501");

//		List<long> ids = new ArrayList<long>(Arrays.asList(3477061000005623115, 3477061000004352001));
//		
//		for(long id : ids)
//		{
//			paramInstance.add(GetRecordsParam.IDS, id);
//		}
//		
//		paramInstance.add(GetRecordsParam.UID, "3477061000005181008");
//		
//		List<String> fieldNames = new ArrayList<String>(Arrays.asList("Company", "Email"));
//		
//		for(String fieldName : fieldNames)
//		{
//			paramInstance.add(GetRecordsParam.FIELDS, fieldName);
//		}
//		
//		paramInstance.add(GetRecordsParam.SORT_BY, "Email");
//		
//		paramInstance.add(GetRecordsParam.SORT_ORDER, "desc");
//		
//		paramInstance.add(GetRecordsParam.PAGE, 1);
//		
//		paramInstance.add(GetRecordsParam.PER_PAGE, 1);

//		OffsetDateTime startdatetime = OffsetDateTime.of(2019, 11, 20, 10, 00, 01, 00, ZoneOffset.of("+05:30"));
//		
//		paramInstance.add(GetRecordsParam.STARTDATETIME, startdatetime);
//		
//		OffsetDateTime enddatetime = OffsetDateTime.of(2019, 12, 20, 10, 00, 01, 00, ZoneOffset.of("+05:30"));
//		
//		paramInstance.add(GetRecordsParam.ENDDATETIME, enddatetime);
//		
//		paramInstance.add(GetRecordsParam.TERRITORY_ID, "3477061000003051357");
//		
//		paramInstance.add(GetRecordsParam.INCLUDE_CHILD, true);

HeaderMap headerInstance = new HeaderMap();

OffsetDateTime ifmodifiedsince = OffsetDateTime.of(2019, 05, 20, 10, 00, 01, 00, ZoneOffset.of("+05:30"));

headerInstance.add(GetRecordsHeader.IF_MODIFIED_SINCE, ifmodifiedsince);

//Call getRecords method that takes moduleAPIName, paramInstance and headerInstance as parameter.
APIResponse < ResponseHandler > response = recordOperations.getRecords(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(GetRecordsParam::fields(), "id");
$paramInstance->add(GetRecordsParam::page(), 1);
$paramInstance->add(GetRecordsParam::perPage(), 3);
$startdatetime = date_create("2020-06-27T15:10:00+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
$headerInstance = new HeaderMap();
$response = $recordOperations->getRecords($moduleAPIName,$paramInstance, $headerInstance);

3.0.0

Copied//Get instance of RecordOperations Class
RecordOperations recordOperations = new RecordOperations();
//Get instance of ParameterMap Class
ParameterMap paramInstance = new ParameterMap();
//paramInstance.Add(GetRecordParam.APPROVED, "false");
//paramInstance.Add(GetRecordParam.CONVERTED, "false");
List<string> fieldNames = new List<string>() { "Company", "Email" };
foreach (string fieldName in fieldNames)
{
    paramInstance.Add(GetRecordParam.FIELDS, fieldName);
}
DateTimeOffset startdatetime = new DateTimeOffset(new DateTime(2020, 10, 15, 12, 0, 1, DateTimeKind.Local));
paramInstance.Add(GetRecordParam.STARTDATETIME, startdatetime);
DateTimeOffset enddatetime = new DateTimeOffset(new DateTime(2020, 11, 15, 12, 0, 1, DateTimeKind.Local));
paramInstance.Add(GetRecordParam.ENDDATETIME, enddatetime);
//paramInstance.Add(GetRecordParam.TERRITORY_ID, "3477061000003051357");
paramInstance.Add(GetRecordParam.INCLUDE_CHILD, "true");
HeaderMap headerInstance = new HeaderMap();
//DateTimeOffset ifmodifiedsince = new DateTimeOffset(new DateTime(2020, 05, 15, 12, 0, 0, DateTimeKind.Local));
//headerInstance.Add(GetRecordHeader.IF_MODIFIED_SINCE, ifmodifiedsince);
//Call getRecord method that takes recordID, moduleAPIName, paramInstance, and headerInstance  as parameter
APIResponse<ResponseHandler> response = recordOperations.GetRecord(recordId, moduleAPIName, paramInstance, headerInstance);

3.0.0

Copied# Get instance of RecordOperations Class
record_operations = RecordOperations()
# Get instance of ParameterMap Class
param_instance = ParameterMap()
ids = [3477061000005623115, 3477061000004352001]
# Possible parameters for Get Records operation
param_instance.add(GetRecordsParam.page, 1)
param_instance.add(GetRecordsParam.per_page, 120)
param_instance.add(GetRecordsParam.approved, 'both')
param_instance.add(GetRecordsParam.converted, 'both')
param_instance.add(GetRecordsParam.cvid, '3409643000000087501')
for each_id in ids:
    param_instance.add(GetRecordsParam.ids, each_id)
param_instance.add(GetRecordsParam.uid, '3409643000000302031')
field_names = ["Company", "Email"]
for field in field_names:
    param_instance.add(GetRecordsParam.fields, field)
param_instance.add(GetRecordsParam.sort_by, 'Email')
param_instance.add(GetRecordsParam.sort_order, 'desc')
start_date_time = datetime(2020, 1, 1, 0, 0, 0)
param_instance.add(GetRecordsParam.startdatetime, start_date_time)
end_date_time = datetime(2020, 7, 1, 0, 0, 0)
param_instance.add(GetRecordsParam.enddatetime, end_date_time)
param_instance.add(GetRecordsParam.territory_id, '3409643000000505351')
param_instance.add(GetRecordsParam.include_child, True)
# Get instance of HeaderMap Class
header_instance = HeaderMap()
# Possible headers for Get Records operation
header_instance.add(GetRecordsHeader.if_modified_since, datetime.fromisoformat('2020-01-01T00:00:00+05:30'))
# Call getRecords method that takes ParameterMap Instance, HeaderMap Instance and module_api_name as parameters
response = record_operations.get_records(module_api_name, param_instance, header_instance)




# Get instance of RecordOperations Class
record_operations = RecordOperations()
# Get instance of ParameterMap Class
param_instance = ParameterMap()
# Possible parameters for Get Record operation
param_instance.add(GetRecordParam.cvid, '3409643000000087501')
param_instance.add(GetRecordParam.approved, 'true')
param_instance.add(GetRecordParam.converted, 'both')
fields = ['id', 'company']
for field in fields:
    param_instance.add(GetRecordParam.fields, field)
start_date_time = datetime(2020, 1, 1, 10, 10, 10)
param_instance.add(GetRecordParam.startdatetime, start_date_time)
end_date_time = datetime(2020, 7, 7, 10, 10, 10)
param_instance.add(GetRecordParam.enddatetime, end_date_time)
param_instance.add(GetRecordParam.territory_id, '3409643000000505351')
param_instance.add(GetRecordParam.include_child, True)
param_instance.add(GetRecordParam.uid, '3409643000000500741')
# Get instance of HeaderMap Class
header_instance = HeaderMap()
# Possible headers for Get Record operation
header_instance.add(GetRecordHeader.if_modified_since, datetime.now())
# Call getRecord method that takes param_instance, header_instance, module_api_name and record_id as parameter
response = record_operations.get_record(module_api_name, record_id, 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 Get Records operation*/
await paramInstance.add(GetRecordsParam.APPROVED, "both");
await paramInstance.add(GetRecordsParam.CONVERTED, "both");
await paramInstance.add(GetRecordsParam.CVID, "3477061000000087501");
let ids = [3477061000005623115n, 3477061000004352001n];
for(let id of ids) {
    await paramInstance.add(GetRecordsParam.IDS, id);
}
await paramInstance.add(GetRecordsParam.UID, "3477061000005181008");
let fieldNames = ["Company", "Email"];
await paramInstance.add(GetRecordsParam.FIELDS, fieldNames.toString());
await paramInstance.add(GetRecordsParam.SORT_BY, "Email");
await paramInstance.add(GetRecordsParam.SORT_ORDER, "desc");
await paramInstance.add(GetRecordsParam.PAGE, 1);
await paramInstance.add(GetRecordsParam.PER_PAGE, 200);
let startDateTime = new Date(2020,1,10,10,10,10);
await paramInstance.add(GetRecordsParam.STARTDATETIME, startDateTime);
let endDateTime = new Date(2020,7,10,12,12,12);
await paramInstance.add(GetRecordsParam.ENDDATETIME, endDateTime);
await paramInstance.add(GetRecordsParam.TERRITORY_ID, "3409643000000505351");
await paramInstance.add(GetRecordsParam.INCLUDE_CHILD, "true");
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
/* Possible headers for Get Record operation*/
await headerInstance.add(GetRecordsHeader.IF_MODIFIED_SINCE, new Date("2020-01-01T00:00:00+05:30"));
//Call getRecords method that takes paramInstance, headerInstance and moduleAPIName as parameters
let response = await recordOperations.getRecords(moduleAPIName, paramInstance, headerInstance);

2.0.0

Copied# Get instance of RecordOperations Class
ro = Record::RecordOperations.new
# Get instance of ParameterMap Class
pm = ParameterMap.new
# module_api_name = "Leads"
# record_id = 3524033000005662018
# pm.add(Record::RecordOperations::GetRecordParam.approved,"false")
# 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
# hm.add(Record::RecordOperations::GetRecordHeader.If_modified_since,"")
# Call getRecord method that takes param_instance, header_instance, module_api_name and record_id as parameter
response = ro.get_record(record_id,module_api_name,pm, hm)


# Get instance of RecordOperations Class
ro = Record::RecordOperations.new
# Get instance of ParameterMap Class
pm = ParameterMap.new
# record_id = 3524033000005495066
# Add the per_page to ParameterMap instance
pm.add(Record::RecordOperations::GetRecordsParam.per_page, 1)
pm.add(Record::RecordOperations::GetRecordsParam.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
# hm.add(Record::RecordOperations::GetRecordHeader.If_modified_since,"")
# Call getRecords method that takes ParameterMap Instance, HeaderMap Instance and module_api_name as parameters
response = ro.get_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 Get Records operation*/
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.APPROVED, "both");
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.CONVERTED, "both");
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.CVID, "347706187501");
let ids = [34770615623115n, 34770614352001n];
for(let id of ids) {
    await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.IDS, id);
}
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.UID, "34770615181008");
let fieldNames = ["Company", "Email"];
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.FIELDS, fieldNames.toString());
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.SORT_BY, "Email");
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.SORT_ORDER, "desc");
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.PAGE, 1);
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.PER_PAGE, 200);
let startDateTime = new Date(2020,1,10,10,10,10);
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.STARTDATETIME, startDateTime);
let endDateTime = new Date(2020,7,10,12,12,12);
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.ENDDATETIME, endDateTime);
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.TERRITORY_ID, "3409643505351");
await paramInstance.add(ZCRM.Record.Model.GetRecordsParam.INCLUDE_CHILD, "true");
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
/* Possible headers for Get Record operation*/
await headerInstance.add(ZCRM.Record.Model.GetRecordsHeader.IF_MODIFIED_SINCE, new Date("2020-01-01T00:00:00+05:30"));
//Call getRecords method that takes paramInstance, headerInstance and moduleAPIName as parameters
let response = await recordOperations.getRecords(moduleAPIName);

Fetching a record through the external field's value

In this example, Contacts is the base module's API name, External_Contact_ID is the API name of the external field, and externalcontact1 is the value of the external field in this module.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/externalcontact1?fields=External_Contact_ID,Last_Name,First_Name,Full_Name,Account_Name,OrgExternal&per_page=2"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

Sample Response

Copied{
    "data": [
        {
            "First_Name": null,
            "Full_Name": "Test Contact 1",
            "Last_Name": "Test Contact 1",
            "External_Contact_ID": "externalcontact1",
            "Account_Name": {
                "name": "Test Account1",
                "id": "111111000000087057"
            },
            "id": "111111000000101004",
            "OrgExternal": "orgcontact1"
        }
    ]
}

Fetching the records using the "ids" parameter

In this example, Contacts is the base module's API name, External_Contact_ID is the API name of the external field. The "ids" parameter fetches the records with the external values externalcontact1 and externalcontact2.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts?ids=externalcontact1,externalcontact2&fields=External_Contact_ID,Last_Name,First_Name,Full_Name,Account_Name,OrgExternal&per_page=2"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

Possible Errors

NO_CONTENTHTTP 204
There is no data for the ID specified or there is no matching record in the given module.
Resolution: Create a record with the given external value.

Note

You cannot fetch records with respect to the external field value set by another user.
All parameters in the Get List of Records(without external ID) are supported here.

Sample Response

Copied{
    "data": [
        {
            "First_Name": null,
            "Full_Name": "Contact 2",
            "Last_Name": "Contact 2",
            "External_Contact_ID": "externalcontact2",
            "Account_Name": {
                "name": "Account 2",
                "id": "111111000000101039"
            },
            "id": "111111000000101018",
            "OrgExternal": "orgcontact2"
        },
        {
            "First_Name": null,
            "Full_Name": "Test Contact 1",
            "Last_Name": "Test Contact 1",
            "External_Contact_ID": "externalcontact1",
            "Account_Name": {
                "name": "Test Account1",
                "id": "111111000000087057"
            },
            "id": "111111000000101004",
            "OrgExternal": "orgcontact1"
        }
    ],
    "info": {
        "per_page": 2,
        "count": 2,
        "page": 1,
        "more_records": false
    }
}