Get Records Using External ID

Purpose

To fetch the records in a module using external IDs.

Endpoints

Request Details

Request URL

{api-domain}/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 100xx.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 JavaScript

Copiedcurl "https://zylkercorp.zohoplatform.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}"

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://zylkercorp.zohoplatform.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://zylkercorp.zohoplatform.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
    }
}