Kaizen #177: Duplicate Check Preferences API vs. Upsert API

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.

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 #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 this

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

    • Kaizen #217 - Actions APIs : Tasks

      Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

    • Kaizen #216 - Actions APIs : Email Notifications

      Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

      • Recent Topics

      • 【Zoho CRM】フィルター機能のアップデート：ルックアップ項目を使ったデータフィルタリング

        ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中からフィルター機能のアップデートをご紹介します。 ルックアップ項目を使ったデータフィルタリングがより詳細に行えるようになりました。 この機能は詳細フィルターとカスタムビューで利用でき、必要な情報を正確に取得できます。 これにより、タブ間を移動することなく、より深く正確な方法でデータを絞り込むことが可能になります。 ◉できること 詳細フィルターとカスタムビューで、ルックアップ先タブの項目が選択可能

      • 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 areas

      • Zoho Books | Product updates | July 2025

        Hello users, We’ve rolled out new features and enhancements in Zoho Books. From plan-based trials to the option to mark PDF templates as inactive, explore the updates designed to enhance your bookkeeping experience. Introducing Plan Based Trials in Zoho

      • Zoho Books | Product updates | August 2025

        Hello users, We’ve rolled out new features and enhancements in Zoho Books. From the right sidebar where you can manage all your widgets, to integrating Zoho Payments feeds in Zoho Books, explore the updates designed to enhance your bookkeeping experience.

      • Weekly Tips: Protect Confidential Information with PGP in Zoho Mail

        We deal with confidential information almost every day, whether it is being sent out or received. Though emails sent using Zoho Mail are encrypted both during transit and at rest, attempts to access and steal your sensitive data are always a threat that

      • Quotes Approval

        Hey all, Could you please help in the following: When creating quotes, how to configure it in a way, that its approval would work according to the quoted items description, not according to quote information. In my case, the quote should be sent to approval

      • Important Update: Facebook Pages API Deprecation

        Dear Zoho Analytics users, As of January 26, 2026, Facebook has officially deprecated Facebook Pages API version 18. This update involves the removal of several metrics that were previously supported by the API. As a result, these changes will affect

      • Adding a Deal to and Existing Contact

        I want to easily add a Deal to an existing Contact. If I click on New Deal on the Contact page this currently this is what happens: All of the mandatory field (and other field) information exists within the Contact. Is there a simple way for it to automatically

      • Custom SMTP is now available in Zoho Sign

        Hi there! Want to send Zoho Sign emails from your organization's or personal email server? Look no further! Zoho Sign has introduced custom Simple Mail Transfer Protocol (SMTP) for Enterprise users across all data centers. By enabling custom SMTP, you

      • Deleting a memorized email address

        How can I delete a memorized email address? Even though the address has been deleted from Contacts, Zoho mail still auto suggests the address when typing it into the TO field. Thanks!

      • Email was sent out without our permission

        Hi there, One customer just reached out to us about this email that we were not aware was being sent to our customers. Can you please check on your end?

      • Flexible Partial-Use Coupons (Stored Value Credits)

        Subject: Feature Request: Ability for users to apply partial coupon balances per transaction Problem Statement Currently, our coupons are "one-and-done." If a user has a $50 coupon but only spends $30, they either lose the remaining $20 or are forced

      • Prevent accidental duplicate entry of Customer Ordersome

        Zoho Support has confirmed that Zoho currently does not have any method (using Deluge, flow or any other method) to alert a user when a sales order has been entered twice using the same customer reference number (i.e. a duplicate). Most ERP platforms

      • Migrating Brevo Automation Logic to Zoho Campaigns

        Hello Zoho Campaigns Support Team, I am in the process of migrating my email marketing from Brevo to Zoho Campaigns. I have around 10,000 contacts, which I have already successfully exported from Brevo and imported into Zoho Campaigns. I now need guidance

      • Is there a way to delete workspaces?

        I want to remove one of the workspaces in my Campaigns account. I don't see any obvious way to do this. Am I missing something?

      • New Custom View -Sorting the Custom fields

        While creating a New Custom View in invoice , Customers, Bills ,expense etc , the sorting of custom fields are not available , a query function "order by / sort by  " may also be included in  Define new criteria module  which will be more beneficial to

      • Make CAMPAIGNS email look as simple as possible

        Hi there I'm trying to make my Campaigns email look as much like a normal email as possible. I'm a bit stuck with the "justification" of the email email block. Can I LEFT JUSTIFY the "whole email" to make it look "normal"? (Please see screenshot attached)

      • Canadian Banks ?

        Can you advise which Canadian Banks can be used to fully sync credit cards and bank accounts? Thanks

      • Sorry! we encountered some problems while sending your campaign. It will be sent automatically once we are ready. We apologize for the delay caused.

        Hello. Lately we are having problems with some campaigns, which show us this error message. Sorry! we encountered some problems while sending your campaign. It will be sent automatically once we are ready. We apologize for the delay caused. We can't find

      • Can I remove or divert certain contacts from an active Campaigns workflow?

        I have created a workflow in Zoho Campaigns, which sends different emails, once contacts have been added to a mailing list. To choose which email to send to the contacts, there are conditions, which divert contacts based on their company type and their company size. There was a subsection of this workflow, where company size wasn't selected correctly, and some contacts have been sent down the wrong path and received the wrong email. The workflow contains a reminder loop and a further series of emails.

      • How to map fields from Zoho Recruit to Zoho People

        I've got these fields from my Job Offer that I'm trying to map to the Work information fields in Zoho People, but they arent showing up. For example, how do I get the department name field (in the job post) to map to the work information field in Zoho

      • UTM in zoho campaigns

        Helloo everybody!!! Someone know how IF ZOHO CAMPAIGNS has UTM for tracking the url of any campaigns. thank u

      • Full Context of Zoho CRM Records for Zia in Zoho Desk for efficient AI Usage

        Hello everyone, I have a question regarding the use of Zia in Zoho Desk in combination with CRM data. Is it possible to automatically feed the complete context of a CRM record into Zia, so that it can generate automated and highly accurate responses for

      • Knowledge base printing

        I saw a posting about printing the knowledge base as I was looking for the answer, but we would like the ability to print out the entire knowledge base with a click, keeping the same organization format.   Bonus would include an index of keywords and

      • Search not working!

        I have items in my notebook tagged but when I search for a tag nothing comes up! Any fix for this?

      • Updates for Zoho Campaigns: Merge tag, footer, and autoresponder migration

        Hello everyone, We'd like to inform you of some upcoming changes with regard to Zoho Campaigns. We understand that change can be difficult, but we're dedicated to ensuring a smooth transition while keeping you all informed and engaged throughout the process.

      • How do i integrate google analytics to Zoho Campaigns?

        Looking to track Zoho Traffic from email Current topic is outdated

      • How do teams manage meeting follow-ups across Zoho tools?

        We’re using Zoho tools for collaboration and tracking, but managing meeting notes, action items, and follow-ups across teams is still challenging. Curious how others are handling this within Zoho workflows. Are there best practices or integrations that

      • Mejoras urgentes para ZOHO MEETING

        Tengo unos meses usando Zoho Meeting. En general, es buena, pero hay cosas vitales que no logra cumplir con mínima calidad. 1) Calidad de audio y video: urge mejoras. Audio con retraso, imagen borrosa, mal recorte de silueta con fondos virtuales. Además,

      • Saving sent email campaign as PDF

        I'm looking to add all campaigns sent to an archive folder in sharepoint. Is there anyway to accomplish this in Zoho Flow ? I'm falling at the first hurdle ... can I automatically save a sent campaign as a PDF to a folder location ?

      • Exporting All Custom Functions in ZohoCRM

        Hello, All I've been looking for a way to keep about 30 functions that I have written in Zoho CRM updated in my own repository to use elsewhere in other instances. A github integration would be great, but a way to export all custom functions or any way

      • Conditional Layouts On Multi Select Field

        How we can use Conditional Layouts On Multi Select Field field? Please help.

      • Appreciation to Qntrl Support Team

        We are writing this topic to appreciate the outstanding level of support from Qntrl Team. We have been using Qntrl since 2022 after shifting from another similar platform. Since we joined Qntrl, the team has shown a high level of professionalism, support,

      • How can I hide "My Requests" and "Marketplace" icon from the side menu

        Hello everybody, We recently started using the new Zoho CRM for Everyone. How can I hide "My Requests" and "Marketplace" from the side menu? We don't use these features at the moment, and I couldn't find a way to disable or remove them. Best regards,

      • Whatsapp Integration on Zoho Campaign

        Team: Can the messages from Zoho Campaign delivered through Whatsapp... now customers no longer are active on email, but the entire campaign module is email based.... when will it be available on whatsapp.... are there any thirdparty providers who can

      • Mandatory Field - but only at conversion

        Hello! We use Zoho CRM and there are times where the "Lead Created Date & Time" field isn't populated into a "Contractor" (Account is the default phrase i believe). Most of my lead tracking is based on reading the Lead Created field above, so it's important

      • Using data fields in Zoho Show presentations to extract key numbers from Zia insights based on a report created

        Is it possible to use data fields in Zoho Show presentations along with Zoho Analytics to extract key numbers from Zia insights based on a report created? For example, using this text below: (note that the numbers in bold would be from Zia Insights) Revenue

      • Free webinar: AI-powered agreement management with Zoho Sign

        Hi there! Does preparing an agreement feel like more work than actually signing it? You're definitely not alone. Between drafting the document, managing revisions, securing internal approvals, and rereading clauses to make sure everything still reflects

      • WhatsApp Channels in Zoho Campaigns

        Now that Meta has opened WhatsApp Channels globally, will you add it to Zoho Campaigns? It's another top channel for marketing communications as email and SMS. Thanks.

      • CRM For Everyone - Bring Back Settings Tile View

        I've been using CRM for Everyone since it was in early access and I just can't stand the single list settings menu down the left-hand side. It takes so much longer to find the setting I need. Please give users the option to make the old sytle tile view

      • Next Page