Kaizen #177: Duplicate Check Preferences API vs. Upsert API
Hello all!!!
Welcome back to another week of Kaizen. Last week, we discussed Optimizing the Use of Record ID Variables in Zoho CRM Queries.
This week, we will explore two important APIs for managing duplicate records in Zoho CRM - Duplicate Check Preferences API and Upsert Records API. While both of these APIs help manage duplicate records, they serve different purposes and are to be used in different scenarios.
This post covers:
- What is the Duplicate Check Preferences API?
- Use Case
- Duplicate Check Configurations
- Updating Duplicate Check Configuration
- How Duplicate Check Preferences Work During Record Creation/Update?
- What is the Upsert API?
- Use Case
- Differences between Duplicate Check Preferences API and Upsert API
What is the Duplicate Check Preferences API
The Duplicate Check Preferences API is a configuration API that allows you to set up criteria using unique fields to manage duplicates across Leads module including Converted Leads and Contacts
in Zoho CRM. Based on the given criteria, the system will restrict the creation or update of duplicate records. For example, if the Phone field is marked as unique and set for duplicate checks, the system will make sure that no two records have the same phone number during records creation or update.
in Zoho CRM. Based on the given criteria, the system will restrict the creation or update of duplicate records. For example, if the Phone field is marked as unique and set for duplicate checks, the system will make sure that no two records have the same phone number during records creation or update.
With the Duplicate Check Preferences API, you can define criteria to find duplicates, such as matching email addresses, phone numbers, or custom fields. During record creation or update, Zoho CRM checks the configured criteria against converted leads or contacts. If a match is found, it triggers a "DUPLICATE_DATA" error and blocks duplicates based on your configuration.
By default, the Insert Records API and Update Records API automatically check for this configuration. If a record matches the defined duplicate criteria, the system prevents its creation or update.
Use case
Zylker, a sales team managing customer contacts in Zoho CRM, often imports leads from various sources like website forms, events, and campaigns. However, the team noticed that many duplicate contacts are being created because the same phone number is associated with some of the contacts. This creates confusion and results in redundant work in their sales process.
By using the Duplicate Check Preferences API, Zylker can prevent the anymore duplicate contacts based on phone numbers (phone is used for an example).
Duplicate Check Configurations
In Zoho CRM, you can configure duplicate check preferences via API in two ways.
i. Configuration in Leads module
The system checks for duplicates on all the Leads using the specified unique fields. By selecting this option, the duplicates will be checked on all the Converted Leads (custom view) as well. This configuration is applicable across all the layouts.
The following is the configuration for duplicate check in the Leads module via API.
The following is the configuration for duplicate check in the Leads module via API.
Request Method: POST
Note:
- The "module" parameter is mandatory, and its supported value is Leads.
- The above URL applies to both Leads and Contacts module configurations.
- You must mark at least one field as mandatory. So, the system can check for duplicates based on the value in the unique field within the Leads module when creating a record.
Input JSON
{ "duplicate_check_preference": { "type": "converted_records", //Converted Leads custom view in Leads module } } |
Response
{ "duplicate_check_preference": { "code": "SUCCESS", "details": {}, "message": "Duplicate check enabled for converted_records successfully.", "status": "success" } } |
ii. Configuration in Contacts module
By selecting this option, the system will check for duplicates in the Contacts module using mapped fields.
Input JSON
{ "duplicate_check_preference": { "type": "mapped_module_records", "type_configurations": [ { "field_mappings": [ { "current_field": { "api_name": "Email", "id": "5725767000000002601" }, "mapped_field": { "api_name": "Email", "id": "5725767000000002503" } } ], "mapped_module": { "api_name": "Contacts", "id": "5725767000000002179" } } ] } } |
How Duplicate Check Preferences Work During Record Creation/Update
Consider Zylker has configured the Contacts module ("type":"mapped_module_records") to check duplicate contacts.
For example, a sales representative at Zylker attempts to add a contact from the Cold Call lead source. However, the same contact already exists in the Contacts module, either from the same or a different lead source.
Since the Contacts module is configured for duplicate check preferences, the system will check for duplicates in the Contacts module using mapped fields. During the record insertion action, the system verifies the Contacts module for any matching records based on these unique identifiers. Based on the result, it either creates the record or throws an error.
Use the Insert Records API to create records in a module.
Request URL: https://www.zohoapis.com/crm/v7/Contacts
Request Method: POST
Input JSON
{ "data": [ { "Company": "Villa Margarita", "Last_Name": "Dolan", "First_Name": "Brian", "Phone": "12345", "State": "Texas" } ] } |
Response
{ "data": [ { "code": "DUPLICATE_DATA", "details": { "api_name": "Email", "duplicate_record": { "Owner": { "name": "Patricia Boyle", "id": "5725767000000411001", "zuid": "808233918" }, "module": { "api_name": "Contacts", "id": "5725767000000002179" }, "id": "5725767000000774010" //The record that already exists in the Contacts module. }, "json_path": "$.data[0].Email", "more_records": false }, "message": "duplicate data", "status": "error" } ] } |
Duplicates are also checked during record updates. If a record is updated with a value that already exists in a unique field, the system indicates it as a duplicate and returns a "DUPLICATE_DATA" error.
Update Duplicate Check Configuration
To update the previously enabled Duplicate Check option configured in your account, use the Update Duplicate Check Option API.
Request Method: PUT
Input JSON
Input JSON
The Contacts ("type": "mapped_module_records") configuration is used in the below sample input.
{ "duplicate_check_preference": { "type": "mapped_module_records", "type_configurations": [ { "field_mappings": [ { "mapped_field": { "api_name": "Phone", //The previously configured Email field as a unique identifier in Contacts has now been replaced with the Phone field. "name": "Contacts", "id": "5725767000000411001" }, "current_field": { "api_name": "Phone", "name": "Leads", //The previously configured Email field as a unique identifier in Leads has now been replaced with the Phone field. "id": "5725767000005381030" } } ], "mapped_module": { "api_name": "Contacts", "name": "Contacts", "id": "5725767000000002179" } } ] } } |
What is the Upsert API?
The Upsert API is a combination of "update" and "insert".
How it works?
You provide a unique identifier (e.g., email, phone number, or a custom field) to check for existing records.
If a record with the same identifier exists, it updates that record.
If no matching record is found, it creates a new one.
Flow diagram
Use Case
Zylker, an e-commerce company, uses Zoho CRM to manage customer data. Customers sign up on Zylker’s online store, and their details are stored in the e-commerce platform like Shopify. Over time, customers may update their contact information, or new customers may sign up. To keep customer records in Zoho CRM accurate and avoid duplicates, Zylker uses the Upsert API to:
- Update existing customer records details if the given unique identifier, such as email or phone number, matches an existing record in Zoho CRM.
- Insert a new record if no match is found. This way, Zylker ensures that new customers are added efficiently.
There are two types of duplicate check fields:
i. System-defined duplicate check fields.
ii. User-defined duplicate check fields.
i. System-defined duplicate check fields
The table below lists the system-defined unique fields. When you create a record using the Upsert API, the system checks these fields for duplicate entries.
The table below lists the system-defined unique fields. When you create a record using the Upsert API, the system checks these fields for duplicate entries.
Leads | |
Contacts | |
Accounts | Account_Name |
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 |
Custom Module | Name |
ii. User-defined duplicate check fields
You can set a normal field as a duplicate check field by enabling "Do not allow duplicate values." Note that you can only set fields with the following field-types as unique— Single Line, Email, Phone, Number, Long Integer, and URL.
Sample Request: https://www.zohoapis.com/crm/v8/Leads/upsert
Request Method: POST
Sample Input JSON
Sample Input JSON
Here, "Email," a system-defined field, has been used as a duplicate check field.
{ "data": [ { "Email": "alice@mail.com", "First_Name": "Alice", "Last_Name": "Brown", "Phone": "+1-555-222-3333", "Order_Date": "2024-01-10", "Order_Value": "$175.00" }, { "Email": "pat@mail.com", "First_Name": "pat", "Last_Name": "Davis", "Phone": "+1-555-666-7777", "Order_Date": "2024-01-15", "Order_Value": "$300.00" } ], "duplicate_check_fields": [ "Email" //You can set the order in which the system checks for duplicate records by specifying the duplicate_check_field array in the input. ] } |
Response
{ "data": [ { "code": "SUCCESS", "duplicate_field": null, "action": "insert", "details": { "Modified_Time": "2025-02-08T09:43:08-08:00", "Modified_By": { "name": "Patricia Boyle", "id": "5725767000000411001" }, "Created_Time": "2025-02-08T09:43:08-08:00", "id": "5725767000005425036", "Created_By": { "name": "Patricia Boyle", "id": "5725767000000411001" } }, "message": "record added", "status": "success" }, { "code": "SUCCESS", "duplicate_field": "Email", "action": "update", "details": { "Modified_Time": "2025-02-08T09:43:08-08:00", "Modified_By": { "name": "Patricia Boyle", "id": "5725767000000411001" }, "Created_Time": "2025-02-08T08:52:22-08:00", "id": "5725767000005425002", "Created_By": { "name": "Patricia Boyle", "id": "5725767000000411001" } }, "message": "record updated", "status": "success" } ] } |
Differences between Duplicate Check Preferences API and Upsert API
Duplicate Check API | Upsert API |
Duplicate Check Preferences can be enabled only in the Leads module. | Supports all modules. |
Throws a "DUPLICATE_DATA" error if a duplicate is detected. | Updates the existing record with new field values if a match is found for the unique fields; otherwise, inserts a new record. |
Use the above Zoho CRM APIs which fit your use cases.
---------------------------------------------------------------------------------------------------------------------
We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com
Stay tuned for more insights in our upcoming Kaizen posts!
- More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog
for detailed information on these updates. ✨
- OAuth Scopes Page for Zoho CRM APIs. ✨
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Subramanian K
Andres
Jeganprabhu S
Sticky Posts
Kaizen #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes areKaizen #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 achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI
Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Create Tasklist with Tasklist Template using API v3
In the old API, we could mention the parameter 'task_template_id' when creating a tasklist via API to apply a tasklist template: https://www.zoho.com/projects/help/rest-api/tasklists-api.html#create-tasklist In API v3 there does not seem to be a way toIntroducing Dedicated Modules for Plans, Addons, and Coupons in Zoho Billing
We’ve enhanced the way you manage Plans, Addons, and Coupons in Zoho Billing. Previously, all three grouped together under Subscription Items. Now, each one has its own dedicated module, giving you a cleaner and more intuitive experience. This updateSend Automated WhatsApp Messages and Leverage the Improved WhatsApp Templates
Greetings, I hope all of you are doing well. We're excited to announce a major upgrade to Bigin's WhatsApp integration that brings more flexibility, interactivity, and automation to your customer messaging. WhatsApp message automation You can now useConverting Sales Order to Purchase Order
Hi All, Firstly, this code works to convert a sales order(SO) to a purchase order (PO) via a button, however I am running into an issue when I convert the SO where the values from the line items are not pulled across from the SO to the PO. The ones inGain control over record sharing with portal users through our new enhancement: criteria-based data exposure
Dear Customers, We hope you're well! Portals is a self-service avenue through which your clients can access and manage their direct and related data in Zoho CRM. This empowers them to be more independent and enables them to experience a sense of transparencyJobs at multiple locations
Hi A lot of times we have same job open at multiple locations. So I would like an option where we can create a job and choose multiple locations. Currently we have to create individual jobs for each location. If we can create one job and mention multiple日本語フォントの選択肢拡充についての要望
日本語フォントの選択肢がとても少ないと感じたことはありませんか？ 多くのアプリ（たとえば Invoice）ではフォントが1種類しかなく、正直あまり使いやすい・見た目が良いとも言えません。 そろそろ、もっと多くの日本語フォントを追加してほしい、そしてすべてのアプリで同じフォント選択肢を使えるようにしてほしいと、私たちユーザーが声を上げる時期だと思います。 ご存じのとおり、現状ではアプリごとにフォント周りの仕様にほとんど一貫性がありません。 みなさん、一緒に要望を出していきましょう！From Zoho CRM to Paper : Design & Print Data Directly using Canvas Print View
Hello Everyone, We are excited to announce a new addition to your Canvas in Zoho CRM - Print View. Canvas print view helps you transform your custom CRM layouts into print-ready documents, so you can bring your digital data to the physical world withPassing the CRM
Hi, I am hoping someone can help. I have a zoho form that has a CRM lookup field. I was hoping to send this to my publicly to clients via a text message and the form then attaches the signed form back to the custom module. This work absolutely fine whenTag Adding Option in Kanban Card Customization Bigin CRM Mobile App
I would like to request an option to add and display tags on Kanban cards in the Bigin CRM mobile app. This feature would make it easier to categorize deals and quickly identify priorities while working on the go.Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM
Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individualsCanva Integration
Hello! As many marketing departments are streamlining their teams, many have begun utilizing Canva for all design mockups and approvals prior to its integration into Marketing automation software. While Zoho Social has this integration already accomplished,Ticket Status email
Good day, This was discussed in the past, but it would be helpful if we could have the system assign a custom response to a status. We have various statuses for tickets, e.g. "closed due to no response", or "Pending Status", it would be helpful for theWhatsApp Voice Message Sending Option in Bigin CRM
I would like to request a feature that allows users to send WhatsApp voice messages directly from Bigin CRM. This would help improve communication efficiency and make it easier for teams to respond quickly to customer inquiries.CRM: hosting a single html file in Zoho and displaying it as a widget
I have seen that CRM offers the option of uploading a web project to Zoho itself and displaying it as a widget in CRM. The instructions then talk about setting a development environment with Node and developing an application to upload to Zoho. But ISynchronise item image between Zoho Commerce and Zoho Books/Inventory/CRM
Here is a blindingly simple idea to tie several Zoho products together. Zoho - please include a method to synchronise the item image (or images) from one Zoho application to another. For example, if you upload an item image in Zoho Inventory, a user shouldHow to change position button transtition of Blueprint?
Hi Everyone, Look at my screenshoot, it is possible move the reject button to the right? I couldn't find that setting in the blueprint. Thank you.Marketer’s Space - WhatsApp Pricing Update: What Marketers Need to Know and Do
Hello Marketers, Welcome back to Marketer’s Space! WhatsApp made changes to their pricing model on July 1, 2025, moving from conversation-based pricing to a per-message pricing model. This week’s post focuses on what these changes mean for your WhatsAppZoho Desk Limitations
Good day, all, I would like to know whether others share my frustration with some of Zoho's limitations. Don't get me wrong, I like Desk (and I also have a subscription for Analytics), I have been with them for close to 10 years, and unfortunately, IMulti file upload
Hi, I just wonder if one could upload multiple files in one shot, say between one and three files, without adding multiple File Upload fields? Thanks, AlalbanySorting Descending in a lookup
I have a case number lookup on multiple forms. I need the most recent added to appear at the top of the lookup or as the list of cases grom it's too much to scroll. Is there a way to have a look up sort descending?Can we add custom fields to portal community profiles?
How do we add custom fields to our profile pages in our portal community? If we have the ability to add custom fields, will we be able to access those fields via API? We want to use our Desk community in our help portal as our primary community and wouldAuto-upload Creator Files to WorkDrive
Hi everyone, I’m working on a workflow that uploads files from Zoho Creator to specific subfolders in Zoho WorkDrive, as illustrated in the attached diagram. My Creator application form has two multi-file upload fields, and I want—on successful form submission—toAsap Widget 2.0
Where's the documentation for the new ASAP widget? https://www.zoho.com/desk/developers/asap/#introduction this one is outdated How can we dynamically navigate between different views? How can we prefill ticket forms using ASAP 2.0?Update date & time when a cell is edited
Hi All, I am desiring to have a cell update with the current date and time when another cell is edited. Any ideas? Thank youCRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive
Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage filesCan the Trigger be changed?
I'm afraid I already know the answer, but here goes... After activating a workflow (under Campaigns > Automations), Then later choosing to Edit the workflow, Can the Workflow's Trigger be changed? Currently the entire Trigger section + options are goneMarketer's Space: Proven tips to improve open rates – I
Hello Marketers! Welcome back to another post in Marketer's Space! In this week's post, we'll discuss the ever-important concept of open rates. This will be a multi-part series, as we have a range of topics to cover. Open rates—which measure the percentageHolidays
Hi; For defining Holidays, you need to add logic to handle the year as well as the month & day. We need to be able to enter Holidays for the next year. I need to add a holiday for January 2, 2017, but I can't until January 1st, which is a Sunday and weCreating Custom PDF Template from Form
I am trying to create a custom PDF from form submissions. I have the standard subscription and it indicates that PDF forms are included. I cannot find anywhere to create PDF forms. I try to follow the instructions from here: https://help.zoho.com/portal/en/kb/forms/form-settings/pdf-settings/pdf-editor/articles/creating-your-own-pdf-template#Creating_your_template_from_the_scratchImportant Update: Facebook Metrics Deprecation & Impact on Zoho Analytics
Dear Zoho Analytics users, Facebook has deprecated a set of metrics from the Facebook Pages Insights API, effective November 15, 2025. As a result, these changes will affect any reports and dashboards in Zoho Analytics that rely on Facebook Pages data.Quick Copy Column Name
Please add the ability to quickly copy the name of a column in a Table or Query View. When you right-click the column there should be an option to copy the name, or if you left-click the column and use the Ctrl+C keyboard shortcut it should copy theConditional Field Visibility in Bigin CRM
I would like to request support for conditional field visibility within Bigin CRM. This feature should allow administrators to configure show/hide rules for fields based on predefined criteria (e.g., field values, picklist selections, stage changes,GPS tracking only or Check out facility
Dear Team, Zoho CRM is quite robust CRM but till date i was waiting for the feature of having GPS tracking of Sales employees which is a common demand by all customers for thier field sales executives. We cover them by saying that CRM provides CheckinIntroducing Zoho MCP for Bigin
Hello Biginners! We're excited to introduce Zoho MCP for Bigin, a completely new way of interacting with Bigin data using AI. With Zoho MCP, you can securely connect your Bigin account with popular AI agents like Claude, Cursor, Windsurf, and VS Code,Introducing the Zoho Projects Learning Space
Every product has its learning curve, and sometimes having a guided path makes the learning experience smoother. With that goal, we introduce a dedicated learning space for Zoho Projects, a platform where you can explore lessons, learn at your own pace,Ask the Experts 26: Brighten every customer interaction with Zoho Desk all year long
Hello everyone, Greetings and welcome to Ask the Experts 26. As we wrap up 2025, we are excited to invite you to the 26th episode of our Ask the Expert series. 🎄The Merry Metrics Edition = Best of Zoho Desk [Best Practices + Holiday Automation + Year-EndMCP > Creator connection failing with Claude
I'm trying to get claude to access any of my Zoho Creator apps and it keeps failing. I have enabled all tools for creator and ensured in claude settings that everything is authorised. Here is what claude says : Unfortunately, the error messages I'm receivingIs it possible to sync data every 5–10 minutes in Zoho Analytics (CRM or Excel imports)?
Hello Team, I want to know if Zoho Analytics supports near real-time syncing of data from different sources. My requirements: I am importing data from Zoho CRM → Zoho Analytics I also have some datasets maintained in Excel/CSV I want both data sourcesFeature Request: Dynamic Dimension Control for zc_LoadIn Popups
As detailed in this community discussion, Zoho Creator's zc_LoadIn parameter is a vital tool for opening components (forms, reports, or pages) in modal dialogs via HTML snippets, Notes, or Rich Text Fields. While powerful, this feature suffers from aNext Page