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

    • Issue with "invoice_url" Field Showing Draft or Void Status

      We are using the Books API feature, and we are experiencing an issue with some invoices. When we use the "invoice_url" field to access an invoice link, we receive the error message: "Invoice that you are trying to access is in draft or void status." This

    • String field that contains html code to email

      Hello everyone, We've created a zoho flow that takes some input from the user (some keywords from a multi pick list) and sends them to a zoho flow which uses an ai prompt to create an email based on these keywords in an html form (e.g. use of <p>, <b>,

    • 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

    • 【Zoho CRM】数式項目に関するアップデート

      ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 今回は「Zoho CRM アップデート情報」の中から、数式項目のアップデート（3つの機能強化）をご紹介します。 【目次】 １、時間ベースの数式を自動更新とリアルタイムの値を表示 ２、条件に基づいて数式の実行停止 ３、既存の数式を使用して新しい数式を作成 １. 時間ベースの数式を自動更新とリアルタイムの値を表示 数式項目のプロパティに関数「Now()」を含む数式項目の値をリアルタイムで自動更新するというチェックボックスを導入しました。 Before：データが手動で編集されるか、自動化によって更新されたときにのみ、数式項目は最新の結果を計算し、値を表示していた。

    • Issue with syncing zoho campaigns with zoho crm

      Hi there, I want to sync both zoho campaigns with zoho crm however i have encountered some issues with this. when clicking manage in zoho i receive this message even though im using the same account and its an admin account. however when i go to zoho

    • Changing Color Theme of Guided Conversations

      Hello, We have recently added Guided Conversations to one of our websites, but I am wondering if there is a way to customize the color scheme so it matches the appearance of the website? Thank you in advance!

    • The ability to show fields from subforms when viewing from related list

      Hi there, Currently im only able to display default columns , however when im unable to add the columns/fields from the subform Ive created. below is a field called quantity from the subform. Im not able to search up this field from the manage column

    • HTML Email in Zoho Books

      Is it possible to create custom html email template in zoho books. 

    • Recording overpayment?

      So a customer just overpaid me and how do I record this? I can't enter an amount that is higher than the invoice amount. Eg. Invoice is $195 and he sent $200. He's a reccuring customer so is there a way to record so that he has a $5 advance for future invoice?

    • How can I add Material cost to a project?

      Hello, We use Zoho project to manage scheduled work. This consists in labour tasks and matrials cost. How can I add the material budget, then teh cost to the project? Thanks Barbara

    • Bigin-Zoho Projects Integration

      We're pleased to announce the Bigin-Zoho Projects integration, which enables you to manage client relationships and project tasks simultaneously in one system. With this integration, once you close a deal in Bigin, you can create a project in Zoho Projects

    • Managing independent contractors

      We use Independent contractors as our field techs. I'm looking for a solution to be able to manage there timesheets, payments, and etc

    • License Issue

      Hello Campaigns Team, we have 17 ZOHO One licenses but in campaigns I get the message that we have a free plan. How can we use ZOHO campaigns? As far as I understood campaigns is a part of ZOHO One. THX Niels

    • Dynamic Date Filtering for KPI Widgets – Need Help with Query Table

      Hello, I'm seeking help with setting up dynamic date filtering for my KPI widgets in Zoho Analytics. Below is an overview of my setup and the issues I'm facing: Why: I need my KPI widgets to update dynamically based on a date range selected via a dashboard

    • Count Function in Zoho Table

      Hi Zoho Team, Hope you're doing well. We would like to request the addition of a Count function in Zoho Table, similar to what exists in Excel, Google Sheets, and Airtable. Currently, there is no built-in way to count the occurrences of unique values

    • Leads, Prospects, Contacts, Clients and Me

      I'm trying to adapt my process to Zoho and am getting confused. Here's how I did it before. Maybe it's just terminology...? Leads - anyone from any source that I might want as a client. Leads include people that I am sending emails or tapping in social

    • Contacts, Leads, Prospects, Opportunities, Deals, Oh my!

      I've implemented three CRM's in previous companies, and led the effort for two of those.  I'm pretty familiar with sales pipeline management. For my current company, I chose Zoho One because of the broad range it includes for other business processes, and am generally quite happy.  So now it's time to dig into Zoho CRM And I find myself a bit befuddled. In other implementations, a "Contact" was just that- a name and some contact information.  Could be anybody whether interested in doing business

    • Visual Sync Status Indicator

      I think I've see in documentation that WorkDrive had the industry standard of indicating a sync status for individual files and folders. I'm just starting with WD and synced my first test folder, but there was no way to tell what's happening by just looking

    • Is there a way to make the new tab button open a new cloud document?

      I'm coming from Google Docs. Plus, is there any way to have a set a default font? I'm using the desktop app and I prefer the options I can get through the cloud documents. I want the convenience of just opening a new cloud document rather than doc that's

    • Tip 26: How to hide the "Submit" button from a form

      Hi everyone, Hope you're staying safe and working from home. We are, too. By now, we at Zoho are all very much accustomed to the new normal—working remotely. Today, we're back with yet another simple but interesting tip--how to hide the Submit button from your forms. In certain scenarios, you may want to hide the submit button from a form until all the fields are filled in.  Use case In this tip, we'll show you how to hide the Submit button while the user is entering data into the form, and then

    • Trying to export a report to Excel via a deluge script

      I have this code from other posts but it gives me an error of improper statement, due to missing ; at end of line or incomplete expression. Tried lots of variations to no avail. openUrl(https://creatorapp.zoho.com/<username>/<app name>/XLSX/#Report:<reportname>,"same

    • Bigin_Email Notification not being sent when a new lead is created

      I have a workflow in BIGIN set to send an email notification when a new lead is created via a webform (integrated with ZohoForm) The trigger is whenever a contact is "Create or Edit". Conditioning was applied for contacts which source is "Website" If

    • ZOHO CRM API Python SDK Convert Quote to Sales Order

      I can see footprints that this may be possible through Inventory Conversion. But I am unable to locate any specific details or samples on how to do this. I am using the most current Python SDK. Any support or even sample code would be much appreciated

    • Displaying Notes/Description Columns in "All Expense" showing Tabs

      It's surprising to see there is no option to view description columns in tab showing all expenses. There are provisions for Reference# and Status, but why not the description/notes. Please Add. Thank You.

    • Zoho Books - uploading company logo squashed

      I am trying to upload my company logo with the following dimensions - 240 x 240 pixels and a file size of 106Kb. When I look at the logo in my invoices, it is squashed and not the right size. Any idea what is going on? I've tried uploading jpeg and png

    • Petty cash discrepancy

      How do I record a petty cash discrepancy? We had money go missing and need to document that in the books, but I'm not sure how to put that in. It's not an expense, just a loss of cash.

    • Missing Custom Fields in ZOHO Reports

      Hi, I am currently attempting to generate some reports using the programme. However, I have met some obstacles in the form of missing custom fields from the field selection panel when creating charts etc. Please advise. There are plenty of custom fields which is rather important to creating these reports. Thank you.

    • Zoho Workdrive file versions

      Hello. I have Workdrive setup to sync files offline to an external hard drive. The off line sync folder currently shows at 1.42 TB. I have a 5 TB storage limit in Workdrive. The cloud version of Workdrive says that I have used all 5 TB! I have 27, 285

    • Integration with Zoho CRM?

      Will it be possible to integrate WorkDrive with CRM similar do Zoho Docs?

    • How to control the # of version of files to keep?

      Currently most of the WorkDrive Storage comprise of the many versions of files saved. How do I save some space and reduce the number of version of date or files saved in WorkDrive? Thanks

    • Should I Use Zoho Mail Calendar, or Zoho CRM Calendar, or Zoho Calendar?

      After a couple of dozens Zoho solopreneur products that I transitioned to after becoming a Zoho One enthusiast 5 years ago, I am finally preparing to conquer the remaining two bastions: Mail and WorkDrive (using Google Workspace at the moment). A NYC

    • Add comments to a form

      Hello, I'm trying to add comments to a form using a subform with one field named comment, but I don't want prior comments to be editable or deleteable by anyone (except the admin).  Is there a way to only display prior comments (with a datetime, user and comment field preferably) but still be able to add new ones when editing the main form?  I'm not tied to subforms if there is an easier was to do this?

    • Zoho Books | Product updates | March 2025

      Hello users, We have rolled out new updates in Zoho Books to enhance your accounting experience. These include the ability to create workflow rules for manual journals and Multi-Factor Authentication (MFA) for customer and vendor portals. Explore these

    • Work Drive Tray Icon Missing

      How can I get the tray icon back? The app froze, had to restart PC and then it's been gone since...  I've re-installed the windows program and restarted my machine twice now.

    • cant receive emails

      I have checked the Dns and everything seems to be fine pls check the print screens attached below help me cause i need to solve this fast

    • Retainer invoice in Zoho Finance modlue

      Hello, Is there a way of creating retainer invoices in the Zoho Finance module? If not can I request this is considered for future updates please.

    • iOS Widget Not Working

      It appears that the iOS widget is not working, displaying a blank white screen instead of a selected note. I’m using app version 6.5.12 and iOS 18.3.1.

    • Two Problems With Data Imported to Notes

      Occasionally I want to create a note by copying and pasting a few paragraphs from an article on line. When I create a new note and paste in the section the newly created note winds up with each paragraph in white text on a dark background rather than

    • Unable to send message;Reason:550 5.4.6 Unusual sending activity detected. Please try after sometime

      Hello i'm unable to send any email because i keep getting this error Unable to send message;Reason:550 5.4.6 Unusual sending activity detected. Please try after sometime i have literally sent less than 10 emails today i'm not sure why i'm getting this

    • Workdrive on Android - Gallery Photo Backups

      Hello, Is there any way of backing up the photos on my android phone directly to a specific folder on Workdrive? Assuming i have the workdrive app installed on the phone in question. Emma

    • Next Page