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

    • Provide a standard structure to your content using article templates

      Hello everyone, When multiple writers work on different documents, maintaining a standard structure can be challenging as each of the writer follows a different writing style. However, when the structure, tone, and format of every document is different,

    • How to update custom multi-user field in Zoho Projects?

      I'm trying to update custom multi-user fields in Zoho Projects via a Deluge function in CRM. The code I have so far is below. It works for updating standard project fields and single-line custom fields, but it does not work to update multi-user fields.

    • Accessibility Spotlight Series - 1

      Every user interacts with products differently, what feels intuitive to one may be challenging for another. Addressing this, accessibility is built into Zoho Project's design philosophy. This helps users navigate and perform actions with ease irrespective

    • Projects Tasks Not Showing Dependencies

      I'm clicking on tasks and the popup to add dependencies isn't showing. I can't disconnect the nodes either. For some reason when I slide a task backwards it says it cannot go before a predecessor, even though there is not predecessor. Double clicking

    • Deprecation of C4 endpoint URLs

      Note: This post is only for users who are still using the C4 endpoints. Hello everyone, At Zoho Creator, we're committed to continuously enhancing the security, performance, and capabilities of our platform. As part of this ongoing effort, we'll be deprecating

    • Introducing AWS authentication for connections in Deluge

      Hello everyone, We're incredibly excited to announce the all-new AWS authentication for connections in Deluge! This highly anticipated feature simplifies connecting to Amazon Web Services, opening up a world of possibilities and allowing you to seamlessly

    • Timeline Tracking Support for records updates via module import and bulk write api

      Note: This update is currently available in Early Access and will soon be rolled out across all data centers (DCs) and for all editions of Zoho CRM. The update will be available to all users within your organization, regardless of their profiles or roles.

    • Customize User Invites with Invitation Templates

      Invitation Templates help streamline the invitation process by allowing users to create customized email formats instead of sending a one-size-fits-all email. Different invitation templates can be created for portal users and client users to align with

    • ListObjects is recognized by VBA

      Sub addNewRow() Dim ws As Worksheet ' Set your worksheet name Set ws = ThisWorkbook.Sheets("Invoice") ' Set your table name (change "Table1" to your actual table name) ws.ListObjects("InvItems").ListRows.Add End Sub I am getting Unknown function: Li

    • KPI Widget dashboard select periods

      I have a problem with selecting periods as a user filter. In the beste scenario I would like to have to have a period filter like Google Analytics has of Datastudio (see attachment). In the KPI widget I "Group by "inquiry_date" on week&Year". It selects

    • Need a way to secure Prefill URLs in Zoho Forms (hide or encrypt prefilled values)

      Hi everyone, I often use Zoho Forms with prefilled URLs to simplify the user experience — for example: https://forms.zohopublic.com/.../form?Name=David&Amount=300 However, the problem is that all prefilled values are visible and editable in the link.

    • Can’t send emails from Zoho CRM after adding a new user — verification codes not received

      Hi everyone, We recently added a new user to our Zoho CRM account and purchased an additional license. Since then, we haven’t been able to send any emails from Zoho CRM. Our Zoho Mail accounts are working perfectly, we can send and receive emails directly

    • Can I add Conditional merge tags on my Templates?

      Hi I was wondering if I can use Conditional Mail Merge tags inside my Email templates/Quotes etc within the CRM? In spanish and in our business we use gender and academic degree salutations , ie: Dr., Dra., Sr., Srta., so the beginning of an email / letter

    • CRM for email in Outlook: how to ignore addresses?

      We’re using the "Zoho CRM for email" add-in for Outlook. When opening an email, the add-in displays all email addresses from the message and allows me to add them to the CRM or shows if they’re already contacts. However, sometimes people listed in To

    • Scheduling Calls in CommandCenter / Blueprints

      I would love it if you could add a function to schedule a call in the lead's record for a future date. I know you can add a Task by going to Instant Actions > Task and completing the form: These tasks go into the lead's record under Open Actions. But

    • Workflow Creation with Zia gets stuck

      It gets stuck here:

    • Quickly send emails and sync conversations with custom email addresses in CRM

      Editions: All editions DCs: All DCs Release plan: This enhancement has been released for customers in all DCs except IN and US. We will be enabling it for IN and US DC customers soon. [Update on 22 May 2024] This enhancement has been released for all

    • Zoho製品と生成AIツールの活用について

      いつもありがとうございます。 弊社では、Zoho Oneを契約し、CRMを軸として、見込み客の管理から商談、その後の受注や請求の管理、サポート業務（Desk）、業務データのレポーティング（Analytics）などを行っております。 Zohoサービス自体には、Ziaというツールが搭載されているかと存じますが、それ以外の外部の生成AIツールと連携した活用などもできるのでしょうか？具体的には、CopilotなどがZohoに登録されているデータや情報を見て、対話型で必要なデータを提示してくれたり、商談や蓄積されたメモなどを分析してユーザが知見を得られるような活用ができないか、と考えております。

    • Work with Contacts who use multiple Emails / Manage obsolete Email addresses without loosing Emails in Context

      Hello List Work with Contacts who use multiple Emails Only after 1 week in using Zoho CRM productively we have contacts which randomly use 2 different email addresses. From the concept I've understood that Zoho CRM offers two email fields which are recognized

    • New Field in CRM Product Module Not Visible in Zoho Creator for Mapping

      I created a new single-line field in the Products module in Zoho CRM. Zoho CRM and Zoho Creator are integrated, but the newly created field in CRM is not visible in Zoho Creator when I try to map fields.

    • Send WhatsApp voice messages from Bigin

      Greetings, I hope all of you are doing well. We're happy to announce this enhancement we've made to Bigin. Bigin's WhatsApp integration now supports audio messages, so you can record and send voice messages. This makes it easier to handle customer questions

    • Microsoft Teams now available as an online meeting provider

      Hello everyone, We're pleased to announce that Zoho CRM now supports Microsoft Teams as an online meeting provider—alongside the other providers already available. Admins can enable Microsoft Teams directly from the Preferences tab under the Meetings

    • I want to subscribe 1 professional user but the email only 250 per day?

      When I subscribe 1 professional user, I am only able to send 250 email per day? So less? Or is it typo, 2500 rather than 250? Any sale agent or friends can clear my doubt? Thank You

    • How to add a % Growth column for year-over-year comparison (2024 vs 2025)

      Hello, I am trying to build a monthly revenue comparison between 2024 and 2025 in Zoho CRM Analytics. My current setup is: Module: Deals (Affaires) Filter: Stage = Closed Won Date field: Closing Date Grouping: By Month Metrics: Sum of Amount for 2024,

    • How do you map a user picklist field to another user picklist field.

      In Zoho Projects, I'm trying to map a custom field (user picklist) in Task Details to a field (user picklist) in the Project Details. How do you get the two to map to each other? This is what I currently have that works for my other fields but doesn't

    • Explore Competitive 3D Scanner Prices at Protomont Technologies

      The genesis of Protomont Technologies emerged from the collaborative efforts of the founders in 2019, both the founders shoulder an enormous experience in the world of 3D Printing. Protomont Technology aims to craft your vision with creativity, empowering

    • New and improved API resources for Zoho Sign Developers

      Hello, Developers community! We know that for you, an API's real value depends on how quickly, easily, and reliably you can integrate the it with your application. That's why we're excited to talk about the recent improvements to our developer resources,

    • stock

      bom/bse : stock details or price =STOCK(C14;"price") not showing issue is #N/A! kindly resolve this problem

    • Project Approval Process Workflow

      Issue: When a new Project is created, there is lack of process/workflow that provides their manager a process to approve or review. Suggestion/Idea: Similar to “Workflow”, we need “Workflow” ability at Project level, where based on the criteria of the

    • Marketing Tip #5: Improve store speed with optimized images

      Slow-loading websites can turn visitors away. One of the biggest culprits? Large, uncompressed images. By optimizing your images, your store loads faster and creates a smoother shopping experience leading to higher sales. It also indirectly improves SEO.

    • Why can I not choose Unearned Revenue as an account on items?

      Hello, I do not understand why we don't have the ability to code an item to unearned revenue. It is not an uncommon situation to have in business. I understand that there is the Retainer invoice as an option, however that doesn't really work for us. Our

    • Form Submission Emails

      Is there a current delay with submission emails being sent? We've had 10-20 forms completed today but only a handful of emails.

    • Rules not working properly

      I created a rule to display certain fields on certain states. But it seems to be not working. It hides the fields even when I selected California, (which is a state that should show the fields when selected)

    • Notebook font size issue

      If I copy something from somewhere and paste it in my notebook, the font size becomes smaller.

    • Sign in process is beyond stupid. I'd rather plug my phone into USB and copy files than sign in to this POS.

      792 clicks and fields to fill in just to get into a 3rd rate app is too stupid for me.

    • Ampersand in URL parameter // EncodeURL does not work

      Hi Zoho, I have a url link with a parameter. The parameter is including ampersand in some cases (Can be "H&M" or "P&I") When trying to use %26 instead of "&"  (the result I get using EncodeURL()) I get H%26M instead of H&M in the parameter field. How can I solve this? Thanks! Ravid

    • how can we create in zoho crm a new contact when the looup does not find a similar existing one

      In forms/integrations/zoho crm / ne w record tab, contact name is to be mapped with my form contact name. When I go in biew edit/lookup configuration, I don t get the options (help dedicated page simply repeat the same info you get in the app) and does

    • Directory Websites

      Directories are a good website category to gain search engine traffic. Directories for a professional service category as an example can help their members in search results over their individual website. It would be nice to have a directory template

    • Manage Task on Mobile

      How do we manage our task on mobile devices? It seems that there should be a standalone mobile app to handle the new task features. The new features released in regards to Task management are great by the way! Now we need to bring that all together in

    • Set Default Payment Method & Default account

      Hi, I would like to know how to set the default payment method and default bank account when recording payments in zoho books. At present we have to change these fields everytime we record a payment, which leads to potential error and as we have a very

    • Next Page