Get Related Records Using External ID

Purpose

To get the related list records using external IDs.

Request Details

Request URL

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

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, 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 Java PHP Csharp Python Node JS Ruby JavaScript

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/extcontact3/Deals"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

3.0.0

CopiedString moduleAPIName = "Leads";
Long recordId = 3477061000005177002l;
String relatedListAPIName = "Products";

//Get instance of RelatedRecordsOperations Class that takes relatedListAPIName, recordId and moduleAPIName as parameter
RelatedRecordsOperations relatedRecordsOperations = new RelatedRecordsOperations(relatedListAPIName, recordId, moduleAPIName);

//Get instance of ParameterMap Class
ParameterMap paramInstance = new ParameterMap();

paramInstance.add(GetRelatedRecordsParam.PAGE, 1);

paramInstance.add(GetRelatedRecordsParam.PER_PAGE, 2);

//Get instance of HeaderMap Class
HeaderMap headerInstance = new HeaderMap();

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

headerInstance.add(GetRelatedRecordsHeader.IF_MODIFIED_SINCE, startdatetime);

//Call getRelatedRecords method that takes paramInstance, headerInstance as parameter
APIResponse < ResponseHandler > response = relatedRecordsOperations.getRelatedRecords(paramInstance, headerInstance);

3.0.0

Copied//Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
$relatedRecordsOperations = new RelatedRecordsOperations( $relatedListAPIName,  $recordId,  $moduleAPIName);
//Get instance of ParameterMap Class
$paramInstance = new ParameterMap();
$paramInstance->add(GetRelatedRecordsParam::page(), 1);
$paramInstance->add(GetRelatedRecordsParam::perPage(), 2);
//Get instance of HeaderMap Class
$headerInstance = new HeaderMap();
$datetime = date_create("2019-02-26T15:28:34+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
$headerInstance->add(GetRelatedRecordsHeader::IfModifiedSince(), $datetime);
//Call getRelatedRecords method that takes paramInstance, headerInstance as parameter
$response = $relatedRecordsOperations->getRelatedRecords($paramInstance, $headerInstance);

3.0.0

Copied//Get instance of RelatedRecordsOperations Class that takes relatedListAPIName, recordId and moduleAPIName as parameter
RelatedRecordsOperations relatedRecordsOperations = new RelatedRecordsOperations(relatedListAPIName, recordId, moduleAPIName);
//Get instance of ParameterMap Class
ParameterMap paramInstance = new ParameterMap();
//Get instance of HeaderMap Class
HeaderMap headerInstance = new HeaderMap();
DateTimeOffset ifModifiedSince = new DateTimeOffset(new DateTime(2020, 05, 15, 12, 0, 0, DateTimeKind.Local));
headerInstance.Add(GetRelatedRecordsHeader.IF_MODIFIED_SINCE, ifModifiedSince);
//Call GetRelatedRecords method that takes paramInstance, headerInstance as parameter
APIResponse<ResponseHandler> response = relatedRecordsOperations.GetRelatedRecords(paramInstance, headerInstance);

3.0.0

Copied# Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
related_records_operations = RelatedRecordsOperations(related_list_api_name, record_id, module_api_name)
# Get instance of ParameterMap Class
param_instance = ParameterMap()
# Possible parameters for Get Related Records operation
param_instance.add(GetRelatedRecordsParam.page, 1)
param_instance.add(GetRelatedRecordsParam.per_page, 100)
# Get instance of HeaderMap Class
header_instance = HeaderMap()
# Possible headers for Get Related Records operation
# header_instance.add(GetRelatedRecordsHeader.if_modified_since, datetime.fromisoformat('2019-10-15T05:00:00+05:30'))
# Call getRelatedRecords method that takes ParameterMap instance and HeaderMap instance as parameter
response = related_records_operations.get_related_records(param_instance, header_instance)

1.0.0

Copied//Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
let relatedRecordsOperations = new RelatedRecordsOperations(relatedListAPIName, recordId, moduleAPIName);
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters for Get Related Records operation */
await paramInstance.add(GetRelatedRecordsParam.PAGE, 1);
await paramInstance.add(GetRelatedRecordsParam.PER_PAGE, 200);
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
/* Possible headers for Get Related Records operation */
await headerInstance.add(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);

2.0.0

Copied# Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
rro = RelatedRecords::RelatedRecordsOperations.new(related_list_api_name , record_id, module_api_name)
# Get instance of ParameterMap Class
pm = ParameterMap.new
# Possible parameters for Get Related Records operation
pm.add(RelatedRecords::RelatedRecordsOperations::GetRelatedRecordsParam.page, 1)
pm.add(RelatedRecords::RelatedRecordsOperations::GetRelatedRecordsParam.per_page, 1)
# Get instance of HeaderMap Class
hm = HeaderMap.new
# hm.add(RelatedRecords::GetRelatedRecordsHeader.If_modified_since,"")
# Call getRelatedRecords method that takes ParameterMap instance and HeaderMap instance as parameter
response = rro.get_related_records(pm, hm)



# Get instance of RelatedRecordsOperations Class that takes moduleAPIName, recordId and relatedListAPIName as parameter
rro = RelatedRecords::RelatedRecordsOperations.new(related_list_api_name , record_id, module_api_name)
# Get instance of HeaderMap Class
hm = HeaderMap.new
# Possible headers for Get Related Records operation
# hm.add(RelatedRecords::GetRelatedRecordsHeader.If_modified_since,"")
# Call getRelatedRecord method that takes header_instance and related_list_id as parameter
response = rro.get_related_record(related_record_id,hm)

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://www.zohoapis.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"
        }
    ]
}