Update Records Using External ID
Purpose
To update existing records in a module through an external field.
Request Details
Request URL
{api-domain}/crm/v2/{module_api_name}/{external_field_value}
Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, and Activities
Possible operation types
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, custom, and notes
Possible operation types
ALL - Full access to the record
WRITE - Edit records in the module
UPDATE - Update records in the module
Updating a record through the value of the external field in the module
Let us consider an example of updating a record in the Contacts module. Instead of passing the record ID of the contact in the subscriber org, you can pass the external field's value in that module and update the record.
Sample Request
Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/extcont1234"
-X PUT
-H "Authorization: Zoho-oauthtoken 100xx.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"
-d "@sample.json"Copied//Get instance of RecordOperations Class
let recordOperations = new ZCRM.Record.Operations();
//Get instance of BodyWrapper Class that will contain the request body
let request = new ZCRM.Record.Model.BodyWrapper();
//Array to hold Record instances
let recordsArray = [];
let record1 = new ZCRM.Record.Model.Record();
//ID of the record to be updated
record1.setId(34770619074373n);
/*
* Call addFieldValue method that takes two arguments
* 1 -> Call Field "." and choose the module from the displayed list and press "." and choose the field name from the displayed list.
* 2 -> Value
*/
record1.addFieldValue(ZCRM.Record.Model.Field.Leads.CITY, "City");
record1.addFieldValue(ZCRM.Record.Model.Field.Leads.LAST_NAME, "Last Name");
record1.addFieldValue(ZCRM.Record.Model.Field.Leads.FIRST_NAME, "First Name");
record1.addFieldValue(ZCRM.Record.Model.Field.Leads.COMPANY, "KKRNP");
/*
* Call addKeyValue method that takes two arguments
* 1 -> A string that is the Field's API Name
* 2 -> Value
*/
record1.addKeyValue("Custom_field", "Custom val");
record1.addKeyValue("Custom_field_2", 10);
//Used when GDPR is enabled
let dataConsent = new ZCRM.Record.Model.Consent();
dataConsent.setConsentRemarks("Approved.");
dataConsent.setConsentThrough("Email");
dataConsent.setContactThroughEmail(true);
dataConsent.setContactThroughSocial(false);
record1.addKeyValue("Data_Processing_Basis_Details", dataConsent);
recordsArray.push(record1);
let record2 = new ZCRM.Record.Model.Record();
//ID of the record to be updated
record2.addFieldValue(ZCRM.Record.Model.Field.Leads.ID, 34096431881002n);
/*
* Call addFieldValue method that takes two arguments
* 1 -> Call Field "." and choose the module from the displayed list and press "." and choose the field name from the displayed list.
* 2 -> Value
*/
record2.addFieldValue(ZCRM.Record.Model.Field.Leads.CITY, "City");
record2.addFieldValue(ZCRM.Record.Model.Field.Leads.LAST_NAME, "Last Name");
record2.addFieldValue(ZCRM.Record.Model.Field.Leads.FIRST_NAME, "First Name");
record2.addFieldValue(ZCRM.Record.Model.Field.Leads.COMPANY, "KKRNP");
/*
* Call addKeyValue method that takes two arguments
* 1 -> A string that is the Field's API Name
* 2 -> Value
*/
record2.addKeyValue("Custom_field", "Value");
record2.addKeyValue("Custom_field_2", "value");
//Add Record instance to the array
recordsArray.push(record2);
//Set the array to data in BodyWrapper instance
request.setData(recordsArray);
let trigger = [];
trigger.push("approval");
trigger.push("workflow");
trigger.push("blueprint");
//Set the array containing the trigger operations to be run
request.setTrigger(trigger);
//Call updateRecords method that takes BodyWrapper instance and moduleAPIName as parameter.
let response = await recordOperations.updateRecords(moduleAPIName, request);Sample Input
Copied{
"data": [
{
"Last_Name": "Test Contact 1"
}
]
}Sample Response
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-19T19:06:00+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-13T22:07:07+05:30",
"External_Contact_ID": "extcont1234",
"id": "111111000000138036",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}Updating a record through the external value of a lookup record in that module
In this example, Contacts is the base module and contains an account lookup field Account_Name. To update a record in the Contacts module, you must specify the external field's API name and its value in the Accounts module, and the external field's API name and its value in the Contacts module.
Sample Request
Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID, Contacts.Account_Name.External_Account_ID"
-d "@sample.json"Sample Input
Copied{
"data": [
{
"External_Contact_ID": "extcontact1",
"Account_Name": {
"External_Account_ID": "extaccount1"
}
}
]
}Sample Response
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-19T19:09:48+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-04T00:08:05+05:30",
"External_Contact_ID": "extcontact1",
"id": "111111000000101004",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}Updating an inventory module's record with external fields in the line items
In this example, Quotes is the base module. To update the details in the Product_Details section, specify the external field's API name and the value in the product and book JSON objects.
Sample Request
Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Quotes/quote1"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Quotes.Product_Details.product.External_Product_ID, Quotes.Product_Details.book.External_Price_book_ID"
-d "@sample.json"Sample Input
Copied{
"data": [
{
"Product_Details": [
{
"id": "111111000000133071"
},
{
"product": {
"External_Product_ID": "12345678900"
},
"book": {
"External_Pricebook_ID": "pricebook2"
},
"quantity": 20
}
]
}
]
}Sample Response
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-20T12:29:49+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-12T23:32:49+05:30",
"External_Quote_ID": "quote1",
"id": "111111000000133069",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}Updating a subform lookup record through an external field in the associated module
Specify the external field's API name and its value in the lookup field JSON object of the Subform.
Possible Errors
- INVALID_DATAHTTP 202
The value of the external field is invalid.
Resolution: Specify the correct external value. - INVALID_DATAHTTP 202
The value of the external field is invalid for the lookup field.
Resolution: Specify the correct external value. - INVALID_DATAHTTP 202
The system expects product IDs in the input when you do not specify the external field header.
Resolution: Include the correct external header when you use external fields in your request. - NOT_ALLOWEDHTTP 202
You cannot update the external field using its own primary key in the request. For example, if extcontact1 is the value of the external field External_Contact_ID, then you cannot update the external field's value using itself (crm/v2/Contacts/extcontact1).
Resolution: Use another external field or CRM's primary key to update an external field.
Sample Request
Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/Contacts/extcontact2"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID,Contacts.Subform_External.Deal_Lookup.External_Deal_ID"
-d "@sample.json"Sample Input
Copied{
"data": [
{
"Subform_External": [
{
"Deal_Lookup": {
"External_Deal_ID": "userdeal1"
}
}
]
}
]
}Sample Response
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-20T12:30:59+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-13T22:07:07+05:30",
"External_Contact_ID": "extcontact2",
"id": "111111000000138036",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}