Duplicate Check Preferences API vs. Upsert API

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


      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ








                                ご検討中の方

                                  • Recent Topics

                                  • How to stop workflow running twice on a record

                                    Hi I have a workflow as below Trigger: Lead record is created/edited - Repeat this workflow whenever a lead is edited is NOT TICKED Condition: When Lead Stage is MQL Action: Reassign Lead, Create Task If the Lead goes into stage MQL, and then it changes

                                  • Zoho invoice doesn't support Arabic language

                                    I added a clause in the terms & conditions section in Arabic but it doesn't appear when I sent or print it.

                                  • Using lookup field in Formula field

                                    I created the following formula field to get string output based on Lookup field values Lead and Account: if(${Communications.Lead}!='','Lead',if(${Communications.Account}!='','Account','Other')) The syntax seems correct, but I'm still getting an error.

                                  • Merge Join PDFs Zoho Creator

                                    Hi all, I have a field where users upload PDF, is it possible to join those pdfs into one with a function or something? Regards.

                                  • Customize the ticket ID for enhanced ticket tracking

                                    Hello everyone, Ticket IDs in Zoho Desk are the unique reference numbers that are assigned to tickets when they're created. Agents generally use the ticket ID to locate a particular ticket and to reference a ticket in conversations and feeds. When customers

                                  • Set a global default filter to All Candidates view

                                    Hi, Is it possible to set a global filter to the All Candidates view? As a use case would be for off-limit candidates. These are those who are off limits due to previous bad client feedback on performance/behaviour. Ideal use case would be to set these

                                  • Can't join canal Developers Zoho User

                                    Hello, I received an invitation to join this channel, but I get an error when I try to join it, and I get the same error when I go to the Zoho Cliq interface > Search for a channel. Is this because I don't have a license linked to this email address?

                                  • It's time to say goodbye to Zoho Recruit for me.

                                    Hello, I have been a Zoho Recruit user since 2013. The tool has evolved, with a better UI, new features and so on. The pricing is still a great asset too. BUT, that being said, important features are not coming fast enough. I tried to share my point of

                                  • Searching for content within courses

                                    Hello, I have been testing out Zoho One for my company have been exploring Learn. I've noticed that you cannot search for content within a course. You can only locate the title of the course. Example: Course: How to Make Your Bed Chapter: Pillows Lesson:

                                  • Remove "Additional Information" options from user-created tickets

                                    I'd like to configure customers to be able to create tickets themselves, with and without logging in. However, I don't want them to set things like the priority or due date. Is there a way to remove these options from the help center when customers create

                                  • Issue Loading Dynamic Table Fields in Zoho Writer

                                    I am experiencing an issue while configuring a repeat table in Zoho Writer. When attempting to insert a dynamic table, I receive the following error: "There was a problem loading your dynamic table fields. Please try again in a while." I have already

                                  • FSM Function not executing

                                    Good Afternoon, all I am working on a workflow function in FSM and yesterday it was working fine. Now today when I select "Save & Execute" it does nothing. I even tested it with just a info statement and it is not executing. Any help would be greatly

                                  • Announcing Early Access to "Zoho CRM for Everyone" — A new and exciting update to Zoho CRM

                                    We are delighted to announce an Early Access to Zoho CRM for Everyone— a truly democratic approach to managing a CRM, gift-wrapped in an exciting and intuitive user interface. Here, multiple teams across an organization can coordinate among each other

                                  • API - Inactive user

                                    Hi We have a complex flow set up with an API. Yesterday I needed to inactivate a user who had set up the flow and API- realised after this, then broke the connection so - re-activated the user. The flow now seems not to work when gaining information from

                                  • Based onthe multipick list value want to Show in the pick list field

                                    Based onthe multipick list value want to Show in the Single pick list field Database Region is multipick list if it contain Saudi and UAE then region pick list want to show Saudi and UAE Database Region is multipick list if it contain Saudi then region

                                  • CRM quotes and sub forms.

                                    Recently upgraded to Enterprise CRM - now some added hopes/questions * In a subform in quotes, if I add a "Percent" field, called Overage for instance. I would expect it to allow me to enter a percent like "10%" and carry the percent forward to formulas

                                  • Reports - Billable Hours

                                    Hello, I have been playing around with some of the reports features but haven't yet been able to generate a report outlining Tickets which have been closed, that have billable time entries - defined against customer accounts -  I can run a report showing all tickets closed with billable hours, but this totals everything - however we have multiple accounts (clients) who log tickets (multiple end-users per client so these are all added into their respective account)  I need a report to show the Ticket

                                  • Add Mileage Tab on Expenses

                                    Hello, the 'Add Mileage' tab is not visible. How can I enable it? I checked the settings, and my user has admin privileges. I also enabled mileage in the policy, but the 'Add Mileage' tab is still not visible. What could be the issue?

                                  • Currency transition

                                    We are using Zoho CRM in Curacao, Dutch Caribbean. Our currency is currently the ANG. Curacao will be transition ing from using the ANG (Antillean Guilder) to using the XCG currency (Caribbean Guilder) on March 31st 2025, see: https://www.mcb-bank.com/caribbean-guilder.

                                  • Error sending an email

                                    Hi, I'm trying to send an automated email (receiver is always the same) via Deluge function. It was working perfectly, but yesterday the receiver's mailbox got full and started returning this error: { "data": [ { "code": "NOT_ALLOWED", "details": { "reason":

                                  • [ Free Webinar] Transform your hiring process with Zoho Recruit's AI tools

                                    We are conducting a free webinar (on 26th November, 05:00 AM IST - 06:00 AM IST) designed to help you make the most of Zoho Recruit’s AI capabilities and give you a sneak peek into our future roadmap. Why Attend? In this session, you will: Discover how

                                  • Email signature duplicate

                                    Hi, For a few weeks, opening the email writer would show an error. After clicking ok, the signature would change slighty (font size, I believe). After that it worked fine, so we thought nothing of it. However, now it no longer shows the error puts the

                                  • Getting Started All Zoho Desk APIs require these two mandatory fields in the header.

                                    Hey, according to API Dokumentation, All Zoho Desk APIs require these two mandatory fields in the header. Authorization - Authentication request token orgId -ID of the organization to access. All API endpoints except /organizations mandatorily require

                                  • ZOHO Work Drive Back Up

                                    I am looking for a ZOHO Work Drive backup solution. Something that is cloud based. There's lots of these kinds of options for Google Drive and other providers, but I have not seen anything for WorkDrive. Any suggestions?

                                  • Export PDF File Name

                                    Is it possible to change the default Zoho .pdf naming scheme for inventory items like quotations? Would like to use the the Subject as the default quote name. Is this possible?

                                  • Facing issue in getting data through api calls

                                    I have send data of users and want to get the data oof users but facing issue with one field for that I want help

                                  • Kaizen #126 - Circuits in Zoho CRM - Part 1

                                    Hello everyone! Welcome back to another week of Kaizen! Today, we will discuss an exciting topic—Circuits in Zoho CRM. For starters, we will discuss what Circuits are, how beneficial they are for businesses, different views of a Circuit, and the different

                                  • Google Ads Data is Publicly available in Zoho CRM

                                    We recently discovered that ALL of the following Google Ads fields are visible to all users in our CRM that have access to either Leads or Contacts modules. Not only is this troubling and inconvenient, it should be unacceptable. It also creates a mess

                                  • Campaigns workflow emails going to Spam

                                    Hi Everyone, Does anyone have a solution for workflow emails going to recipients SPAM folders? Our domain is not on any Blacklists, We have our domain authenticated with SPF, DKIM and DMARC all set up and we still have leads who tell us they are not getting

                                  • Best Way to Integrate a Shared Sales Inbox with Zoho CRM

                                    I’m setting up a shared email inbox (e.g., sales@mycompany.com) for our sales team and want to integrate it with Zoho CRM Leads and Deals so that multiple team members can collaborate efficiently. Since Zoho CRM doesn’t support IMAP for shared inboxes,

                                  • Add and Delete Customer Portal user via Deluge

                                    Using Creator to build an app involving a customer portal. I'm trying to integrate the customer portal for the first time and it is raising questions, mainly because it's new territory. Is it possible to add a new user to the customer portal via deluge? For example, if an existing user invites/refers another potential user to try our app, is there code to automate via deluge, setting up an account ready to go for them? The referral would include their email address, and a workflow would set up the

                                  • Unexpected Error in Reports (Pivot Chart, Pivot Table)

                                    Dear Zoho Support Team, I am facing an issue while creating reports (Pivot Chart, Pivot Table, etc.) in Zoho Creator. When I try to access the report, I receive an unexpected error, and an alert message saying "Undefined" appears with the loading UI.

                                  • Access invoice custom modules data from API

                                    Hi, I am using $url = "https://www.zohoapis.eu/invoice/v3/invoices"; $opts = ["http" => [method" => "GET",header" => [ "Authorization: Zoho-oauthtoken $accessToken", "X-com-zoho-invoice-organizationid: $orgId" ] ] ]; From my app to retrieve the invoices,

                                  • Using IMAP configuration for shared email inboxes

                                    Our customer service team utilizes shared email boxes to allow multiple people to view and handle incoming customer requests. For example, the customer sends an email to info@xxxx.com and multiple people can view it and handle the request. How can I configure

                                  • Zoho CRM and Google Sync - delete Contacts?

                                    If I delete a contact in Zoho CRM, will it also be deleted in Google contacts?

                                  • For Each (Desk Ticket) Loop

                                    What I need is some sort of "for each" loop functionality in Flow, this doesn't seem to be a thing, but I'm wondering if someone found some sort of workaround? Here's the whole situation: I have a Flow, which is supposed to be triggered by a custom field

                                  • Turn off/Disable Lead Approval

                                    Is there a way to disable the need to approve leads? I thought there was but I can't find any reference to it in help, etc. We don't need an approval process for incoming leads at the moment. Thanks.

                                  • Change colour on task lists?

                                    I have many task lists on my project boards, since they are all the same colour they blend in with each other. Is there a way to change the colour of these task lists in the list view?

                                  • Zoho Flow Doesn't Detect Desk Ticket Custom Field Change

                                    I have a Flow that is configured to be triggered when a custom field on a ticket changes. I also have a Schedule in Desk that runs a script that changes the custom field. When I change the custom field manually in the Desk interface, the Flow runs as

                                  • invokeURL to change custom field

                                    I have a deluge script that currently runs as a Schedule. It works exactly as intended, however I've recently been informed by Zoho that there's some mechanism in place to block changes made by a script when it runs on a schedule from being detected by

                                  • Next Page