Update Related Records Using External ID

Purpose

To update the related list records using external IDs.

Request Details

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{external_field_API_name/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
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 Java PHP Csharp Python Node JS Ruby JavaScript

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/extcontact3/Deals"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID,Deals.External_Deal_ID"
-d "@sample.json"

3.0.0

Copied//API Name of the module 
String 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 BodyWrapper Class that will contain the request body
BodyWrapper request = new BodyWrapper();

//List of Record instances
List < com.zoho.crm.api.record.Record > records = new ArrayList < com.zoho.crm.api.record.Record > ();

//Get instance of Record Class
com.zoho.crm.api.record.Record record1 = new com.zoho.crm.api.record.Record();

/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
record1.addKeyValue("id", "3477061000005919001");

record1.addKeyValue("list_price", 50.56);

//Add Record instance to the list
records.add(record1);

//Get instance of Record Class
com.zoho.crm.api.record.Record record2 = new com.zoho.crm.api.record.Record();

/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
 */
record2.addKeyValue("id", "3477061000005917011");

record2.addKeyValue("list_price", 50.56);

//Add Record instance to the list
records.add(record2);

//Set the list to Records in BodyWrapper instance
request.setData(records);

//Call updateRelatedRecords method that takes BodyWrapper instance as parameter.
APIResponse < ActionHandler > response = relatedRecordsOperations.updateRelatedRecords(request);

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 BodyWrapper Class that will contain the request body
$request = new BodyWrapper();
//List of Record instances
$records = array();
  //Get instance of Record Class
  $record1 = new Record();
   /*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
   * 2 -> Value
  */
 $record1->addKeyValue("id", "3477065919001");
$record1->addKeyValue("list_price", 50.56);
                //Add Record instance to the list
                array_push($records, $record1);
                //Get instance of Record Class
                $record2 = new Record();
                /*
                 * Call addKeyValue method that takes two arguments
                 * 1 -> A string that is the Field's API Name
                 * 2 -> Value
                 */
                $record2->addKeyValue("id", "3477061000005917011");
                $record2->addKeyValue("list_price", 50.56);
                //Add Record instance to the list
                array_push($records, $record2);
                //Set the list to Records in BodyWrapper instance
                $request->setData($records);
                //Call updateRecord method that takes BodyWrapper instance as parameter.
  $response = $relatedRecordsOperations->updateRelatedRecords($request);

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 BodyWrapper Class that will contain the request body
BodyWrapper request = new BodyWrapper();
//List of Record instances
List<API.Record.Record> records = new List<API.Record.Record>();
//Get instance of Record Class
API.Record.Record record1 = new API.Record.Record();
/*
* Call addKeyValue method that takes two arguments
* 1 -> A string that is the Field's API Name
* 2 -> Value
*/
record1.AddKeyValue("id", 3477065919001);
record1.AddKeyValue("list_price", 50.56);
//Add Record instance to the list
records.Add(record1);
//Get instance of Record Class
API.Record.Record record2 = new API.Record.Record();
/*
* Call addKeyValue method that takes two arguments
* 1 -> A string that is the Field's API Name
* 2 -> Value
*/
record2.AddKeyValue("id", 3477065917011);
record2.AddKeyValue("list_price", 50.56);
//Add Record instance to the list
records.Add(record2);
//Set the list to Records in BodyWrapper instance
request.Data = records;
//Call UpdateRelatedRecords method that takes BodyWrapper instance as parameter.
APIResponse<ActionHandler> response = relatedRecordsOperations.UpdateRelatedRecords(request);

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 BodyWrapper Class that will contain the request body
request = BodyWrapper()
# List to hold Record instances
records_list = []
# Get instance of Record Class
record_1 = Record()
"""
Call add_key_value method that takes two arguments
1 -> A string that is the Field's API Name
2 -> Value
"""
record_1.set_id(3409643000002414001)
record_1.add_key_value('list_price', 50.56)
# Add Record instance to the list
records_list.append(record_1)
# Get instance of Record Class
record_2 = Record()
"""
Call add_key_value method that takes two arguments
1 -> A string that is the Field's API Name
2 -> Value
"""
record_2.set_id(34096430000024140010)
record_2.add_key_value('list_price', 100.56)
# Add Record instance to the list
records_list.append(record_2)
# Set the list to Records in BodyWrapper instance
request.set_data(records_list)
# Call update_related_records method that takes BodyWrapper instance
response = related_records_operations.update_related_records(request)



# 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 BodyWrapper Class that will contain the request body
request = BodyWrapper()
# List to hold Record instances
records_list = []
# Get instance of Record Class
record = Record()
"""
Call add_key_value method that takes two arguments
1 -> A string that is the Field's API Name
2 -> Value
"""
record.add_key_value('list_price', 90.90)
# Add Record instance to the list
records_list.append(record)
# Set the list to Records in BodyWrapper instance
request.set_data(records_list)
# Call updateRelatedRecord method that takes BodyWrapper instance, related_list_id as parameter.
response = related_records_operations.update_related_record(related_list_id, request)

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

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 BodyWrapper Class that will contain the request body
bw = RelatedRecords::BodyWrapper.new
# List to hold Record instances
records = []
(0..1).each do |i|
  # Get instance of Record Class
  record = Record::Record.new

  # """
  # Call add_key_value method that takes two arguments
  # 1 -> A string that is the Field's API Name
  # 2 -> Value
  # """
  record.add_key_value('id', 3_524_033_000_005_948_003)
  record.add_key_value('Note_Content', i.to_s)
  # Add Record instance to the list
  records.push(record)
end
# Set the list to Records in BodyWrapper instance
bw.data = records
# Call update_related_records method that takes BodyWrapper instance
response = rro.update_related_records(bw)


# 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 BodyWrapper Class that will contain the request body
bw = RelatedRecords::BodyWrapper.new
# List to hold Record instances
records = []
(0..0).each do |i|
  # Get instance of Record Class
  record = Record::Record.new

  # """
  # Call add_key_value method that takes two arguments
  # 1 -> A string that is the Field's API Name
  # 2 -> Value
  # """
  record.add_key_value('id', 3_524_033_000_005_948_003)
  record.add_key_value('Note_Content', i.to_s)
  # Add Record instance to the list
  records.push(record)
end
# Set the list to Records in BodyWrapper instance
bw.data = records
# Call update_related_records method that takes BodyWrapper instance, related_record_id as parameter.
response = rro.update_related_record(related_record_id,bw)

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 400
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 400
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://www.zohoapis.com/crm/v2/Contacts/111111000000085009/Deals"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.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"
        }
    ]
}