Duplicate Check Preferences API vs. Upsert API

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.

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. 

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"
                }
            }
        ]
    }
}


The "Phone" field from both the Leads and Contacts modules is mapped to identify duplicate records.

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 Method: POST

Input JSON

{
    "data": [
        {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "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.


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"
                }
            }
        ]
    }
}

You can also retrieve and delete duplicate configuration.

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. 

Leads

Email

Contacts

Email

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.


Request Method: POST

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"
        }
    ]
}


For more details on how the Upsert API works, refer to the Kaizen #56 - Upsert Records #API.

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!

Info

    • Sticky Posts

    • Kaizen #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.

    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 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.

    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

    • Recent Topics

    • Zoho CRM: Sales Rep Professional Certification Program on Coursera

      We are happy to share that we have published the Zoho Sales Representative Professional Certificate in partnership with Coursera, a leading platform for online learning and career development that offers access to courses and degrees from leading universities

    • OS X Notebook quits immediately upon launch

      NoteBook for OS X (Sequoia, but also under Sonoma) always quits immediately upon launch (so I cannot use the "Attach user log" option). I've restarted my MacBook but the problem persists. If it helps, attached is a diagnostic report from Library>Log

    • Can External users upload files or images to WorkDrive?

      I want to know if it is possible for someone externally through a link and PW be able to upload files and images onto WorkDrive?

    • Multi-line fields character limits

      Is there a way to set the character limit higher on multi-line fields so that we are not losing information pasted into the field? When the text is entered or pasted, there is no error to say that the text is too large. After saving and going back to view most of the text is gone.   Also, when viewing the resume, the text is not wrapped in the multi line fields and can t be read without scrolling across the page.

    • Taz bot not working — What should I do to resolve this issue?

      I am experiencing issues with the Taz bot in Zoho Cliq—not receiving responses or it does not seem to work as expected. Could you please explain why the Taz bot might not be functioning and what steps I should take to resolve this issue? Thank you!

    • OneNote Migration

      I am trying to migrate two notebooks from OneNote. For five days now I have had no notification that migration has completed and the migration page show 50% complete - one notebook completed one not finished. It just stays like this. I am unable to cancel

    • Set various time slot reminders for task and event

      Hi I would like known if there is possibility to set various time reminders for a task or event like we have the possibility to do in google calendar or google task. For example I'am creating an event or task and I want to be alerted before 30min and

    • Zoho Calendar not functioning---cannot edit, add attendees, etc.

      Hello, My calendar is acting strange. I'm using Chrome as my browser and pop ups are not blocked (the calendar worked fine yesterday). When creating an event, I'm not able to "edit" the event and add attendees, etc. The link is non-responsive. I cannot

    • Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked

      Hi, I sent few emails and got this: Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked And now I have few days since I cant send any email. Is there something wrong I did? Also can someone fix this please

    • Spilt Axis for stacked column and line graph

      Each month around this time I prepare a business review deck. One of the biggest annoyances I have with Zoho, also happens to be something that most other platforms have provided for a long time now, and that is being able to create a chart with stacked

    • Pin a note on top

      Dear Zoho Notebook Team, Please highly consider adding ability to pin a note on top and arrange pinned notes. I have a lot of notes that I want to pin important ones on top and this feature is missing badly. Thank you.

    • Windows 11 app ver 2.2.8

      I have been trialing Zoho Notes syncing between my PC and iphone. No problems with iphone but the Windows 64 bit app ver 2.2.8 was very buggy and would lock up completely, needing a Control Alt Delete etc to close it down. It seemed to be connected to

    • Deluge Script: Onboarding → Access Form

      Hello everyone, Edit: Sorry, I think I put this topic in the wrong section. I’ve recently run into an issue that’s been giving me a bit of a headache for the past few weeks. Context: This is my first time using Deluge to create a script, but it’s not

    • Windows Device Authentication

      We have recently started using ManageEngine, and my boss saw a device management feature in the Zoho One directory. We thought it would either help give us more intergration into Zoho one through bringing ManageEngine services through Zoho one. Or, it

    • How can I change spell check language?

      I cannot find the way to change spell check language. My "display language" is English, and I want to have the same one for Spell Check, but it is Russian!!! How can I change it? In one of your explanations you mentioned that I have to choose it from

    • Mail is so slow - doesn't even work!

      Mail has been getting slower and slower - and today it's not even pulling up emails in either Inbox or Unread. This is beyond frustrating since email is a big part of business. Sent a request through the useless help portal - no response. Called the useless

    • User marked as SPAMMER. Mail Fetch has also been disabled for any active POP accounts.

      I am the administrator for joelles.com One of our accounts has been blocked saying this: User marked as SPAMMER. Mail Fetch has also been disabled for any active POP accounts. I cannot change the disabled account in the control panel as it says that it

    • My domain did not activate

      Hi, my domain (apsaindustrial.com.ar) did not activate, and the phone verification message never arrived. Please would you solve this problem? Thanks.

    • ME SALE ESTE ERROR: No fue posible enviar el mensaje;Motivo:554 5.1.8 Email Outgoing Blocked

      Ayuda!! Me sale este error al intentar enviar mensajes desde mi correo electronico de Zoho! Tampoco recibo correos pues cuando me envia rebotan. Ayuda, Me urge enviar unos correo importantes!! Quedo atenta MAGDA HERNANDEZ +5731120888408

    • Is there a way to sync Tags between CRM and Campaigns/Marketing Hub?

      I wonder if there is a way to synch the tags between CRM and Marketing-Hub / Campaigns?

    • how to see if a specific contact opened an email in zoho campaign?

      how to see if a specific contact opened an email in zoho campaign?

    • Revenue Management: #8 Revenue Recognition in Educational & Training Institutions

      Educational Institutions and training centres typically collect course fees at the time of enrolment, sometimes for a one-day workshop and sometimes for a year-long certification course. You might also charge separately for course materials or evaluation.

    • How to Customize Task Creation to Send a Custom Alert Using JavaScript in Zoho CRM?

      Hello Zoho CRM Community, I’m looking to customize Zoho CRM to send a custom alert whenever a task is created. I understand that Zoho CRM supports client scripts using JavaScript, and I would like to leverage this feature to implement the alert functionality.

    • how to use validation rules in subform

      Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")

    • Using files from Zoho CRM in Gemini/ChatGPT/Claude

      Hi all, I’ve got subscriptions to Gemini and a few other AI tools which I use for tasks like data enrichment, email composition, etc. In our workflow, we often receive various documents from clients — such as process workflows, BRDs/requirement documents

    • Enhancements to the formula field in Zoho CRM: Auto-refresh formulas with the "Now" function, stop formula executions based on criteria, and include formulas within formulas

      Dear Customers, We hope you're well! By their nature, modern businesses rely every day on computations, whether it's to calculate the price of a product, assess ROI, evaluate the lifetime value of a customer, or even determine the age of a record. With

    • Maximum file limit in zoho people LMS

      Dear Team, I am having approximately 4.9 GB of material, including PPTs and videos for uploading in zoho people LMS course. May I know what is the maximum limit limit for the course files Thanking you, With regards, Logeswar V Executive _ Operations

    • Dynamically prefill ticket fields

      Hello, I am using Zoho Desk to collect tickets of our clients about orders they placed on our website. I would like to be able to prefill two tickets fields dynamically, in this case a readonly field for the order id, and a hidden field for the seller

    • Optimize your Knowledge Base for better visibility by allowing search engine crawling and indexing

      All you need to know about no-follow and no-index in KB. What are article crawlability and indexability? Crawlability and indexability are vital for making an article visible and accessible to search engines. When a search engine crawls an article, it

    • Has anyone created a public ASAP Guide that I can check out?

      I am thinking of adding an ASAP guide to my web application, but I have noticed that the ASAP widget itself can be really slow to load sometimes. Has anyone created a public ASAP Guide that I can check to see how performant it is? I don't want to spend

    • Zoho Desk Partners with Microsoft's M365 Copilot for seamless customer service experiences

      Hello Zoho Desk users, We are happy to announce that Zoho Desk has partnered with Microsoft's M365 to empower customer service teams with enhanced capabilities and seamless experiences for agents. Microsoft announced their partnership during their keynote

    • What’s New in Zoho Analytics – September 2025

      Hello Users!! In this month’s update, we’re raising the bar across multiple touchpoints, from how you bring in data, plan and track projects to how you design and brand your dashboards. We’ve added the all-new Gantt chart for project visualization, expanded

    • Zoho MCP has no tools for Creator or 3rd Party Apps?

      I don't see a Zoho MCP community forum so putting this here. Two big problems I see: 1) Although Zoho advertises "over 950 3rd party apps" as available through their MCP, when I go to "Add Tools" there are ZERO 3rd party apps available to choose from.

    • Zoho Forms - Zoho Drive connection - Shared Drives not supported

      Hello i am stuck with Google Drive Connection There is no supported shared drives Connection is not support shared drives boolean Query Parameters - supportsAllDrives=true&supportsTeamDrives=true to activate fetch files from the shared drives. Ahat need

    • Can't create package until Bill created?

      I can't understand why we cannot create a package until a Bill is created? We are having to created draft Bills to create a package when the item is received, but we may not have received a Bill from the supplier. Also, Bill # is required, but we normally

    • Whats the Time out Limit for API Calls from Deluge?

      Hi Creator Devs, We are making API calls to third party server via Deluge. Getting this error message: Error at line : 24, The task has been terminated since the API call is taking too long to respond. Please try again after sometime. Whats the default

    • How to get the authorization code for domain transfer from Zoho?

      I have transferred my domain from zoho to godaddy, and that needs a authorization code. I haven't got any mail containing that. How to get the authorization code from domain transfer? Thanks, Arun

    • Community Digest Agosto 2025 - Todas las novedades en Español Zoho Community

      ¡Hola, Zoho Community! Agosto llega a su fin y septiembre nos trae aire fresco a la comunidad: más inteligencia con IA, actualizaciones que elevan la productividad y la recta final hacia Zoholics España 2025. Aquí tienes lo más destacado del mes para

    • I have error AS101 when I try to add paypal@mydomain.com to Zoho

      Please help me with this. I tried to call the help line 4 times but don't get any response.

    • Tip #3: How to change your booking page language

      Displaying your booking page in your target audience's language can greatly increase customer satisfaction. By speaking their language, you will help customers feel more comfortable scheduling with you and create a stronger connection with them. Let's

    • Next Page