Update Related Records Using External ID

Purpose

To update the related list records using external IDs.

Request Details

Request URL

{api-domain}/crm/v2/{module_api_name}/{external_field_API_name/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
UPDATE - Update related records in the module

Associating a Contact and a Deal using their external IDs

In this example, extcontact3 and extdeal3 are the values of the external fields External_Contact_ID and External_Deal_ID in the Contacts and Deals modules, respectively. We will reference these values to associate the contact with the deal.

Sample Request

Curl JavaScript

Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/extcontact3/Deals"
-X PUT
-H "Authorization: Zoho-oauthtoken 100xx.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID,Deals.External_Deal_ID"
-d "@sample.json"

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 BodyWrapper Class that will contain the request body
let request = new ZCRM.RelatedRecord.Model.BodyWrapper();
//Array to hold Record instances
let recordsArray = [];
//Get instance of Record Class
let record1 = new ZCRM.Record.Model.Record();
/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
record1.addKeyValue("id", 34770615917011n);
record1.addKeyValue("list_price", 50.56);
//Add Record instance to the array
recordsArray.push(record1);
let record2 = new ZCRM.Record.Model.Record();
/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
record2.addKeyValue("id", 34096432414001n);
record2.addKeyValue("list_price", 100.56);
//Add Record instance to the array
recordsArray.push(record2);
//Set the array to Records in BodyWrapper instance
request.setData(recordsArray);
//Call updateRelatedRecords method that takes BodyWrapper instance
let response = await relatedRecordsOperations.updateRelatedRecords(request);





//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 BodyWrapper Class that will contain the request body
let request = new ZCRM.RelatedRecord.Model.BodyWrapper();
//Array to hold Record instances
let recordsArray = [];
//Get instance of Record class
let record1 = new ZCRM.Record.Model.Record();
/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
record1.addKeyValue("list_price", 50.56);
//Add the record to array
recordsArray.push(record1);
//Set the array to data of BodyWrapper instance
request.setData(recordsArray);
//Call updateRelatedRecord method that takes BodyWrapper instance, relatedRecordId as parameter.
let response = await relatedRecordsOperations.updateRelatedRecord(relatedListId, request);

Sample Input

Copied{
    "data": [
        {
            "External_Deal_ID": "extdeal3",
            "Contact_Role": "111111000000026002"
        }
    ]
}

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "External_Deal_ID": "extdeal3",
                "id": "111111000000094028"
            },
            "message": "relation added",
            "status": "success"
        }
    ]
}

Associating a Contact and a Deal using the contact's record ID and the deal's external ID

In this example, extdeal2 is the value of the external field External_Deal_ID in the Deals module. We will use this value to associate it with the contact with the said record ID.

Note

You can also associate a contact and deal with the contact's external value in the URL, and the deal's record ID in the input.

Possible Errors

INVALID_DATAHTTP 202
The ID of the external field is invalid.
Resolution: Specify the correct external ID.
INVALID_DATAHTTP 400
You have specified an invalid external ID for the base module.
Resolution: Specify the correct external ID.
MANDATORY_NOT_FOUNDHTTP 202
You have specified the external ID in the header for the related module but not in the request body.
Resolution: It is mandatory to include the external field in the request body when you specify in the header.

Sample Request

Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/111111000000085009/Deals"
-X PUT
-H "Authorization: Zoho-oauthtoken 100xx.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Deals.External_Deal_ID"
-d "@sample.json"

Sample Input

Copied{
    "data": [
        {
            "Contact_Role": "111111000000026002",
            "External_Deal_ID": "extdeal3"
        }
    ]
}

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "External_Deal_ID": "extdeal3",
                "id": "111111000000094028"
            },
            "message": "relation added",
            "status": "success"
        }
    ]
}