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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
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 #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #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 are
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
Ability to Attach Record-Specific Files Automatically in Workflow Email Templates
Currently in Zoho CRM, email templates allow attachments to be added, but these attachments are static and remain the same for every recipient. There is no straightforward option to automatically attach a file that is stored within the specific CRM recordZoho DataPrep integration with OpenAI (beta)
We are thrilled to announce Zoho DataPrep's integration with OpenAI. The public beta roll-out opens up three features. Users who configure their OpenAI Organizational ID and ChatGPT API key (Find out how) will be able access the features. The featuresCRM Client Portal mobile App?
Hello Just checking back in on this... I was wondering if a mobile CRM client Portal app is on the develop pipeline? Some of the other Zoho apps have them (Creator and Connect), but we love the CRM and our clients and vendors use their phone almost exclusivelyHow does SKU work when selling products in parts in Zoho Inventory
Hello everyone, Zoho Inventory does not understand the physical cutting of the piece.. It only tracks quantities of the unit (like feet ). So when you sell part of an item, the system simply reduces quantity for that SKU. Assume that i have a 50 ft longRestrict employees to take only one day holiday from a multi-day festival holiday
Hi everyone, I have a requirement related to Optional/Festival Holidays in Zoho People. For example, in the month of May there are three optional holiday dates: May 11, May 12, and May 13. Employees can choose one of these days as their optional holiday.AI Bot and Advanced Automation for WhatsApp
Most small businesses "live" on WhatsApp, and while Bigin’s current integration is helpful, users need more automation to keep up with volume. We are requesting features based on our customer Feedbacks AI Bot: For auto-replying to FAQs. Keyword Triggers:Related lists New option in missing
hi I have created quite a few modules and added as related lists to my main module. Some have new, some dont I can not see why?Setting total budget hours for a specific project
Hi there, I work on a lot of projects that have fixed budget hours. Is there a way to enter the total budgeted hours so i can track progress and identify when hours have been exceeded. I see in the projects dashboard there is a greyed out text sayingClone entire dashboards
If users want to customize a dashboard that is used by other team members, they can't clone it in order to customize the copy. Instead they have to create the same dashboard again manually from scratch. Suggestion: Let users copy the entire dashboardIntroducing Formula Fields for performing dynamic calculations
Greetings, With the Formula Field, you can generate numerical calculations using provided functions and available fields, enabling you to derive dynamic data. You can utilize mathematical formulas to populate results based on the provided inputs. ThisGetting started with Zoho PDF Editor
Hello users, If you are new to Zoho PDF Editor or aren't sure of its full potential, then this article is for you. Zoho PDF Editor is a free online PDF editing tool, that allows you to upload and edit PDFs, insert text and images, add fillable and e-signatureZoho Projects - Cloning a task does not trigger task workflow when created
Hello! I have a Project where my team uses a set of tasks from a tasklist as templates, so we could simply clone it and drag it to another list in kanban view to avoid creating a new one from scratch. The process works well, but after cloning it the newPurchase Orders not in sequence
I am unable to sort by Purchase Order Numbers. I can only sort by date; however, the PO numbers aren't in the order they were entered. This was not the case prior to today.Placeholder format in Number field does not reflect Max Digits configuration
When the Max Digits (Maximum digits of number) property is set to a smaller value (for example, 2 digits), the placeholder in the input field still displays a 7-digit format (#######). The same behavior can also be observed in Decimal and Currency fieldInternal Fillable Contract with Zoho Writer (Before Sending to Client)
Hi everyone, I’m trying to automate the following process in Zoho CRM and would appreciate some guidance. Process: When a Deal moves to a specific stage, CRM triggers an automation. CRM sends a contract template to an internal team member so they canDate/time displayed in ZohoCRM does not match date/time of entries in ZohoForm
Hello there, we use a ZohoForm as a worksheet, i.e. users use it to track start time, break and stop time for every working day. The ZohoCRM org time zone is set on GM -4, so is the Time Zone in the Date&Time section in ZohoForm (see attachment). DespiteUpdate Existing Records greyed out in Free Version
Trying to update records from an Excel sheet, and not getting the option to update. Only option is to add as new accounts. All documentation I can see says update should be an option! Accounts, Leads, Contacts, all the same.Dynamically Populate Picklist Values from Another Module Using Client Script
I am working in Zoho CRM and trying to dynamically populate a picklist field in the Partners module using values stored in another custom module. I have two modules: 1. Partners Module Field: Partner_Type_Pick Field Type: Picklist 2. Partners_Type ModuleAdd zoho calendar to google calendar
Hi I keep seeing instructions on how to sync Zoho CRM calendar with google calendar but no instructions on how to view Zoho calendar in my google calendar.Zoho Community Digest : Jan 2026 | Part 1
Hello Everyone! Staying in the loop with Zoho's latest product updates and features across the vast Zoho Community Forums can be a real challenge. We get it. With over 50+ applications, each with its dedicated forum, it's easy to miss out on importantWorld date & time format
Hello, Is there a timeline to get the worldwide used date and time format ? I mean not the american one... I mean day month year, and 24 hours clock. RegardsZoho Meeting - Feature Request - Introduce an option to use local date and time formating
Hi Zoho Meeting Team, My feature request is to add an option for dates to be displayed in the users local format. This is common practice across Zoho applications and particularly relevant to an application like Zoho Meeting which revolves around dateNimble enhancements to WhatsApp for Business integration in Zoho CRM: Enjoy context and clarity in business messaging
Dear Customers, We hope you're well! WhatsApp for business is a renowned business messaging platform that takes your business closer to your customers; it gives your business the power of personalized outreach. Using the WhatsApp for Business integrationHow Zoho Desk contributes to the art of savings
Remember the first time your grandmother gave you cash for a birthday or New Year's gift, Christmas gift, or any special day? You probably tucked that money safely into a piggy bank, waiting for the day you could buy something precious or something youConditional layouts - support for multi-select picklists
Hi, The documentation for conditional layouts says the following: "Layout Rules cannot be used on the following field types: Auto Number Lookup Multi Select Lookup User Lookup Formula File Upload Multi Line" I have a custom module with a multi-pick listDont want to list inactive items.
If an item is made inactive, there is no point in showing it in the item list. Please provide an option to hide all inactive items in 'Preferences'.Possible to freely prompt/query CRM data using Zia?
Is it possible to prompt Zia to query on any information stored in the CRM, especially on the data stored in custom text fields? My use case is the people in my organisation have entered lots of text in custom text fields to capture information from anActual vs Minimum
Hi all, I am sure I am not the only one having this need. We are implementing billing on a 30-minute increment, with a minimum of 30 minutes per ticket. My question is, is there a way to create a formula or function to track both the minimum bill vs theClient Script Not Working When Field is Set by Workflow
Problem Context: I have implemented a client script in the Cases module that automatically assigns commands based on the value of the Priority field. The script functions correctly when the Priority field is manually set by a user through the form. ObservedIntegration of CRM and Recruit
hi team, Is it possible to sync deals <> job openings from only 1 pipeline? My configuration of CRM has pipeline for each business unit, so I will have all data in the CRM system. body leasing and recruitment is one BU (hence 1 pipeline) - can I sync{Action Required} Re-authenticate your Google Accounts to Continue Data Sync
Hello Users! To align with Google’s latest updates on how apps access files in Google Drive, we’ve enhanced our integration to comply with the updated security and privacy standards, ensuring safer and more reliable access to your data. With this update,Approvals in Zoho Creator
Hi, This is Surya, in one of my creator application I have a form called job posting, and I created an approval process for that form. When a user submits that form the record directly adding to that form's report, even it is in the review for approval.Select CRM Custom Module in Zoho Creator
I have a custom module added in Zoho CRM that I would like to link in Zoho creator. When I add the Zoho CRM field it does not show the new module. Is this possible? Do i need to change something in CRM to make it accesible in Creator?Cannot give public access to Html Snippet in Zoho Creator Page
Hi, I created a form in Zoho Creator and published it. The permalink works but I want to override the css of the form. (style based URL parameters is not good enough) So I created a page and added an Html snippet. I can now override the css, which isintegrating Zoho CRM vendors with Zoho projects
In most of our projects we collaborate with our Vendors. Being able to integrate only Accounts and not Vendors from CRM, is a huge limitation for our perspective and needs. We would really love to see this feature in the CRM-Projects integration.Zoho Creator Workshops 2026—Europe & UK | Coming to a city near you!
Hello everyone! We're excited to announce the Zoho Creator Workshop Series 2026, coming to cities across Europe and the United Kingdom this year! Whether you're looking to explore the intermediate-to-advanced capabilities of Creator or you're a seasonedValidation rule for Date field
The condition settings for a Date field are are absolutlly usless. Conditions can only be set for a specific date, which is logically ineffective in most cases. When setting a condition for a Date field, users usually need to compare the value relativemerhaba
merhaba sosyal medya paketimiz mevcut ama yorumları göremiyoruz ve o yüzden cevap veremiyoruz destek rica ediyoruz.Number 9 envelopes for invoice printing
I email and print invoices. Being new to Zoho and coming from QB, we did both as we have a more traditional So in Zoho i want to do the same using Number 9 envelopes. These have both a return window and mail to windoow see attached image. Im just looking for best suggestions on how to get a ZOHO invoice to work, so I can mail my invoices...Zoho Books/Square integration, using 2 Square 'locations' with new Books 'locations'?
Hello! I saw some old threads about this but wasn't sure if there were any updates. Is there a way to integrate the Square locations feature with the Books locations feature? As in, transactions from separate Books locations go to separate Square locationsNext Page