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



      • Sticky Posts

      • Kaizen #197: Frequently Asked Questions on GraphQL APIs

        🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

      • Kaizen #198: Using Client Script for Custom Validation in Blueprint

        Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

      • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

        Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

      • Kaizen #193: Creating different fields in Zoho CRM through API

        🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

      • Client Script | Update - Introducing Commands in Client Script!

        Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

        • Recent Topics

        • Where can I find rejected inbound mails and their reason for rejection

          Hi, I was recently made aware by a mailing list which I am subscribed to (ffmpeg-devel@ffmpeg.org) that my Zoho mail Mail account is rejecting some emails. If I look under Admin Panel > Security & Compliance > Quarantine > Incoming, the list there is

        • Sync more than one Workdrive

          Hello Please I'm facing some difficulties since some days. In my company we have many zoho accounts in different organisations. And I have to find a way to sync all these Workdrives. I spend many hours to search it on zoho Workdrive but no solution. Could someone help me ? Any idea how I can achieve it ? Thanks in advance. Regards

        • Zoho writer unable to merge documents to PDF with basic fonts in Hebrew or fonts from my computer

          I created several forms that will be merged into PDF files through Zoho Writer and I am unable to receive the PDF in the basic fonts of the Hebrew language or in the fonts I have on my computer. The writer exports to PDF an exchange font that looks very

        • Base Currency Adjustment Reversal

          Two questions surrounding the base currency adjustments (BCA). I recently ported over from QB so I need to enter the base currency adjustments. In QB, it will calculate the BCA for you at the end of the year and then reverse it at the top of the following year. Makes sense. Does Zohobooks not do this as well? I created a BCA for Dec 31, 2016 but no reversing entry was made Jan 1, 2017. Am I supposed to manually do a reversal? I'm not even allowed to post journals directly to the 'exchange gain loss'

        • Please implement UAE Central Bank FX rates

          Hello, as I understand from your knowledge base, any UAE business account created from September 15, 2018 does not have foreign exchange rates fetched automatically. This is a serious inconvenience and I am not sure why ZOHO has not looked into the ways

        • Search Records returning different values than actually present

          Hey! I have this following line in my deluge script: accountSearch = zoho.crm.searchRecords("Accounts","(RS_Enroll_ID:equals:" + rsid + ")",1,200,{"cvid":864868001088693817}); info "Account search size: " + accountSearch.size(); listOfAccounts = zoho.crm.searchRecords("Accounts","(RS_Enroll_ID:equals:"

        • Super Admin Access to All Courses and Spaces in Zoho Learn

          Dear Zoho Learn Team, We hope this message finds you well. We are using Zoho Learn extensively for internal and agent training. While managing our courses and spaces, we encountered a significant limitation regarding admin access and course management.

        • Print checks for owner's draw

          Hi.  Can I use Zoho check printing for draws to Owner's Equity?  This may be a specific case of the missing Pay expenses via Check feature.  If it's not available, are there plans to add this feature?

        • [New Release 2024] Create and embed custom capabilities across CRM with Kiosk Studio, our latest no-code tool

          [Update | New series] We've started publishing a series of posts on Kiosk Studio. It's called Kiosk Studio Sessions and you can check out the first one here! [Update | 15 Oct} Session #2 is live! This one will look at how to create a kiosk for your call

        • Revenue Management: #10 Common Mistakes while Recognizing Revenue

          We are at the end of the series on Revenue Management, covering how different businesses recognise revenue. Even with clear standards like ASC 606 and IFRS 15 in practice, businesses often struggle with the nuances of revenue recognition. Especially growing

        • Windows Desktop App - request to add minimization/startup options

          Support Team, Can you submit the following request to your development team? Here is what would be optimal in my opinion from UX perspective: 1) In the "Application Menu", add a menu item to Exit the app, as well as an alt-key shortcut for these menus

        • integarting attachments from crm to creator

          when i tried to integrate pdf attachments from crm to creator via deluge i am getting this error {"code":2945,"description":"UPLOAD_RULE_NOT_CONFIGURED"} the code i used is attachments = zoho.crm.getRelatedRecords("Attachments","Sales_Orders",203489100020279XXX8);

        • Search Option

          🚫 Current Limitation: As of now (September 2025), Zoho FSM lacks a global search functionality, which makes it difficult to quickly: Find specific Work Orders by number or keyword Search for customer records or contact info Locate assets, jobs, or service

        • Mobile Chat Window - Full Screen

          Hello, The mobile chat window takes up the full screen, which is highly confusing for most customers! Using a desktop machine, I see the same happens when reducing the browser width to 800px or below. This suggests that it responsive web design, causing the switch to full screen. Can we fix this very annoying behaviour ourselves using a custom css file? If so, can you please let me know how? Thanks

        • Is it possible to customize ZC Themes?

          I understand you can choose a layout and customize Brand Color, App Header, Menu, and Sub-Menu components, but can you override some of the default theme settings with CSS or a config file? For example, - Table highlight color - Listview auto filter highlight

        • Is it possible to create Custom function-based Lookup field in Zoho CRM

          Is it possible to create a custom function-based lookup field in Zoho CRM? If so, how? Use case: Need to fetch users from Zoho Projects into a dropdown field in Zoho CRM.

        • @mention in comments no notification

          Hi, hope someone can help. When we @mention someone in the comments in Zoho Creator, how is that user notifed as we don't get anything on email or in the app notifications. 

        • Zoho unified inbox

          The new changes have definitely improved things for switching between accounts.  But zoho still desperately needs a unified inbox.  It sucks to have to enter filters and folders for each and every inbox.  This seems like such a simple thing, i wonder why Zoho hasn't done it?

        • Add "Running Balance" column to Account Transaction Reports

          Hello, Currently Zoho Account Transaction Reports give you the opening balance, then lists the transactions, then provides the closing balance.  It would be great if you could add a column on the far right that shows the "Running Balance" on the account after each transaction.  There are many times when analyzing or tie-ing out transactions that this would be very helpful.  I currently have to frequently run a tape on my adding machine to get balance totals after a specific transaction on the list.

        • Unified customer portal login

          As I'm a Zoho One subscriber I can provide my customers with portal access to many of the Zoho apps. However, the customer must have a separate login for each app, which may be difficult for them to manage and frustrating as all they understand is that

        • WhatsApp Channels in Zoho Campaigns

          Now that Meta has opened WhatsApp Channels globally, will you add it to Zoho Campaigns? It's another top channel for marketing communications as email and SMS. Thanks.

        • error : Object code : 6500

          b3 = map(); b3.put("name", "Test Project Name"); updateprojects2 = invokeurl [ url :"https://projectsapi.zoho.eu/restapi/portal/era0130/projects/169495000000928007/" type :PUT parameters: b3 connection:"in2" ]; info b3 ; info updateprojects2; ------------

        • How to book GST paid in zoho books

          hi, i am a new user to Zoho books and not able to book GST paid in books, kindly suggest how i can book it in books. thanks, siddharth

        • I got unknown charge from Zoho

          Good day, I need help disputing a charge I don't know from, zoho. I have ZohoMail and ZeptoMail. I purchase credits for ZeptoMail, and for ZohoMail I am not subcribed.

        • Function 56: Automatically enable the option for customers to pay via bank account

          Hello everyone and welcome back to our series! One of the key features of Zoho Books is its integration with multiple payment gateways, allowing you to receive online payments for your invoices. This ensures faster payments, automates payment tracking

        • Attach Files to Your Notecards and share them on the go!

          Hey everyone! We’re excited to share a feature many of you have been asking for — you can now attach files directly to your text notecards and share with ease! 🙌 This update was built with your feedback in mind, especially for those who wanted a simple

        • 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

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

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

        • How to searchByCriteria records that are under approval?

          I need to search for both approved and pending approval records Is that possible with this method? Or I need to a different method? var priceReqID = $Page.record_id; log(priceReqID); var records = ZDK.Apps.CRM.Price_List_Item.searchByCriteria("Price_Request:equals:"

        • How to add Simple Analytics to Zoho Pages?

          I have a website with Zoho Pages, how do I add Simple Analytics on it? They seem to have code they need to be embedded https://docs.simpleanalytics.com/script

        • Cant seem to delete an email account

          Hello, I have researching for 4 days how to delete an email account and I am absolutely without a clue. The email account I am trying to delete is support<AT>fyshoes<dot>com. It's the first email account I made and it (is???) was associated with the super user (me). I have since changed it to adming<AT>fychoes<dot>com and I see the support email in my list but I just cant seem to get rid of it. Ultimately I want to associate that email account with another user that I want to add. This is really

        • Import data into Multi-Select lookup field from CSV/Excel

          How to import data into a multi-select lookup field from the CSV/Excel Sheet? Let's say I have an Accounts multi-select lookup field in the Deals module and I want to import the Deals with Accounts field. Steps:- 1. Create/edit a multi-select lookup field

        • Script that deletes a record?

          We're using WP Plugin "Integration for WooCommerce and Zoho Pro", and have created a couple of Feeds to send data to Zoho. We are trying to create Contact records, but only based upon condition. Tried to make it with small Deluge function and Workflow,

        • A formula that capitalises the first letter of each word

          Hi all, is there a zoho formula that can capitalise the first letter of each word in a string? INITCAP only capitalises the first letter of the first word.

        • Quotes in Commerce?

          In Zoho Ecommerce, I need to be able to generate quotes, negotiate with customers, and then generate invoices. Currently, I plan to integrate Zoho CRM to generate quotes. After negotiation and confirmation, I will push the details to Zoho Ecommerce to

        • Zoho Commerce - Mobile Application

          Does Zoho Commerce have a mobile application for customers to place an order?

        • Register user through Phone Number by Generating OTP

          In zoho commerce , I am developing website on online food store Inilialy the user get verification code to their email for registering there account for login. But I need to login using phone number by generating OTP automatically rather than verification

        • Unable to change sales_order status form "not_invoiced" to "invoiced"

          I am automating process of creating of invoice from sales_orders by consolidated sales_orders of each customer and creating a single invoice per customer every month. I am doing this in workflow schedule custom function where i create invoice by getting

        • Custom Buttons for Mass Actions

          Hello everyone, We’ve just made Custom Buttons in Zoho Recruit even more powerful! You can now create Bulk Action Buttons that let you perform actions on multiple records at once, directly from the List View. What’s new? Until now, custom buttons were

        • Zoho Vault Passwords

          Is there a way to consume Zoho Vault Manager passwords using the API? Thanks in advance.

        • Next Page