Upsert Records Using External ID

Purpose

To update existing records or insert new records in a module through an external field.

Request Details

Request URL

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

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Cases, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, and Custom

Possible operation types

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names

leads, accounts, contacts, deals, campaigns, cases, 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
CREATE - Create records in the module

Upserting a record when the external value is unique

Let us consider an example of an upsert request in the Contacts module. When the external field's value is unique, and if the other duplicate fields are checked, the system inserts the contact.

Sample Request

Curl Java PHP Csharp Python Node JS Ruby JavaScript

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"

3.0.0

Copied//API Name of the module to create records
String moduleAPIName = "Leads";

//Get instance of RecordOperations Class
RecordOperations recordOperations = new RecordOperations();

//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 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(Field.Leads.CITY, "City");

record1.addFieldValue(Field.Leads.LAST_NAME, "Last Name");

record1.addFieldValue(Field.Leads.FIRST_NAME, "First Name");

record1.addFieldValue(Field.Leads.COMPANY, "Company1");

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

record1.addKeyValue("Custom_field_2", "value");

//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 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(Field.Leads.CITY, "City");

record2.addFieldValue(Field.Leads.LAST_NAME, "Last Name");

record2.addFieldValue(Field.Leads.FIRST_NAME, "First Name");

record2.addFieldValue(Field.Leads.COMPANY, "Company12");

