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

    • scroll bar for far left of screen

      I am unable to even see the scroll bar to the right of "inbox" etc on the left; it is stuck at "streams" and I can't get to inbox or anything else. It would help if it could be made a lighter color as the black or dark grey can't bee seen.

    • OUt of office every friday

      Hi, I tryed to configure my out of office, because i'm not working or emailing on fridays. But when i select only friday as unavailable day, the out of office still sets for the whole week. What am I doing wrong?

    • Signature line

      How do I set signature line in email

    • Zoho email

      I cannot send email to mail.ru

    • 【参加無料】東京 Zoho ユーザ交流会 NEXUS ー CRMで始めるマーケティング事例 / AI活用法(Zia Agents)

      ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で東京 Zoho ユーザー交流会 NEXUS を開催します！ 昨年度までより、さらにパワーアップして戻ってきました！ ユーザー活用事例は、2人のユーザーさんからお話しいただきます。Zoho サービスの活用の幅を広げたい方や、他のユーザーの利用法を気軽に知りたい方など、多くの方にとって学びのあるセッションになること間違いなしです✨ また今年は、これまで以上に、AI機能にも焦点を当てて行く予定です。 初回として、Zoho社員からZoho

    • Issue Exporting Data – CSRF Token Invalid Error

      Dear Zoho Team, We are experiencing an issue when exporting data from our Analytics workspace. Whenever we attempt to export data from our analytical pool, the system displays the following alert message: Alert Message: The CSRF token is invalid. It could

    • Deluge Learning Series – Client functions in Deluge | January 2026

      We’re excited to kick-start the first session of the 2026 Deluge Learning Series (DLS) with Client functions in Deluge. For those who are new to DLS, here’s a quick overview of what the series is all about: The Deluge Learning Series takes place on the

    • Zoho Mail 505 error I can not send email

      Hi, I’m having issues sending emails from my custom domain email address. When I send emails to Outlook addresses, I receive an “Undeliverable 505” error. However, emails send and receive correctly when I use Gmail. This is important for my business,

    • Multiple MFA Methods

      With SMS-based MFA methods being discontinued, there is now no way to have mutliple MFA methods. I'd like to add my zoho account on two seperate phones using the Google Authenticator app. In the https://accounts.zoho.com/home#multiTFA/modes you can only

    • Reuse Standalone Function

      I noticed that there's a missing information in documentation to reuse a standalone function and it is because the parameters require an argument. Here is my code and it is working. response = invokeurl [ url: "https://people.zoho.com/api/v3/function/sample/execute"

    • Domain renewals

      Need to know how hoe to renew the domain

    • MX shopify problem

      hello, i added all MX values in my shopify DNS - it shows those values on the shopify panel + your toolkit. I tried to send some email and it works, however on my gmail it says they cant verify this email. When i try to answer into my domain's email -

    • im facing issue on generate the Estimate price

      i couldn't understand what is the issue , i cant generate Estimate price where is the issue

    • Best Way to Manage Email Notifications While Running a Strategy Website

      I am currently managing a content-based website, and I use Zoho Mail for handling contact forms, user queries, and collaboration emails. One challenge I am facing is organizing incoming emails efficiently, especially when messages come from different

    • What is the maximum email domains ?

      I help manage about 20 associations and I'm looking for a way to centralize them in one place. Does Zoho Mail pro or enterprise support 20-30 domains for 3-5 users each?

    • Add to Workdrive filter

      I'm trying to create a filter that will upload attachments in emails and the e-mail body to a folder in workdrive. I am able to do one or the other (attachment, or e-mail content), but not both. I first tried it using the "Email (EML) + attachment" option.

    • Forgot my admin Panel Id and password

      Sir, I have an account , where a domain mycityestate.in is added for Zoho email , now it is hard for me to manage email because i have forgotten the Email account and password registered with Admin Panel of Zoho. Just need email name which is registered

    • MCP no longer works with Claude

      Anyone else notice Zoho MCP no longer works with Claude? I'm unable to turn this on in the claude chat. When I try to toggle it on, it just does nothing at all. I've tried in incognito, new browsers, etc. - nothing seems to work.

    • Knowledgebase SEO

      We have a custom-domain mapped help center that is not restricted via login. I have some questions: a) will a robots.txt file still allow us to control indexing? b) do we have the ability to edit the sitemap? c) do category URLs get indexed by search

    • Partial payments for retainer invoices

      When a customer does not pay the entire retainer invoice there is no way to apply a partial payment. PLEASE add this function.

    • Problem with CRM Connection not Refreshing Token

      I've setup a connection with Zoom in the CRM. I'm using this connection to automate some registrations, so my team doesn't have to manually create them in both the CRM and Zoom. Connection works great in my function until the token expires. It does not refresh and I have to manually revoke the connection and connect it again. I've chatted with Zoho about this and after emailing me that it couldn't be done I asked for specifics on why and they responded. "The connection is CRM is not a feature to

    • New Features: Repeat Last Action, Insert Cut/Copied Rows/Columns and Hyperlink

      You might have noticed the constant updates to Zoho Sheet of late. Here are 3 more features that have been added to Zoho Sheet recently: F4 - Repeat Last Action Insert Cut/Copied Rows and Columns Insert Hyperlink Here is a screen cast demonstrating each of these features. Read further below to learn more about these new features. F4 - Repeat Last Action: You can now repeat the last action you made on your spreadsheet by using the keyboard shortcut, F4. It is quite handy and helps you get your work

    • Need help getting my mail on iPhone and Tablet

      I need to access my Zoho mail via the iPhone Mail app. I have entered the login name, password and the incoming and outgoing servers, which my Mail Settings page says are imappro.zoho.com and smtppro.zoho.com. The iPhone keeps saying it cannot authenticate.

    • Add an background image to an email template in CRM

      Hi all, We wants to put an background image behind all our email templates. Is there a way to import this thru html. If i put the option background image in <body style="background-image:...</body> and i look to the preview it shows our background, but

    • Is there a way to show contact emails in the Account?

      I know I can see the emails I have sent and received on a Contact detail view, but I want to be able to see all the emails that have been sent and received between all an Accounts Contacts on the Account Detail view. That way when I see the Account detail

    • How do I bulk archive my projects in ZOHO projects

      Hi, I want to archive 50 Projects in one go. Can you please help me out , How can I do this? Thanks kapil

    • Copy contents of File Upload Field into Workdrive

      Hello, I have set up our CRM so that a Workdrive folder is automatically created for each Deal via workflow, this adds the id of the folder into a dedicated field. We also have a field on each Deal called 'Approved Layout', which is a file upload field.

    • ZeptoMail API

      Hello Since today, we experience issues with the ZeptoMail API. When trying to send e-mails using: https://api.zeptomail.eu/v1.1/email we receive the error: (503) Site unavailable due to a traffic surge. Please try again shortly. I kindly ask you to identify

    • 553 Relaying disallowed. Invalid Domain - gzkcompany.ro

      Hi there, Can you please assist me in getting the right domain settings? I just renewed my domain subscription, after expired and i got error: 553 Relaying disallowed. Invalid Domain - gzkcompany.ro Zoho mail can receive emails, but its impossible to

    • Not able to receive emails for a while

      I am not able to receive emails for a while now.

    • Confirmation requested: eligibility and process to downgrade to Forever Free — tenant bigbanghawking.com

      Thank you for your reply. I am testing Zoho Mail from Brazil with the tenant bigbanghawking.com (endpoint: mail.zoho.com) and we are currently on the Premium trial that expires 21/01/2026. Before deciding whether to pay or cancel, I need written confirmation

    • Add line item numbers to sales order/invoice creation page

      It would be really helpful if there were line numbers visible as we are creating a sales order and/or invoice. There are line numbers visible in the PDF once the sales order is created. I would like to be able to see the line numbers as I am building

    • Zoho API v2.0 - get ALL users from ALL projects

      Hello,        I've been trying to work on an automatization project lately and I find it difficult to work with this strict structure. To be more explicit, if i would like to get all users participating in a project i would need to get all projects first.       Same thing with projects. If i want to get all projects, I would need to get all portals first.        The problem with this aproach is that it consumes a lot of time and resources.             I want to ask if there is another way of getting

    • الموقع لا يقوم بالسداد

      السلام عليكم ورحمة الله وبركاته وبعد من أمس وانا احاول السداد للدومين YELLOWLIGHT ولا اتمكن من السداد اقوم بتعبئة جميع البيانات ولكن دون جدوى يطلع لى حدث خطأ ما

    • New in Office Integrator: Enhanced document navigation with captions and cross references

      Hi users, We're pleased to introduce captions, table of tables and figures, and cross-references in the document editor within Zoho Office Integrator. These features allow you to structure documents efficiently and simplify document navigation for your

    • Where Do I set 24h time format in Cliq?

      Where Do I set 24h time format? Thanks

    • 🎉 ¡Seguimos trayendo novedades a Español Zoho Community! 🎉 Confirmada la agenda y ubicación para los Workshops Certificados

      Si todavía no te has hecho con tu entrada para nuestros Workshops Certificados del próximo 26 y 27 de marzo o, por el contrario, estabas esperando que confirmáramos dónde los celebraremos, ¡este post es para ti! 📍¿Dónde nos vemos?📍 Nuestros Workshops

    • User is already present in another account error in assigning users to marketing automation

      Hello everyone Greeting, I had a problem in assigning user in marketing automation, when I try to add it I see this error: (User is already present in another account error) what should I do?

    • How do I get complete email addresses to show?

      I opened a free personal Zoho email account and am concerned that when I enter an email address in the "To", "CC", fields, it changes to a simple first name. This might work well for most people however I do need to see the actual email addresses showing

    • What's New in Zoho POS - January 2026

      Hello everyone, Welcome to Zoho POS’s monthly updates, where we share our latest feature updates, enhancements, events, and more. Let’s take a look at how January went. Sort and resolve conflicts Conflicts are issues that may arise when registers and

    • Next Page