Get Related Records Using External ID

Purpose

To get the related list records using external IDs.

Request Details

Request URL

{api-domain}/crm/v2/{module_api_name}/{external_value}/{related_list_api_name}

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, deals, contacts, accounts, products, campaigns, and pricebooks

Possible operation types

ALL - Full access to the related records
WRITE - Edit related records
GET - Fetch related records from the module

Fetching all related deals in the Contacts module

In this example, extcontact3 is the value of the external field External_Contact_ID in the Contacts module. We will reference this field's value to fetch the deals associated to this contact.

Sample Request

Curl JavaScript

Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/extcontact3/Deals"
-X GET
-H "Authorization: Zoho-oauthtoken 100xx.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

1.0.0

Copied//Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
let relatedRecordsOperations = new ZCRM.RelatedRecord.Operations(relatedListAPIName, recordId, moduleAPIName);
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters for Get Related Records operation */
await paramInstance.add(ZCRM.RelatedRecord.Model.GetRelatedRecordsParam.PAGE, 1);
await paramInstance.add(ZCRM.RelatedRecord.Model.GetRelatedRecordsParam.PER_PAGE, 200);
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
/* Possible headers for Get Related Records operation */
// await headerInstance.add(ZCRM.RelatedRecord.Model.GetRelatedRecordsHeader.IF_MODIFIED_SINCE, new Date('October 15, 2019 05:35:32'));
//Call getRelatedRecords method that takes ParameterMap instance and HeaderMap instance as parameter
let response = await relatedRecordsOperations.getRelatedRecords(paramInstance, headerInstance);






//Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
let relatedRecordsOperations = new ZCRM.RelatedRecord.Operations(relatedListAPIName, recordId, moduleAPIName);
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
/* Possible parameters for Get Related Record operation */
await headerInstance.add(ZCRM.RelatedRecord.Model.GetRelatedRecordHeader.IF_MODIFIED_SINCE, new Date('June 15, 2020 05:35:32'));
//Call getRelatedRecord method that takes headerInstance and relatedRecordId as parameter
let response = await relatedRecordsOperations.getRelatedRecord(relatedListId, headerInstance);

Sample Response

Copied{
    "data": [
        {
            "Contact_Role": "111111000000026002",
            "External_Deal_ID": "externaldeal3",
            "id": "111111000000094028"
        }
    ],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}

Fetching a related record through the external field's value of the related record

In this example, externaldeal3 is the value of the external field External_Deal_ID in the Deals module. We will reference this value to fetch this related deal from the contact whose external value is extcontact3.

Possible Errors

INVALID_DATAHTTP 400
You have specified an invalid external ID for the base module.
Resolution: Input the correct external ID.
NO_CONTENTHTTP 204
You have specified an invalid ID in the URL or in the "ids" parameter.
Resolution: Input valid IDs.

Sample Request

Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/extcontact3/Deals/externaldeal3"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Deals.External_Deal_ID,Contacts.External_Contact_ID"

Sample Respose

Copied{
    "data": [
        {
            "Contact_Role": "111111000000026002",
            "External_Deal_ID": "externaldeal3",
            "id": "111111000000094028"
        }
    ]
}