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/{version}/{module_api_name}/upsert
Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Cases, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Appointments, Services 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, appointments, services 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
Copiedcurl "https://www.zohoapis.com/crm/v6/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"
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/v6/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/v6/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"
}
]
}