/*
 * 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 list
records.add(record2);

List < String > duplicateCheckFields = new ArrayList < String > (Arrays.asList("City", "Last_Name", "First_Name"));

request.setDuplicateCheckFields(duplicateCheckFields);

//Set the list to Records in BodyWrapper instance
request.setData(records);
HeaderMap headerInstance = new HeaderMap();
//Call upsertRecords method that takes moduleAPIName and BodyWrapper instance as parameter.
APIResponse < ActionHandler > response = recordOperations.upsertRecords(moduleAPIName, request,headerInstance);

3.0.0

Copied//Get instance of RecordOperations Class that takes moduleAPIName as parameter
$recordOperations = new RecordOperations();
//Get instance of BodyWrapper Class that will contain the request body
$request = new BodyWrapper();
//List of Record instances
$records = array();
$recordClass = 'com\zoho\crm\api\record\Record';
//Get instance of Record Class
$record1 = new $recordClass();
/*
 * 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
*/
$field = new Field("");
$record1->addFieldValue(Leads::City(), "City");
// $record1->addFieldValue(Leads::LastName(), "Last Name");
$record1->addFieldValue(Leads::FirstName(), "First Name");
$record1->addFieldValue(Leads::Company(), "Company1");
/*
 * Call addKeyValue method that takes two arguments
 * 1 -> A string that is the Field's API Name
 * 2 -> Value
*/
$record1->addKeyValue("Custom_field", "Value");
$record1->addKeyValue("Custom_field_2", "value");
//Add Record instance to the list
array_push($records, $record1);
//Get instance of Record Class
$record2 = new $recordClass();
/*
* 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(Leads::City(), "City");
// $record2->addFieldValue(Leads::LastName(), "Last Name");
$record2->addFieldValue(Leads::FirstName(), "First Name");
$record2->addFieldValue(Leads::Company(), "Company12");
/*
* 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 list
array_push($records, $record2);
$duplicateCheckFields = array("City", "Last_Name", "First_Name");
$request->setDuplicateCheckFields($duplicateCheckFields);
//Set the list to Records in BodyWrapper instance
$request->setData($records);
$headerInstance = new HeaderMap();
//Call createRecords method that takes BodyWrapper instance as parameter.
$response = $recordOperations->upsertRecords($moduleAPIName, $request,$headerInstance);

3.0.0

Copied//Get instance of RecordOperations Class
RecordOperations recordOperations = new RecordOperations();
//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 List<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 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(Leads.CITY, "City");
record1.AddFieldValue(Leads.LAST_NAME, "Last Name");
record1.AddFieldValue(Leads.FIRST_NAME, "First Name");
record1.AddFieldValue(Leads.COMPANY, "Company1");
/*
* Call addKeyValue method that takes two arguments
* 1 -> A string that is the Field's API Name
* 2 -> Value
*/
record1.AddKeyValue("Custom_field", "Value");
record1.AddKeyValue("Custom_field_2", "value");
//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 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(Leads.CITY, "City");
record2.AddFieldValue(Leads.LAST_NAME, "Last Name");
record2.AddFieldValue(Leads.FIRST_NAME, "First Name");
record2.AddFieldValue(Leads.COMPANY, "Company12");
/*
* 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 list
records.Add(record2);
List<string> duplicateCheckFields = new List<string>() { "City", "Last_Name", "First_Name" };
request.DuplicateCheckFields = duplicateCheckFields;
//Set the list to Records in BodyWrapper instance
request.Data = records;
HeaderMap headerInstance = new HeaderMap();
//Call upsertRecords method that takes moduleAPIName and BodyWrapper instance as parameter.
APIResponse<ActionHandler> response = recordOperations.UpsertRecords(moduleAPIName, request,headerInstance);

3.0.0

Copied# Get instance of RecordOperations Class
record_operations = RecordOperations()
# 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()
# Value to Record's fields can be provided in any of the following ways
"""
Call add_field_value method that takes two arguments
Import the zcrmsdk.src.com.zoho.crm.api.record.field file
1 -> Call Field "." and choose the module from the displayed list and press "." and choose the field name from the displayed list.
2 -> Value
"""
record_1.add_field_value(Field.Leads.last_name(), 'Python SDK')
record_1.add_field_value(Field.Leads.first_name(), 'New')
record_1.add_field_value(Field.Leads.company(), 'Zoho')
record_1.add_field_value(Field.Leads.city(), 'City')
"""
Call add_key_value method that takes two arguments
1 -> A string that is the Field's API Name
2 -> Value
"""
record_1.add_key_value('Custom_field', 'Value')
record_1.add_key_value('Custom_field_2', 12)
# Add Record instance to the list
records_list.append(record_1)
# Get instance of Record Class
record_2 = Record()
# Value to Record's fields can be provided in any of the following ways
"""
Call add_field_value method that takes two arguments
Import the zcrmsdk.src.com.zoho.crm.api.record.field file
1 -> Call Field "." and choose the module from the displayed list and press "." and choose the field name from the displayed list.
2 -> Value
"""
record_2.add_field_value(Field.Leads.last_name(), 'Boyle')
record_2.add_field_value(Field.Leads.first_name(), 'Patricia')
record_2.add_field_value(Field.Leads.company(), 'Law')
record_2.add_field_value(Field.Leads.city(), 'Man')
"""
Call add_key_value method that takes two arguments
1 -> A string that is the Field's API Name
2 -> Value
"""
record_2.add_key_value('Custom_field', 'Value')
record_2.add_key_value('Custom_field_2', 12)
# Add Record instance to the list
records_list.append(record_2)
# Set the list to data in BodyWrapper instance
request.set_data(records_list)
duplicate_check_fields = ["City", "Last_Name", "First_Name"]
# Set the array containing duplicate check fields to BodyWrapper instance
request.set_duplicate_check_fields(duplicate_check_fields)
# Get instance of HeaderMap Class
header_instance = HeaderMap()
# Call upsertRecords method that takes BodyWrapper instance and module_api_name as parameters.
response = record_operations.upsert_records(module_api_name, request,header_instance)

1.0.0

Copied//Get instance of RecordOperations Class that takes moduleAPIName as parameter
let recordOperations = new RecordOperations();
//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 addFieldValue method that takes two arguments
 * Import the "zcrmsdk/core/com/zoho/crm/api/record/field" file
 * 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(Field.Leads.CITY, "City");
record1.addFieldValue(Field.Leads.LAST_NAME, "Last Name");
record1.addFieldValue(Field.Leads.FIRST_NAME, "First Name");
record1.addFieldValue(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);
//Add the record to array
recordsArray.push(record1);
let record2 = new Record();
/*
 * 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(Field.Leads.CITY, "City");
record2.addFieldValue(Field.Leads.LAST_NAME, "Last Name");
record2.addFieldValue(Field.Leads.FIRST_NAME, "First Name");
record2.addFieldValue(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 the record to array
recordsArray.push(record2);
//Set the array to data in BodyWrapper instance
request.setData(recordsArray);
let duplicateCheckFields = ["City", "Last_Name", "First_Name"];
//Set the array containing duplicate check fiels to BodyWrapper instance
request.setDuplicateCheckFields(duplicateCheckFields);
//Get instance of HeaderMap Class
let headerInstance = new HeaderMap();
//Call upsertRecords method that takes BodyWrapper instance and moduleAPIName as parameter.
let response = await recordOperations.upsertRecords(moduleAPIName, request,headerInstance);

2.0.0

Copied# List to hold Record instances
records = []
# Get instance of Record Class
record = Record::Record.new
# """
# Call add_field_value 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
# """
if module_api_name.downcase == 'Leads'.downcase
  record.add_field_value(Record::Field::Leads.Last_name, 'asdad')
  record.add_field_value(Record::Field::Leads.City, 'City')
  record.add_field_value(Record::Field::Leads.First_name, 'First Name')
  record.add_field_value(Record::Field::Leads.Company, 'KKRNP')
end

# file = Record::FileDetails.new
# file.file_id = "f46166fa14ce16c6e2622b3ce82830759c6334275dc8a317539bbda39a6ca056"
# files = [file]

# """
# Call add_key_value method that takes two arguments
# 1 -> A string that is the Field's API Name
# 2 -> Value
# """

if module_api_name == 'Contacts'
  file_details = []

  file_detail =  Record::FileDetails.new

  file_detail.file_id = '479f0f5eebf0fb982f99e3832b35d23e29f67c2868ee4c789f22579895383c8'

  file_details.push(file_detail)

  record.add_key_value('File_Upload_1', file_details)
end

# """
# Following methods are being used only by Inventory modules
# """
if %w[Quotes Sales_Orders Purchase_Orders Invoices].include? module_api_name
  line_item_product = Record::LineItemProduct.new
  line_item_product.id = 3_477_061_000_005_356_009
  inventory_line_item = Record::InventoryLineItems.new
  inventory_line_item.product = line_item_product
  inventory_line_item.list_price = 10.0
  inventory_line_item.discount = '5.0'
  inventory_line_item.quantity = 123.2
  line_tax = Record::LineTax.new
  line_tax.name = 'Tax1'
  line_tax.percentage = 20.0
  line_taxes = [line_tax]
  inventory_line_item.line_tax = line_taxes
  inventory_line_items = [inventory_line_item]
  record.add_key_value('Product_Details', inventory_line_items)
  record.add_key_value('Subject', 'asd')
end


if module_api_name == 'Price_Books'
  pricing_detail_record = Record::PricingDetails.new
  pricing_detail_record.from_range = 1.0
  pricing_detail_record.to_range = 1.0
  pricing_detail_record.discount = 1.0
  pricing_detail_records = [pricing_detail_record]
  record.add_key_value('Price_Book_Name', 'assd')
  record.add_field_value(Record::Field::Price_Books.Pricing_details, pricing_detail_records)
  record.add_field_value(Record::Field::Price_Books.Pricing_model, Util::Choice.new('Flat'))
end
# # Get instance of BodyWrapper Class that will contain the request body
records.push(record)
trigger = []
trigger.push('approval')

trigger.push('workflow')

trigger.push('blueprint')
# Get instance of BodyWrapper Class that will contain the request body
body_wrapper = Record::BodyWrapper.new
# Set the list to data in BodyWrapper instance
body_wrapper.data = records
# Set the lar_id in BodyWrapper instance
body_wrapper.lar_id = '213123131'
#set trigger
body_wrapper.trigger = trigger
process = ['review_process']
body_wrapper.process = process
# Get instance of RecordOperations Class
rr = Record::RecordOperations.new
# Get instance of HeaderMap Class
hm = HeaderMap.new
# Call upsertRecords method that takes BodyWrapper instance and module_api_name as parameters.
response = rr.upsert_records(module_api_name,body_wrapper,hm)

1.0.0

Copied//Get instance of RecordOperations Class that takes moduleAPIName as parameter
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 = [];
//Get instance of Record Class
let record1 = new ZCRM.Record.Model.Record();
/*
 * Call addFieldValue method that takes two arguments
 * Import the "zcrmsdk/core/com/zoho/crm/api/record/field" file
 * 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);
//Add the record to array
recordsArray.push(record1);
let record2 = new ZCRM.Record.Model.Record();
/*
 * 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 the record to array
recordsArray.push(record2);
//Set the array to data in BodyWrapper instance
request.setData(recordsArray);
let duplicateCheckFields = ["City", "Last_Name", "First_Name"];
//Set the array containing duplicate check fiels to BodyWrapper instance
request.setDuplicateCheckFields(duplicateCheckFields);
//Call upsertRecords method that takes BodyWrapper instance and moduleAPIName as parameter.
let response = await recordOperations.upsertRecords(moduleAPIName, request);

Sample Input

Copied{
    "data": [
        {
            "Last_Name": "Boyle",
            "External_Contact_ID": "Boyle1"
        }
    ]
}

Upserting a record through the external value

When you pass the external value in the request, and if that external value exists in the record of a module, the system updates that record with the other details in the input. Otherwise, the system inserts a records in that module.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"

Sample Input

Copied{
    "data": [
        {
            "Last_Name": "Boyle P",
            "External_Contact_ID": "Boyle1",
            "Email": "p.boyle@abc.com"
        }
    ]
}

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "duplicate_field": "External_Contact_ID",
            "action": "update",
            "details": {
                "Modified_Time": "2019-12-23T16:39:18+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "111111000000044700"
                },
                "Created_Time": "2019-12-23T16:39:18+05:30",
                "id": "111111000000157039",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "111111000000044700"
                }
            },
            "message": "record updated",
            "status": "success"
        }
    ]
}

Upserting the external field using the system-defined duplicate check field

In this example, a new external value is passed to the external field External_Contact_ID in the Contacts module. Now, the system checks for the system-defined duplicate check field "Email". If that email ID exists for a contact, the system updates that contact with the new value for the external field.

Duplicate check for Org-based external ID fields
Consider there is an external field "External_Campaign_ID" in the Contacts module that holds the value of the Campaign in a third-party app. User1 creates a record in the contacts modules and sets the value of this external field as "Camp_MailChimp_1". Now, when user2 tries to create a record with the same value for the external field, the system throws the DUPLICATE_DATA error.
Duplicate check for User-based external ID fields
Consider there is an external field "External_Contact_ID" in the Contacts module. User1 creates a record with the value "Contact1" for this record. Now, when the same user performs an upsert operation referencing this external field, the system checks if there are any records created by user1 that contain the value "Contact1" for the external field. If there is a matching record, the system will update the record. If there is no matching record, the system creates one with the given data.
You need not provide the X-EXTERNAL header for the upsert API, as the system considers the external field as unique and considers it for performing duplicate check.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"

Sample Input

Copied{
    "data": [
        {
            "Last_Name": "Boyle P",
            "External_Contact_ID": "Boyle123",
            "Email": "p.boyle@abc.com"
        }
    ]
}

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "duplicate_field": "Email",
            "action": "update",
            "details": {
                "Modified_Time": "2019-12-23T16:39:18+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "111111000000044700"
                },
                "Created_Time": "2019-12-23T16:39:18+05:30",
                "id": "111111000000157040",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "111111000000044700"
                }
            },
            "message": "record updated",
            "status": "success"
        }
    ]
}