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

        • ¿Puedo migrar mi sitio desde WordPress a Zoho? ¿Zoho admite herramientas con código personalizado?

          ¡Hola comunidad! Estoy evaluando la posibilidad de migrar mi sitio web https://calculadoradenotas.cl/ desde WordPress a una solución Zoho, y tengo algunas dudas técnicas que espero puedan aclararme. Mi sitio no es solo informativo: es una herramienta

        • Automating SharePoint Folder Creation based on Equipment Module

          Dear Team, I would like to seek your valuable advice on one of my requirements. My objective is to automatically create a SharePoint folder whenever a record is created in the Equipment module. The folder should be named based on the equipment name. Once

        • Can I view a gallery of attachments related to an Account, Contact, or Subscription

          It is often useful to review photos related to an account or contact by service type. It would be nice to be able to see the photos collected through workorders or appointments all associated.

        • Language Field on Contact Person-level

          Dear at Zoho Books, would it be possible for you to have a Field for 'Language' for the Contact Persons under a Company. In CRM and Bigin we could create a Custom Field (Dropdown) for this effect but without any present in Zoho Books we could never sync

        • Customise Zoho FSM Work Order Name

          Hi there, is there a way for us to customise the work order number? For example - I want to add auto look up for company name or dates at the end of the work order number. WO4 - Company ABC

        • Introducing Dynamic Display in Zoho CRM mobile apps

          Hello everyone, We're happy to announce that Dynamic Display is now available in the Zoho CRM mobile app for both iOS and Android devices. Mobile apps have become synonymous with convenience and flexibility. As more and more businesses rely on mobile

        • How we can integrate pdf attachments in zoho crm with xero

          when i tried to integrate the data and attchment from zoho crm to to xero only the data get integrated with xero how we can integrate the pdf attachment as well nb zoho apis are not working via functions

        • Delete user profile

          Hello, How can I delete a User Profile?

        • Send emails directly via Cases module

          Greetings all, The ability to send emails from the Cases module, which users have been eagerly anticipating, is now available, just like in the other modules. In Zoho CRM, Cases is a module specifically designed for managing support tickets. If your organization

        • Introducing delegate signing in Zoho Sign

          Hi everyone! We are happy to announce a new feature in Zoho Sign — Delegate Signing! Whether you're tied up in meetings, away on vacation, or managing multiple responsibilities, you can now assign a delegate to sign documents on your behalf. This ensures

        • Deleting Salutation Field

          We have updated our lead input screen and 'Salutation' has appeared. This is not visible in the 'Edit Pgae Layout' screen so cannot be moved to 'List of Removed Fields'  Salutation is visible in the list in 'Customization - Fields' however I can only 'Edit' or 'Replace' I cannot delete and I do not need this field on my lead input screen.  Please can you advise how to get rid of this.  Screen shots can be provided if needed.  Thank you Tasha

        • Zoho Voice VS in Zoho CRM for logging calls

          I don't understand the differences between logging calls in Zoho Voice VS in Zoho CRM. Why the 2 separate platforms? Seems confusing

        • Updates to Auto-Upgrade in Zoho Campaigns

          Hello everyone, We've rolled out a new update that slightly modifies how the auto-upgrade option in Zoho Campaigns works. Even if you hit the contact limit, this update ensures that your account is upgraded and that contacts are imported smoothly—without

        • Adding Sub-Forms to Merge Documents

          I am setting up a Mail Merge, which includes sub-form table data. I've done it before but now I am having issues: 1. The headings don't show. I had to enter these manually 2. The table lines are separated. I want them together. Anyone know how to fix

        • Zoho Bookings Online Training | July 31, 2025

          Hi everyone! We’re back with the second session of our Zoho Bookings training series! This time, we’ll show you how to automate your scheduling, manage appointments more efficiently, and explore advanced features for your industry. Join our free, two-hour

        • Translation of Tooltip Messages

          The descriptive help messages should be available to provide translations for.

        • Delete Inactive Zoho Accounts - Access Cleanup_User Id: 60001640923

          As part of our Zoho access hygiene, we’ve reviewed and deactivated several inactive user accounts. These accounts have not been used in the past year and are no longer tied to active operations. All access rights have been revoked, and records retained

        • CREATE button is grayed

          On Android adding new notes to notebooks with collections is impossible because the CREATE button is grayed. What can be done?

        • Can Zoho Creator Apps have multiple actors and steps? Example

          Mortgage Application App- Outside party fills out form via published website form, Inside party approves for additional documentation, outside party recieved requests for x, y, and z documents.  Outside party submits x, y and z but z is wrong.  Inside

        • How to download all attachments from inbox, send, other folders in one go

          Hi All, Appreciate if anyone could help me with steps for below requirement. How to download all attachments from inbox, send, other folders in one go. Even mapping to new folder will help me.  Thanks in advance. 

        • Re-Apply SLA When Ticket Reopened from Closed Status?

          If you have an SLA applied, timers are deactivated when going to "On Hold" status type and reactivated when going back to an Open status type. What we discovered is when a customer replies to a closed case and it reopens, the SLA is not applied and timers

        • Zoho Expense Reimbursement

          I am using Zoho Expense for employee expenses.  At year end I accounted for reimbursement for the founders' expenses by doing a manual entry between employee reimbursements and shareholder loan.  All is correct in the balance sheet, but in Zoho expense the expense report totals are showing as owing still.  It doesn't impact the books, but I don't want to see amounts owing.  How can I zero these out?  The only way I can see it is by creating a transaction in Books that pays the employee via a bank

        • Request to Delete Mistakenly Created Zoho Desk Account – Access Blocked to Company Directory

          Dear Zoho Support Team, I hope this message finds you well. I am writing to request assistance regarding a Zoho Desk account I mistakenly created using my company email address. I created the account before being officially onboarded by my company, and

        • Introducing an AI-driven CAPTCHA for Help Center that offers improved accessibility and enhanced security | Zoho Desk | Product Update

          Captcha protects your help center from fraud and abuse without creating friction. What is a CAPTCHA? CAPTCHA is a test used in computing to verify that a user is human by requiring them to complete a challenge. It helps prevent bot attacks and reduce

        • Announcing new features in Trident for Windows (v.1.29.4.0)

          Hello Community! Trident for Windows just got better! It’s packed with new features designed to enhance communication, manage important information securely, and give you a smoother, more productive experience. Let’s dive into what’s new! Access Zoho

        • Exporting Ticket Threads/Comments and Attachments in Reports

          Hi, I would like to know is it possible for Ticket Comments and/or Attachments to be displayed in Reports?

        • Product management across integrated apps

          Hi everyone, I’m setting up my business for selling products and integrating CRM, Inventory/Books, Ecommerce, and other apps. Where should I load products for the first time so they reflect across all apps? And for updating prices or adding new products—where

        • Calculate Number of Days Between Two Dates

          Can someone help me with how to create a field using the formula function to calculate the number of dates between a campaign start date and end date? The closest I have gotten is using the "Datecomp" function but it gives you the dates in minutes, rather

        • Zoho Writer Docx files not able to be converted into Google Docs

          Since July 23rd, I've encountered an issue where DOCX files exported from Zoho Writer no longer convert properly into Google Docs when uploaded to Google Drive. My workflow relies on generating merged DOCX documents from Zoho Forms using Zoho Writer templates,

        • Schedule Campaign - Recipients Time Zone

          Something seems to be wrong with the scheduling feature for scheduling campaigns to be deployed at a specific time to the recipients time zone. I scheduled campaigns twice to be sent at the recipients time zone and the campaigns are deploying at the wrong time. When communicating with Zoho support they said to make sure it was scheduled at least 24 hours in advance so we did this with our last campaign and it was still deployed at the wrong time. Anyone else having this issue?

        • Zoho Vault App for Windows

          Hello, is there a Windows app that can be used to access the passwords saved in Zoho Vault? Thank you

        • Zoho Cursor Jumping

          Hi, Zoho Support, We received the below email for a bug when using Zoho on Firefox. Please let us know if there is anything that can be done to solve this issue. Have any other Zoho Mail users reported issues the past few days with Zoho auto-saving drafts

        • tomorrow option within the due date section and drag and drop into calendar

          Firstly, thank you for creating such a well-designed and user-friendly to-do list app. It’s almost perfect for my needs, but I wanted to offer a couple of suggestions that I believe could significantly enhance its usability, particularly for those who

        • low quality videos

          when in puplish videos or reel in social media platforms it pulished in low quality

        • Using Zoho Forms vs Zoho Survey

          Hello - I'm looking for advice on whether to use Zoho Survey or Zoho Forms for our small non-profit. We have a Zoho One subscription, so have access to both. The main use case at the moment is application forms for our professional development programs.

        • Kaizen #200 - Answering Your Questions | Authentication using Zoho CRM Python SDK

          We’re incredibly excited to bring you the 200th post in our Kaizen series! This journey has been as much about listening as it has been about sharing. And today, we’re making both count. Over the past few weeks, we’ve collected your feedback through the

        • Zoho CRM sync

          Just wondering if the plan is for the Zoho CRM implementation to always be just an import and not a sync? At the very least, a one-way sync that kept the data in Tables up-to-date would increase the amount of usecases, but ideally the option to two-way

        • Add serial number in print page list

          How can i add serial number in print page for every entries?

        • Trying to Delete records from Creator not found in CRM

          Hi, In the following script, I am trying to delete records from Creator not found in CRM, but I am getting the error message "Error at line number: 55 Improper Statement Error might be due to missing ';' at end of the line or incomplete expression". Please

        • Can't login to Zoho mail

          I'm logged into Zoho but when I try to go in zoho mail I get: Invalid request! The input passed is invalid or the URL is invoked without valid parameters. Please check your input and try again. I just set up my mx records and stuff with namecheap a few

        • Next Page