Upsert Record in Zoho CRM V8

Table of Contents

Note:

  • Each time the zoho.crm.v8.upsert integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.crm.v8.upsert integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

The zoho.crm.v8.upsert task checks whether a record already exists in the specified Zoho CRM module by using a unique 
identifier field value provided in the request. If a matching record exists, it updates the existing record. Else, the upsert task creates a new record with the given values.

How to define a unique identifier

A unique identifier determines how Zoho CRM identifies an existing record during an upsert operation. A field can be configured as a unique identifier in the following ways:

System-Defined duplicate check (Default)

Some modules in Zoho CRM have predefined duplicate-check fields set by the system. For example, in the Leads module, the Email field acts as a default duplicate-check field.

Manually configured unique field in Zoho CRM

A field can be configured as a unique identifier by enabling the "Do not allow duplicate values" property in the field settings 
within Zoho CRM. Once enabled, Zoho CRM ensures that only one record can exist with a given value for that field. During upsert, this field will be used as unique identifier.

Specified in the upsert Task syntax

A field can also be designated as the unique identifier directly in the upsert task by using the duplicate_check_fields parameter in the syntax.

In all the above cases, the corresponding field value must be provided in the <values> parameter so that Zoho CRM can compare it against existing records.

Example:

if "Email" is set as the duplicate-check field and "john@zylker.com" is provided as the value for the field, the upsert task searches for the a record with the same email ID. If an existing record with same email ID is identified, then upsert task, updates the values of that record. If no record is found, then upsert task creates a new record with the provided values.

Syntax

<variable> = zoho.crm.v8.upsert(<module>,<values>,<duplicate_check>,<connection>);

where,

ParameterData typeDescription
<variable>KEY-VALUEHolds the response returned by Zoho CRM on successful task execution or error details on failure.
<module>TEXTSpecifies the API name of the module in which the record needs to be created or updated.
<values>KEY-VALUE

Represents the input collection (key–value pairs) where each key is a Zoho CRM field's API name mapped to the corresponding value to be inserted into that field.

Unique field's values must be specified here to identify any existing records and upsert the data.

Note: Each module in Zoho CRM contains mandatory fields that are required to create a record. Refer to this page for the list of mandatory fields in each module.

<duplicate_check>

(Optional)

KEY-VALUE

Specifies the API names of the fields that will act as the unique identifier to check for existing records during the upsert operation.

If <duplicate_check> parameter is not specified in the task, then system defined or manually configured duplicate check fields in Zoho CRM will be used to find and update existing record data.

<connection>TEXT

Represents the link name of the connection which is connected to your Zoho CRM account.

Note:


Tip: If multiple records share the same identifier value, the upsert operation may update any one of the matching records. To ensure predictable behaviour, the identifier field should be unique for each record.

For example, if "Last_Name" is specified as the only unique identifier and three records have the same last name, any one of those records will be updated by the upsert task. However, if fields such as "Email" or "Phone" are designated as unique identifiers, only one record can exist with a given email address or phone number, ensuring that the correct record is updated.

Examples

1. Check for existing Leads with specified Email ID and update the contact details.

The following script creates a new record in the module - Leads.

record_values = Collection();
record_values.insert("Last_Name":"Mark");
record_values.insert("Company":"Zylker");
record_values.insert("Email":"john@zylker.com");
duplicate_check = Collection();
duplicate_check.insert("duplicate_check_fields": {"Email"});
response = zoho.crm.v8.upsert("Leads",record_values,duplicate_check,"crm");

where,

response
is the variable which holds the response returned by Zoho CRM.
"Leads"
is the TEXT that represents the name of the module in which the record needs to be upserted.
record_values
is the collection that holds the values of the record to be updated or created.
"Last_Name"
"Company"
"Email"
are the API names of the Zoho CRM fields.
duplicate_check
is a key-value variable that holds the fields that are used as unique identifiers in the upsert task.
"duplicate_check_fields"
is the key parameter which is mapped to the unique identifier fields.

2. Create a new record with Upsert

The following script creates a record with mentioned values, in the module - Leads.

record_values = Collection();
record_values.insert("Last_Name":"John");
record_values.insert("First_Name":"Little");
record_values.insert("Company":"Zylker");
response = zoho.crm.v8.upsert("Leads",record_values);

where,

"Last_Name"
"Company"
"First_Name"
are the API names of the Zoho CRM fields.
"Leads"
is the TEXT that represents the name of the module in which the record needs to be upserted.
record_values
is the collection that holds the values of the record to be updated or created.

Here, no duplicate-check field is provided in the upsert syntax or manually configured in Zoho CRM. For the Leads module, "Email" is the system-defined duplicate-check field. However, since no Email value is provided in the task to verify against existing records, no duplicate check is performed and so, a new record is created.

Note: Refer this page for the instructions to get API names of the CRM modules and fields.

Response Format

Success Response

  • The success response returned on upserting an existing record is of the following format
{
 "Modified_Time":"2018-12-11T12:15:02+05:30",
 "Modified_By":{"name":"John","id":"2303XXXXXXXXXX"},
 "Created_Time":"2018-12-06T19:01:45+05:30",
 "id":"2303XXXXXXXXXX",
 "Created_By":{"name":"John","id":"2303XXXXXXXXXX"}
}


Failure Response

  • The failure response returned for incorrect or non-existent module is of the following format.
{
 "code": "INVALID_MODULE",
 "details": {
  "resource_path_index": 0
 },
 "message": "the module name given seems to be invalid",
 "status": "error"
}