Kaizen #56 - Upsert Records #API

Hello everyone!

Welcome back to another week of Kaizen.

In this post, we will discuss the Upsert Records API.

1. The purpose of upsert records API

Using the upsert records API, you can either insert or update records in a module. When you fire an upsert call, the system checks for duplicate records based on the duplicate check field's values. If the record is already present, it gets updated. If not, the record is inserted.

2. The duplicate check fields

There are two types of duplicate check fields:

2a. The system-defined duplicate check fields

These are the default unique fields. When you upsert a record, the system checks for duplicate entries in these fields.

Module-wise system-defined duplicate check fields

Module	System-defined duplicate check field
Leads	Email
Accounts	Account_Name
Contacts	Email
Deals	Deal_Name
Campaigns	Campaign_Name
Cases	Subject
Solutions	Solution_Title
Products	Product_Name
Vendors	Vendor_Name
PriceBooks	Price_Book_Name
Quotes	Subject
SalesOrders	Subject
PurchaseOrders	Subject
Invoices	Subject

2b. The user-defined unique fields

The fields for which "Do not allow duplicate values" is enabled. Click here to know more. Note that you can only set fields with the following field-types as unique— Single Line, Email, Phone, Number, Long Integer, and URL.

3. The duplicate_check_field array

You can set the order in which the system checks for duplicate records by specifying the duplicate_check_field array in the input. You can add only the system-defined duplicate check fields and user-defined unique fields to the duplicate_check_field array. For instance, in the example below, "Email" is the system-defined duplicate check field, and "Phone" and "Fax" are the user-defined unique fields for the Leads module.

"duplicate_check_fields": [

"Email",

"Phone",

"Fax"

]

If you do not specify the duplicate_check_field array, the system checks for duplicate records in the following order:

System-defined duplicate check fields
User-defined unique fields

4. How does duplicate check work?

Consider a case where the user has configured two unique fields unique1 and unique2 for a module (user-defined unique fields), and Email is a system-defined unique field.

The following table explains how the duplicate check happens for different user inputs to the duplicate_check_fields array.

User Input to the "duplicate_check_fields" Array	Duplicate Check Order
unique1	unique1, unique2
unique2	unique2, unique1
unique1, unique2	unique1, unique2
Email	Email, unique1, unique2
No input	System-defined duplicate check field for that module followed by unique fields. That is, Email, unique1, unique2

If you do not specify the system-defined duplicate check fields in the array, the system will ignore them and check only for user-defined unique fields.

5. Upserting a record via API

OAuth Scope

The scope to access the Deals module via API is:
ZohoCRM.modules.{module_api_name}.{operation_type}

The operation type can be ALL, WRITE, or CREATE.

Click here to know more about the scopes.

Request URL: {{api-domain}}/crm/v2/Leads/upsert

Request Method: POST

Sample Input

{

"data": [

{

"Last_Name": "Frey (Sample)",

"Email": "frey@sample.com",

"Company": "abc",

"Lead_Status": "Contacted"

{

"Last_Name": "New Lead",

"First_Name": "CRM Lead",

"Email": "newlead@zoho.com",

"Lead_Status": "Attempted to Contact",

"Mobile": "7685635434"

}

"duplicate_check_fields": [

"Email",

"Mobile"

]

}

Sample Response

Note:

You can insert or update a maximum of 100 records per API call.

We hope you found this post useful.

Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Topic Participants
Sneha Sridharan

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes