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




        • Recent Topics

        • Automation #6 - Prevent Re-opening of Closed Tickets

          This is a monthly series where we pick some common use cases that have been either discussed or most asked about in our community and explain how they can be achieved using one of the automation capabilities in Zoho Desk. Typically when a customer submits

        • ASAP Chrome Extension not loading

          We have ASAP enabled in Zoho Desk. I installed the ASAP Chrome Extension (Windows 10), but when I click the extension button while on our site, it never fully loads. I just get what's shown below.

        • Feature Request - Insert URL Links in Folders

          I would love to see the ability to create simple URL links with titles in WorkDrive. or perhaps a WorkDrive extension to allow it. Example use case: A team is working on a project and there is project folder in WordDrive. The team uses LucidChart to create a drawing/s for the project. The team member could create a link to the LucidChart drawing/s and allow WordDrive to truly be a repository for ALL the project documents, even those outside of WorkDrive. A folder is dedicated to a CRM account. A

        • ZOHO DESK ヘルプセンターの言語選択メニューの表示方法

          ZOHO DESK のヘルプセンターを構築し、多言語化設定をしました。 顧客のヘルプセンター画面右上に言語選択メニューが表示されないため、弊社の契約先会社に問い合わせましたが、「通常は多言語化をオンにすると表示するためCSS を触り過ぎではないか」 という指摘のみでした。 試行中ですが表示できません。 何か要因となる情報をお持ちの方がいましたらご教授いただけますと幸いです。 ↓の赤枠を表示したいのですが、表示できません。

        • How to reply to thread via API

          We have built a webapp for our customers that uses the Zoho Desk API to enable each customer to view their full list of tickets, view individual tickets and raise new tickets. The Zoho Desk API doesn't have the ability to reply to a ticket/thread. Replies

        • Email Builder Editor is not functioning or loading correctly

          Email editor function is not working or loading correctly in any template, new or old. Cleared my cache, restarted browser, problem unchanged.

        • Create Tasklist with Tasklist Template using API v3

          In the old API, we could mention the parameter 'task_template_id' when creating a tasklist via API to apply a tasklist template: https://www.zoho.com/projects/help/rest-api/tasklists-api.html#create-tasklist In API v3 there does not seem to be a way to

        • Issue in downloading the sent logs

          Hi Team, I'm unable to export the sent file for any email campaign. When selecting all fields, the system indicates that the document will be sent via email, but I haven't received it. At times, it shows a download option, but the file doesn’t get downloaded.

        • Integrate Google Chat with Zoho CRM for seamless collaboration

          Hello everyone, Sales is a team sport and sales reps have to be in constant communication with people inside and outside their organization. While email remains the most effective channel for important conversations, sales reps often collaborate via chat.

        • customers enter orders?

          Anyway we can let a customer into CRM and enter their own orders , no access to anything else except history reports, no access to any other contacts. Greg Aanes 2109 Queen Street Bellingha WA USA

        • Zoho Learn - URL Parameters for Externally Shared Articles?

          Hey Folks, Are there any parameters one can append to URLs for externally-shared articles? Specifically, can I add a parameter that hides the Manual name (use case being I want to embed the article in another webpage)? Also, can one password-protect an

        • Why Sharing Rules do Not support relative date comparison???

          I am creating a Sharing Rule and simply want to share where "Last Day of Coverage" (Date field) is Greater than TODAY (Starting Tomorrow). However, sharing rules don't have the option to compare a date field to a relative date (like today), only to Static

        • Post message to a channel using a simple one-line command!

          Hi Everybody! This post is all about posting a message in a Channel using cURL, Wget and PowerShell. cURL is a light-weight, command interface used to transfer data to a server. The steps are pretty easy!  The three most important points here are  Generating an Auth token Get your Channel Unique Name Form your message as a JSON structure Generating an Auth token To use the 'Messaging API' you'll need Cliq's authentication token from Zoho Accounts. Generate an auth token by hitting the below-given

        • Activity or History Log User Login

          Hi Everyone, I have Zoho Customer Portal, which has pages and reports. Is it possible to create 1 field such as true/false to find out users who have opened the customer portal? Like a kind of user activity log. Thank you so much.

        • How to associate a document sent in Zoho Sign with an deal in the CRM?

          Hi, often documents are loaded in Zoho sign and sent for signature. These sometimes are linked to a deal in the Zoho CRM and would be nice to see the status of the document within the CRM. I am aware of the integration, but that assumes that the document

        • Invalid Emails in CRM

          Is there a way to get a report or create a view that shows all email addresses that are invalid for any reason? I keep coming across them and want to ensure that they are flagged with users to update. This is on a custom module.

        • Add Custom Reports To Dashboard or Home Tab

          Hi there, I think it would be great to be able to add our custom reports to the Home Tab or Dashboards. Thanks! Chad

        • Associating an Email from CRM Email Parser to Contact Record via Function

          Is it possible to create a custom function that will associate email records from zCRM's Email Parser functionality to a contact record where specific fields match? Our use-case is that we have service providers using third-party event booking systems

        • Update Client Record based on creation of custom module record

          Hi! Hoping for someone's help with this one. I have a custom module called 'Agreement History. Whenever a deal is won, it creates a new record in this module with associated 'Products' and 'Clients' to track rental history and contracts. What I'm trying

        • Inputting VAT Pre-Registration expenses for first VAT Return

          Hi Zoho, I've just registered for VAT and am setting up Zoho to handle calculations and VAT return submissions. I'm struggling to figure out how to input the last 4 years worth of expenses into Zoho so that they're calculated in the VAT module. When I

        • How to Bring to front the picture?

          I have 2 pictures that have to layers but i can't find bring to front button, Thank

        • setting owner of note when adding via deluge

          My organization has requested the ability to mass update the notes related list in the deals module. Since this can't be done with the mass update feature, I created an update "notes single" line field and created a workflow rule that triggers a function

        • Creating email schedules with custom filters for Pivot/Summary Reports in Zoho Analytics

          Hi Zoho, I have a Weekly Inventory Report that I'd like to send out to various vendors. Is it possible to create an email schedule for each vendor with customized filtering at the scheduling level? Currently, we generate two pre-filtered reports (copies

        • Can Client generate Sales Order by himself?

          My business primarily operates in the B2B sector, and I've observed that my sales team and I spend an excessive amount of time obtaining sales orders from our customers. This is particularly relevant in a product-based business with multiple SKUs. I am

        • New Asap Widget How to update my code

          I know you're still working on updating the documentation for calling the Asap Widget, the existing documentation is no longer valid. In the old 1.0 version I was able to do many things programmatically in javascript. I could open an article directly

        • Python - code studio

          Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

        • No Responses in PageSense Polls

          Hello everyone, I have launched a poll on two websites yesterday and I think that responses are not being recorded correctly at the moment. I can see the poll on the page and have tried to submit test answers which are not showing on the PageSense report.

        • Automating CRM backup storage?

          Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,

        • Count the NUMBER of Contacts for an Account automatically

          Hello. Is there any way Zoho can count the number of CONTACTS for a particular ACCOUNT and have a field in the ACCOUNT module update itself automatically? Currently we use Zoho to administer our language school and the Contacts represent students and Accounts represent Grupos (Classes). It would be very useful for us to have a feature like this enabled, and I can see other similar applications requiring something like this. The solution would be even better if the Contacts met a specified criteria,

        • Join Zoho Meeting only via Web browser and not with Zoho Meeting App

          Dear Zoho team, according to the documentation [1], Zoho Meeting only offers web view for Chrome and Firefox on a desktop. For other browsers and devices, participants can only join a Zoho Meaning with the Zoho Meeting App installed. This is a big hurdle

        • 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

        • Email alias per task list so these tasks don't get listed under a 'General' task list that we didn't create nor use

          Using an email alias to add tasks is very good for forwarding emails directly into Zoho Projects however everything gets listed under a 'General' task list which is counter-intuitive. It would be good to have an email alias for each task list so we can

        • Pin multiple columns and adjust column widths in CRM subforms

          Hello all, Subforms act as secondary forms or tables in which you can associate multiple line items to a primary record and thereby ensure more structured and comprehensive data organization. We've made some recent enhancements to subforms. Here's what's

        • Creating Form PDF and Adding to CRM Account

          I have client onboarding forms that I'll be creating in Zoho Forms and these forms will gather information from clients that will help with upcoming projects. I want to know how I can have a pdf created from a from submission and automatically attach

        • Related Lists filter

          I have Contacts showing in our Accounts module. I customized the Contacts module with an Employment Status field, with the following picklist options: "Primary Contact", "Secondary Contact", "Active Staff(not a main contact)", and "No longer employed".

        • Improve Zia Data Foundation

          Hi, is it possible to manually improve Zia's CRM data foundation for companies? Zia tends to give data based on foreign companies but we only operate in the German market. Even if I specifically but the German company name and the URL to the german imprint

        • 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

        • Zoho Sheet view has two way sync or one way? Sheet view to CRM and what about CRM to Sheet view?

          I created a zoho sheet view. I can make changes and these changes are saved back to CRM. I have copied the link of this zoho sheet view for future easy access. Now I go to CRM, and update a single record in CRM. Now if I use the zoho sheet view link that

        • Sending Multiple Assessments to Candidate?

          Good day, Is it possible to send multiple assessments to Candidates automatically after they have been created? I need to send 4 seperate assessments automatically to new Candidates and am unsure of how to go about it. Zoho only has the option to assign

        • Zoho CRM API, Python SDK v7 Quoted_Items

          Hello. How do I use this SDK to retrieve the Quoted_Items from a Quote and downstream the items in a Sales Order I can see references to a constant INVENTORY_MODULES_ITEMS = ["invoiced_items", "quoted_items", "purchase_items", "ordered_items"] But I cannot

        • Next Page