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

    • Recent Topics

    • PUNJAB NATIONAL BANK (CORPORATE) INDIA - NOT AVAILABLE IN BANKING

      Dear sir, Kindly fix it. PUNJAB NATIONAL BANK (INDIA) is available but PUNJAB NATIONAL BANK (CORPORATE) is not available. Kindly enable this banking since we need to categorize the entries. Regards, Sanjay Jena email id/ user id : travewithmerchant@

    • Amazon invoice in Zoho Books

      I have just made my first few sales on Amazon India. Amazon Seller account generates invoices for the sales made on Amazon. These invoices are sent to customers also. Now when I was only making offline sales, I used to create Invoices in Zoho Book. Now

    • CUSTOM FUNCTION GIVE ERROR #EVAL!

      CUSTEM FUNCTION CREATE KYA ZOHOSHEET ME US FUNCTION KO USE KIYA LEKIN DATA TO SAHI HAI LAKIN DATA SHEET ME NAHI LAG LAHA HAI KRUPYA SOLVE KARE MY CODE IS float ADDTWO_TWO(float NO1, float NO2) { ADD = NO1 + NO2; return ADD; }

    • Zoho ShowTime: Certificates of Completion - Award your learners with a sense of achievement

      In our increasingly competitive market, professional trainers need to differentiate themselves if they are to survive. One way to do this is to focus on innovation and deliver an ideal learning experience. By developing a renowned certificate program that provides learners with a specialized skill set for a particular industry, both trainees and future prospects will recognize the trainer's leadership in that field. This can help with long-term growth, revenue generation, and even marketing and branding.

    • IMAP Migration from Gmail

      I have been trying to import my email from a Gmail server and keep receiving the following error. I have reduced the security, activated imap and no improvement. The link to the Google support item has not helped. Unable to connect to your account. Please

    • Your Incoming has been blocked and the emails will not be fetched in your Zoho account and POP Accounts Click here to get unblocked.

      When entering my account, this error is thrown at me, and I deleted a good part of my deleted messages, but I still can not unblock it, I would appreciate your help. reservas@lineasperutravel.com

    • Request for Creating Multiple Email Accounts on One Mobile Number

      Dear Zoho Team, I am planning to shift all my work-related communication to Zoho Mail because of its reliability and features. For my work, I need to create 3–4 separate email accounts for different purposes. Could you please confirm if it is possible

    • Signature issue

      Problem: The signature does not appear when replying or forwarding an email. solve issue: settintgs/Signature Check option place a signature above the content with quotation marks

    • mail admin not loading

      i am trying to login to mailadmin ... gears keeps rotating forever... its not a password issue whats so ever ... not cookies issues whatsoever from android app i can login but there so few things to do from there .. i changed ip address the same... i

    • Unify All Zoho Video Meeting Experiences into One Standardized Platform

      Hi Zoho Team, We would like to share an important user experience concern regarding the current state of video meeting functionality across the Zoho ecosystem. The Problem Within Zoho, there are multiple ways to initiate or schedule a video meeting: Zoho

    • Changing Account in Quote form does not update address information.

      I am trying to update the address information in a quote I've created. I corrected the address in the "Account" but that did not change in the quote. If I re-enter the Account Name in the Quote form, nothing updates. How do I fix this?

    • Zoho One Backup of entire account

      Hello, When using Zoho one is there a way to backup your entire account of all apps that you are using \ activively using in a single step or do you have to backup each applications data individually? Thanks,

    • ZIA in Zoho Cliq

      Is It possible to use the ZIA feature from Zoho Analytics in the Zoho Cliq?

    • Issue with “CC” and “Subject Details” of the initial mail when reply / replied all / forward using Zoho Mail Client (Desktop / Web Mail / Mobile App)

      It is observed that when I reply / reply all / forward a mail using Zoho Mail Client (Desktop / Web Mail / Mobile App), the “CC” and “Subject Details” are omitted from the mail which was replied/forwarded. However this is not the case with outlook mail

    • Unable to send Emails - 452 4.3.1 Temporary System Error

      Whene ever i request smtp server to send the email (without attachment). i recieve error "452 4.3.1 Temporary System Error"

    • I can't receive email

      I cannot receive any email sent to my Zoho email after the free upgrade plan trial is finished.

    • Help for the alisa adding

      Sorry, I would like to add a paypal alias on my domain email address. However, the system blocked it. How can I do it?

    • Problem with Writer and Workdrive

      Hi team, I’m the super admin for our Zoho One org. WorkDrive is active, and Zoho Docs is deprecated for our org. However, Zoho Writer cannot connect to WorkDrive at all — we’ve cleared cache, tried incognito, and restarted several times. I was able to

    • Lite plan attachment said 250mb but actually 25mb ?

      Lite plan attachment said 250mb but actually 25mb ? I can't attach over 25mb files, and can't receive mails has attached files over 25mb too

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

    • Can no longer export as pdf

      In NOTEBOOK I am no longer able to export notes to pdfs as I used to be able to. When I hit that command it asks where I want to send it, but no matter what I chose there is no pdf attachment that shows up in order to send. Nothing happens.

    • Option to Customize Career Site URL Without “/jobs/Careers”

      Dear Zoho Recruit Team, I hope you are doing well. We would like to request an enhancement to the Career Site URL structure in Zoho Recruit. In the old version of the career site, our URL was simply: 👉 https://jobs.domain.com However, after moving to

    • Old vs New Value for Deleted Lookup Values

      Suppose the following scenario, where a value in a lookup is deleted: 1. User has countries form 2. Form A has a lookup to countries form 3. User selects Italy in Form A and saves it with the Italy ID 4. Form A report shows Italy 5. Italy is inadvertently

    • Desktop app doesn't support notecards created on Android

      Hi, Does anybody have same problem? Some of last notecards created on Android app (v. 6.6) doesn't show in desktop app (v. 3.5.5). I see these note cards but whith they appear with exclamation mark in yellow triangle (see screenshot) and when I try to

    • customize payment page

      Is there a way to customize, other than the theme colour, the payment page that customers are taken to from invoices? I can't seem to find a way. I just don't like the formatting of the current page and would like to make it look better. I've looked at

    • Are Environments Worth It?

      In concept, Environments in ZC is a great idea. I think the flow is pretty smart when you compare it to GitHub, especially for a low code audience. However, in practice, I've found it to be unpredictable, and I've only used it a few times. Aside from

    • Enhanced duplicate check for Leads in CRM

      Hello Everyone, We are excited to announce that you can now check for duplicate entries in leads by comparing them with similar records in the Contacts Module. Previously, when you added a lead, only the converted leads were checked for duplicates. This

    • Pause(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 is

    • Integration Request: Elementor

      Integrating Zoho CRM forms with Elementor, the most popular page builder on Wordpress, would be great. I use it for our site, goenergylink.com, and I have had to use Zapier webhooks to be able to connect it with Elementor. The one issue I have run into

    • Vertical images displayed as horizontal

      Some pictures that originally are in vertical position are displayed in horizontal after the upload. It seems that system rotates them by 90 degrees. How can I fix this issue?

    • Ability to Change Visibility of Published YouTube Videos

      Hi Zoho Social Team, How are you? We would like to request an enhancement in Zoho Social regarding the management of already published youtube videos. Currently, after publishing a youtube video through Zoho Social, there is no option to change its visibility

    • Adding anchor links in Zoho CRM email templates

      I know you can add anchor link in Campaigns, but I dont see the option to that in the CRM email template. Am I missing something?

    • Support “Never End” Option for Recurring Meetings in Zoho Meeting

      Hello Zoho Meeting Team, Hope you are doing well. We would like to request support for creating recurring meetings with no end date in Zoho Meeting. Currently, when scheduling a recurring meeting, Zoho Meeting requires us to select a specific end date.

    • openUrl in blueprints

      My customer wants to open a URL at the end of a blueprint transition. Seems this isn't possible right now but it would be very useful. In this thread, https://help.zoho.com/portal/en/community/topic/openurl-not-working the Zoho agent said that it's logically

    • Is it possible to pull the Zoho desk data into Zoho analytics in real time

      Hi - I am looking to add more dashboards and reports of Zoho Desk in analytics. I see there is a schedule to pull the data into analytics, but I'm wondering if there is an option to pull the data in real time instead of a specific interval?

    • CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

      Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

    • Introducing the revamped What's New page

      Hello everyone! We're happy to announce that Zoho Campaigns' What's New page has undergone a complete revamp. We've bid the old page adieu after a long time and have introduced a new, sleeker-looking page. Without further ado, let's dive into the main

    • Ability to Add YouTube Video to Playlist During Publishing

      Hi Zoho Social Team, How are you? While publishing YouTube videos through Zoho Social, we noticed that the platform currently does not allow selecting a playlist at the time of publishing. Instead, we can only add the video to a playlist after it has

    • Introducing Zoho Creator's 2025 Release Projection 2

      Hello Creators! I'm Prakash, from the Creator product management team, and today I'm delighted to unveil our next set of features as part of Release Projection 2 for 2025. With thoughtful analysis and planning, we've curated powerful new capabilities

    • Sharing Form Ownership Among Multiple Users

      I would really like the ability to share form ownership among multiple users. It's frustrating to me that if a co-worker wants to make an edit to a form, I have to transfer ownership to them. It would be great if forms could act like google forms, where multiple people can edit a form and view responses. 

    • Next Page