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 #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 theKaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.
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
Marketer’s Space - Get Holiday-Ready with Zoho Campaigns
Hello marketers, Welcome back to another post in Marketer’s Space! Q4 is packed with opportunities to connect with your audience - from Halloween, Black Friday, and Cyber Monday, to Thanksgiving, Christmas, and New Year. In this post, we’ll look at howPersonalized demo
can I know more about the personalized demo we are construction company andUser Filter not selecting All Items
We are encountering 2 issues when using the user filter. When users are trying to search using the filter option, the OK button is grayed out. Users have to unselect or make a change before it filters properly. 2. When filtering and the OK button works,Can I collect email addresses in a form??
Can I add new subscribers to my email list (hosted in FloDesk) when they check a box and add their email address on a Zoho form?Zoho CRM Android app updates: Kiosk and multiple file upload support for subforms
Hello everyone, We've rolled out new enhancements to the Zoho CRM Android app to bring better mobile CRM experience and efficiency. Let's take a quick look at what's new: Kiosk Multiple file uploads for subforms Kiosk Kiosk is a no-code tool in Zoho CRMAlerts for mentions in comments
We are testing the use of Writer internally and found that when a user is mentioned in a comment, there is no email alert for the mention. Is this something that's configurable, and if so, where can we enable this option?Subform Disabled Fields Should Remain Disabled on Edit/View
Currently, when we disable a subform field using on user input or on add new row, it works perfectly during the initial data entry. However, when the record is saved and reopened for viewing or editing, these disabled fields become editable again. ThisIs it really true that I can't set the default 'deposit to' account in 2025?
I've been using Books for 7 years and the default account has never been a problem. I usually manually reconcile invoices and have never had a thought about which account. It has always been my account. However, I recently noticed that for the past 4Standard Payment Term is not pulled from account to quotation
Hey Team There seems to be something off. I do have "Net 30" as my default payment term in Zoho Books for my customers. If, from the customer overview or quote section, I create a new Quotation, the payment terms field stays blank and doesn't get theOAuth integration issues
I'm experiencing persistent OAuth errors when trying to connect Make with Zoho API. I've tried multiple approaches but keep encountering the following issues: First error: 'Invalid Redirect Uri - Redirect URI passed does not match with the one configured'Zoho Mail Android app update: Manage folders
Hello everyone! In the latest version(v2.9) of the Zoho Mail Android app update, we have brought in support for an option to manage folders. You can now create, edit, and delete folders from within the mobile app. You can also manage folders for the POPShortcut to fill a range of cells
Good evening: I'm writing because I haven't been able to find a feature that allows you to select a range of cells, type in one of them, and then use a key combination to type in all of them. In Excel, the keyboard shortcut is Ctrl+Enter. I haven't foundGet Zoho Mail API working (including DRE Connector, Oauth Token, ZUID, ZOID & ACCOUNT_ID)
Disclaimer: I’m not a professional coder! Do you need to use Zoho Mail API? Me too. It lets you do all sorts of things — like reading the complete header of an email, or forwarding an email with its attachments — which is what I wanted to do. But settingRevenue Deferrals
Does ZOHO books and subscriptions handle Revenue Deferrals?Can I make a website open inside Zoho whenever I log in?
Hi Zoho Team, Every day, I check a few websites for updates, for example, Rojgar--result, where I see the latest government job results and notifications. I was wondering if there’s any option in Zoho to make a website like that open inside Zoho wheneverZoho Analytics & SQL Server - Live connect
Below are the steps I did Created a fresh database and table in my own virtual server Created a new data source connection with live connect I was able to select the tables and created the data source successfully I am getting the error when I try toKaizen #214 - Workflow APIs - Part 2
Welcome back to another week of Kaizen! Last week, we discussed how Zylker Cloud Services used the Workflow APIs to discover and audit all the automations in their CRM, listing every workflow, checking triggers, and understanding their automation limits.Playback and Management Enhancements for Zoho Quartz Recordings
Hello Zoho Team, We hope you're all doing well. We would like to submit a feature request related to Zoho Quartz, the tool used to record and share browser sessions with Zoho Support. 🎯 Current Functionality As of now, Zoho Quartz allows users to recordZoho CRM Community Digest - September P1 | 2025
Hello Everyone! September's Here! Before we jump into product updates, and community highlights, here's a quick spotlight! Zoho has launched a Professional Sales Rep Certification course on Coursera, tailored for sales professionals to strengthen theirUpload my theme.
Hello. I would like to upload my own theme, this one: https://themeforest.net/item/panagea-travel-and-tours-listings-template/21957086 Is it compatible and where I upload it? If not I will hire a developer, what do I have to ask when I search for one?Explore the Redesigned Quotes Module in Zoho Billing
Dear users, We’re excited to introduce a refreshed look for the Quotes details page in Zoho Billing! This update brings you a more efficient user interface experience without changing your existing workflow. We've enhanced layouts with organized tabs,Product Updates in Zoho Workplace applications | September 2025
Hello Workplace Community, Let’s take a look at the new features and enhancements that went live across all Workplace applications this September. Zoho Mail Attach email as EML file in Compose Effortlessly attach emails as EML file in Compose by simply🤝 Rencontres, partage et inspiration au Zoho Community Meetup de novembre
Chers utilisateurs, Bonne nouvelle 🎉 : notre Meetup Zoho Community approche, et nous serions ravis de vous y voir ! 📍 Toulouse : le 25 novembre 📍 Lyon : le 27 novembre (🎯 Il ne reste que quelques places !) Que vous soyez débutant ou utilisateur avancé,Need Help Mapping GST Registration Number Field Between Zoho Books & Zoho CRM + Slow Sync Issues
am facing an issue with field mapping between Zoho Books and Zoho CRM. I want to map the GST Registration Number field from the Customer module in Zoho Books to a custom GST field inside the Accounts module in Zoho CRM. However, I am getting a warningNotification received when self-assigning tickets
When I assign tickets in Zoho Desk the relevant agent gets a notification email. When assigning myself a ticket in Zoho Desk, I get a notification email. Now, as I am the person who assigned the ticket to myself, getting a notification in this regardNouveauté dans Zoho Writer - Création de documents et de modèles assistée par l'IA
Zia, l’assistant IA de Zoho Writer, soutient les utilisateurs dans l’amélioration de leur écriture et la création de contenus : correction orthographique et grammaticale en temps réel, suggestions adaptées au contexte, détection du plagiat, révisionsSession Expired
I constantly get "Session Expired" and need to relogin or close and open the application again. This gets really frustrating during the day. Is this something that can be solved? This really makes me want to leave the app as it is no go to need to reopenIntegrate your Outlook/ Office 365 inbox with Zoho CRM via Graph API
Hello folks, In addition to the existing IMAP and POP options, you can now integrate your Outlook/Office 365 inbox with Zoho CRM via Graph API. Why did we add this option? Microsoft Graph API offers a single endpoint to access data from across Microsoft’sDisable Buttons for Users with Profiles without permission
Hey, I've noticed that users without permission of setting up things in the marketplace, can still see the icon: On a click, you see this: It would be way better, if they couldn't see this menu icon at all. (Aside from the fact that it completely misplacedMapping a new Ticket in Zoho Desk to an Account or Deal in Zoho CRM manually
Is there any way for me to map an existing ticket in Zoho desk to an account or Deal within Zoho CRM? Sometimes people use different email to put in a ticket than the one that we have in the CRM, but it's still the same person. We would like to be ableZoho製品と生成AIツールの活用について
いつもありがとうございます。 弊社では、Zoho Oneを契約し、CRMを軸として、見込み客の管理から商談、その後の受注や請求の管理、サポート業務（Desk）、業務データのレポーティング（Analytics）などを行っております。 Zohoサービス自体には、Ziaというツールが搭載されているかと存じますが、それ以外の外部の生成AIツールと連携した活用などもできるのでしょうか？具体的には、CopilotなどがZohoに登録されているデータや情報を見て、対話型で必要なデータを提示してくれたり、商談や蓄積されたメモなどを分析してユーザが知見を得られるような活用ができないか、と考えております。Zoho Analytics - Make text clickable in underlying data
Hi Community, I have a simple sales report based on a Invoice query table. I have included a link on to each invoice on the table and sent the Invoice number URL to the link. This works find in the query table, but when I click underlying data on theCredit Management: #5 Advanced Refund Policy
You're subscribed to a well-known SaaS design tool. You've used it to manage your team's projects, create marketing visuals, brochures, and so on. But your needs change over time. Your company may switch to another tool or hire an in-house designer whoExported Slide Image Lacks Portion of the Background Image
This does not always happen, but when I export (or "download") the rendered image of a slide, it sometimes lacks a portion of the background image. I created a sample slide deck to demonstrate it and shared it with the admins. It is also publicly availableHow to create a Zoho Mail extension similar to Outlook's OnSend add-in?
Hi, I want to create a Zoho Mail extension similar to Outlook’s OnSend add-in. The extension should: Let the user select headers and footers from a taskpane while composing an email. When the user clicks Send, the extension should: Automatically insertEffective Inbox Organization: Folders vs Tags in Zoho Mail?
I'm exploring the best ways to organize a busy inbox, especially when managing multiple clients or project using Zoho Mail. I’d love to know what works best for others: 1. Do you prefer **folders** (possibly with sub-folders) for each client or project?Piss poor service in Support in Domains and email
Srijith Narayanan B contacted me today. Very pleasant fellow. Just didn't want to tell him how bad your support service is. You help the person, but you leave before we can finish the next stage. Which causes a lot of frustration. It's been 8 days nowZoho Mail android app update: Block & reject future emails, Report phishing, Spam alerts, Suspicious URL detection
Hello everyone! In the most recent Zoho Mail Android app update, we have brought in support for the following features: Block & reject future emails Report Phishing Spam alerts in the mail details screen. Suspicious URL detection. Block & reject futureZohomail does not support additional fields in mailto links
Hello, I set up Zohomail as default composer in Firefox according to manual here: https://www.zoho.com/mail/help/defaultcomposer.html#alink2 Later, I wanted to use this functionality to answer in a Linux mailing list thread using mailto link: mailto:xxxxx@kernel.org?In-Reply-To=%3C727o0521-q24p-s0qq-66n0-sn436rpqqr1p@example.com%3E&Cc=xxxxx%example.org&Subject=Re%3A%20%5BPATCH%20v2%28%29Emails not being received from a particular domain
Cannot receive any emails sent from atco.com Domain is in the spam whitelist so should be no reason for it not to be coming through. Have filed a ticket and besides a generic response of we are looking at it - it seems there is no actual support workersNext Page