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. ✨
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
Recent Topics
This will be long, Please bear with me - Next Gen Layout - Search
In general, I think that Zoho are going in the right direction with the Next Gen UI. The latest update brings some nice improvements and all-in-all from a user's perspective I think the improvements are generally very good. However, there are some areasSelecting all notes in a notebook
In Windows11, I select a notebook and I get a list of notes, but only 30 notes. If I scroll down to the end, I get an additional 30 notes (and at the top it now shows 60 notes). I can keep doing this to eventually see all my notes but this is a real pain.Update latitude & longitude address field API
How do I update the coordinates of an address field from a widget? I can't modify the latitude and longitude of the address field. I think the problem is how I'm writing formdata variable. zoho_init.then(function (data) { var queryParams = ZOHO.CREATOR.UTIL.getQueryParams();Filter Records in CRM API
Hi Team, I’m currently working on a task to retrieve expired deals from the CRM. By “expired deals,” I mean deals where the closing date has already passed and the stage is not “Closed Won” or “Closed Lost” (i.e., all other stages). I tried using bothUser Name in Zoho Cliq Not Updating Across Apps?
We updated the name of a user in Zoho. (From Sue to Taylor) Her name has not been updated in Cliq on all apps. When in Zoho One, if I go to Cliq directly, it is correct, but if I am in another app, and the Cliq bar pops up on the bottom, it will be theAbility to Use Both AND and OR When Creating Rules (Advanced Conditions)
I'd like to be able to use more complicated logic when setting up rules. E.g. in Zoho Mail, I can choose "Advanced conditions (AND/OR) to create a rule that can be applied to multiple subject lines from the same sender. But in Zoho TeamInbox, I will haveAttaching files to emails within CRM Deals.
Hello, We have recently started using the extension "Workdrive for CRM" (Related List) to view/store our documents for each Deal, instead of using Attachments. Overall it feels like a better way to go but the user experience is not so great when it comesWhy I can't map Account Name from lead module to Account module?
When I qualify a lead in the bluerprint, I use automated conversion in Blueprint to automatically create Contact, Account and Deal. the Deal record and contact record has been successfully created automatically as I expect, but I can't see any accountPause(1);
I'm using scheduler to invoke an interaction via http post with an external service. The schedule code uses a for-each loop that runs so fast my external application's log files get messed-up (they are named by date-time stamp). What I'm suggesting isRelease Notes | February 2026
We have rolled out another set of enhancements in Vertical Studio during February 2026, bringing improvements to Canvas customization, reporting capabilities, and data access controls. Here is a summary of what was released during February 2026: CanvasAgentic Engineering with Zoho: The Next Evolution of Intelligent Systems
The concept of Agentic Engineering is reshaping how modern systems are designed. It introduces a new layer to the way we think about artificial intelligence and system architecture. For years, most software systems have operated in a reactive way — respondingEngenharia Agêntica e as soluções da Zoho
O conceito de engenharia agêntica impacta diretamente como os sistemas são projetos. Este tema inseri mais uma camada a nossa idéia de inteligência artificial. Antes o desenvolvimento de sistemas operavam de forma reativa e dependente de comandos diretos,Effective project and task customization with CodeX
Dear users, Beyond Task Lists is a series of articles aimed at showcasing the various customization capabilities of Zoho Projects. We'll discuss real life project management scenarios, use cases, and requirements that needs combining multiple features.Set expiration date on document and send reminder
We have many company documents( for example business registration), work VISA documents. It will be nice if we can set a expiry date and set reminders ( for example 90 days, 60 days, 30 days etc.,) Does Zoho workdrive provide that option?Debit opening balances of vendors
Dear colleagues: I am looking at the trial balance as on 31st March 2024, and punching opening balances (1st April 2024) in Zoho Books. Vendors have credit balances, by its nature, but some of our vendors have debit balances as well (e.g., we have paidZoho Books emails suddenly going to Spam since 11 Nov 2025 (Gmail + now Outlook) — anyone else?
Hi everyone, We migrated to Zoho Books in July 2025 and everything worked fine until 11 Nov 2025. Since then, Zoho Books system emails are landing in customers’ Spam (first Gmail, and now we’re seeing Outlook/Office 365 also starting to spam them). ImpactedClient Portal ZOHO ONE
Dear Zoho one is fantastic option for companies but it seems to me that it is still an aggregation of aps let me explain I have zoho books with client portal so client access their invoice then I have zoho project with client portal so they can access their project but not their invoice without another URL another LOGIN Are you planning in creating a beautiful UI portal for client so we can control access to client in one location to multiple aps at least unify project and invoice aps that wouldThe Social Wall: February 2026
Hello everyone, This month, we’re bringing you a mix of exciting toolkit enhancements and a few improvements across the web and iOS app, all designed to make your social media management simpler and smoother. File converter Images come in different formats,Zoho Mail and SalesInbox doesn't link to CRM record using Reply-To
Hi, I've just set up SalesInbox, with the intention of using it for sales enquiries (instead of Desk, which I have been using until now). I've noticed that, unlike Desk, SalesInbox only uses the 'From' email address to attempt to link to a CRM contactService line items
Hello Latha, Could you please let me know the maximum number of service line items that can be added to a single work order? Thanks, Chethiya.Poor Search Results on Zoho CRM
The search on Zoho CRM is quite poor. Salesforce has now published a new search, when will get this on Zoho? https://help.salesforce.com/s/articleView?id=data.c360_a_hybridsearch_index.htm&type=5How to use filters on all products page? Or even a category page?
Hello, I am trying to create some filters so users can use filters to find products they are looking for. So what i am trying is to create a filter according to price lets say. So if i define it this way i am expecting to see this filter option on categoryCapture Last check-in date & days since
I have two custom fields on my Account form, these are "Date of Last Check-In" and "Days Since Last Contact" Using a custom function how can I pull the date from the last check-in and display it in the field "Date of Last Check-In"? and then also display the number of days since last check-in in the "Days SInce Last Contact" field? I tried following a couple of examples but got myself into a bit of a muddle!Archiving Contacts
How do I archive a list of contacts, or individual contacts?Every time an event is updated, all participants receive an update email. How can I deactivate this?
Every time an event is updated in Zoho CRM (e.g. change description, link to Lead) every participant of this meeting gets an update email. Another customer noticed this problem years ago in the Japanese community: https://help.zoho.com/portal/ja/community/topic/any-time-an-event-is-updated-on-zohocrm-calendar-it-sends-multiple-invites-to-the-participants-how-do-i-stop-that-from-happening3/18 オンライン勉強会のお知らせ Zoho ワークアウト （無料）
ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 3月開催のZoho ワークアウトの開催が決定しましたのでご案内します。 今回はZoomにて、オンライン開催します。 ▶︎参加登録はこちら（無料） https://us02web.zoom.us/meeting/register/BoNTN7zYR8OvOPGShqBY0A ━━━━━━━━━━━━━━━━━━━━━━━━ Zoho ワークアウトとは？ Zoho ユーザー同士で交流しながら、サービスに関する疑問や不明点の解消を目指すイベントです。Conversion Rate – Won Deals over Assigned Prospects
Hello, I would like assistance configuring a KPI in Zoho Analytics titled: Objective of the calculation: Number of Won Deals divided by Total number of assigned prospects (not only converted prospects). Important clarification: The denominator must includeFeature Request – Conditional Visitor Information Request in Zoho SalesIQ
We would like to request the ability to conditionally ask for visitor details based on the communication channel used in Zoho SalesIQ. Specifically: When a visitor initiates a conversation through the live chat widget on the website, we want to continueApple Messages for Business in Omnichannel communications?
Hello, Apple launched "Apple Messages for Business" but Zoho CRM or Zoho Desk don't appear in the list of possible integrators. Zoho already promotes https://www.zoho.com/crm/omnichannel.html Omni Channel integration, but Apple Messages does not yet appear.Admin asked me for Backend Details when I wanted to verify my ZeptoMail Account
Please provide the backend details where you will be adding the SMTP/API information of ZeptoMail Who knows what this means?Cliq iOS can't see shared screen
Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? RegardsZOHO.CRM.UI.Record.open not working properly
I have a Zoho CRM Widget and in it I have a block where it will open the blocks Meeting like below block.addEventListener("click", () => { ZOHO.CRM.UI.Record.open({ Entity: "Events", RecordID: meeting.id }).catch(err => { console.error("Open record failed:",【Zoho CRM】通貨機能のアップデート：為替レートの自動更新やデータ更新オプションなど
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から通貨機能のアップデートをご紹介します。 CRMの複数通貨機能を使うと、地域ごとに通貨を管理し、顧客の現地通貨で記録したデータを自国通貨に自動換算して分析やレポートに活用できます。 従来は、為替レートを管理者が手動で定期更新する必要があり、各データには作成時点のレートが固定されるため、その後の市場変動は反映されませんでした。 本記事では、この問題を解消する「為替レートの自動更新」をはじめ、さまざまな新機能をご紹介します。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:Can we add zoho sign to a custom module?
i understand out of the box it works with 8 modules. is it possible to add it to a custom module?This domain is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details
Selected date present employees roster
=CHOOSECOLS(FILTER(A2:E5;(INDEX(C2:E5;0;MATCH(VALUE(B8);INDEX(VALUE(C1:E1));0))<>"OFF")*(INDEX(C2:E5;0;MATCH(VALUE(B8);INDEX(VALUE(C1:E1));0))<>"EL"));1;2;2+MATCH(VALUE(B8);INDEX(VALUE(C1:E1));0)) This way sheet looks lCredit Card Terminal for Zoho Books
Hello, Instead of punching the credit card number manually for customer payment, do you have a third-party hardware credit card reader that works with Braintree? Thank YouFiltering in Help Center
Hi, our ticket system is based on a set of structured status categories. The customer must be able to filter by these status. How can we add "Status" as filter to the help center. In the same moment we do not need filters e.g. as "channel". How can weOn Edit Validation Blueprint
Hello, I have a notes field and a signature field. When the Approve button is clicked, the Signature field will appear and must be filled in. When the Reject button is clicked, the Notes field will appear and must be filled in. Question: Blueprint willNext Page