Kaizen #56 - Upsert Records #API
Hello everyone!
Welcome back to another week of Kaizen.
In this post, we will discuss the Upsert Records API.
1. The purpose of upsert records API
Using the upsert records API, you can either insert or update records in a module. When you fire an upsert call, the system checks for duplicate records based on the duplicate check field's values. If the record is already present, it gets updated. If not, the record is inserted.
2. The duplicate check fields
There are two types of duplicate check fields:
2a. The system-defined duplicate check fields
These are the default unique fields. When you upsert a record, the system checks for duplicate entries in these fields.
Module-wise system-defined duplicate check fields
Module | System-defined duplicate check field |
Leads | Email |
Accounts | Account_Name |
Contacts | Email |
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 |
2b. The user-defined unique fields
The fields for which "Do not allow duplicate values" is enabled. Click here to know more. Note that you can only set fields with the following field-types as unique— Single Line, Email, Phone, Number, Long Integer, and URL.
3. The duplicate_check_field array
You can set the order in which the system checks for duplicate records by specifying the duplicate_check_field array in the input. You can add only the system-defined duplicate check fields and user-defined unique fields to the duplicate_check_field array. For instance, in the example below, "Email" is the system-defined duplicate check field, and "Phone" and "Fax" are the user-defined unique fields for the Leads module.
"duplicate_check_fields": [ "Email", "Phone", "Fax" ] |
If you do not specify the duplicate_check_field array, the system checks for duplicate records in the following order:
- System-defined duplicate check fields
- User-defined unique fields
4. How does duplicate check work?
Consider a case where the user has configured two unique fields unique1 and unique2 for a module (user-defined unique fields), and Email is a system-defined unique field.
The following table explains how the duplicate check happens for different user inputs to the duplicate_check_fields array.
User Input to the "duplicate_check_fields" Array | Duplicate Check Order |
unique1 | unique1, unique2 |
unique2 | unique2, unique1 |
unique1, unique2 | unique1, unique2 |
Email | Email, unique1, unique2 |
No input | System-defined duplicate check field for that module followed by unique fields. That is, Email, unique1, unique2 |
If you do not specify the system-defined duplicate check fields in the array, the system will ignore them and check only for user-defined unique fields.
5. Upserting a record via API
OAuth Scope
The scope to access the Deals module via API is:
ZohoCRM.modules.{module_api_name}.{operation_type}
ZohoCRM.modules.{module_api_name}.{operation_type}
The operation type can be ALL, WRITE, or CREATE.
Click here to know more about the scopes.
Request URL: {{api-domain}}/crm/v2/Leads/upsert
Request Method: POST
Sample Input
{ "data": [ { "Last_Name": "Frey (Sample)", "Email": "frey@sample.com", "Company": "abc", "Lead_Status": "Contacted" }, { "Last_Name": "New Lead", "First_Name": "CRM Lead", "Email": "newlead@zoho.com", "Lead_Status": "Attempted to Contact", "Mobile": "7685635434" } ], "duplicate_check_fields": [ "Email", "Mobile" ] } |
Sample Response
Note:
You can insert or update a maximum of 100 records per API call.
We hope you found this post useful.
Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Sneha Sridharan
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 FAQsKaizen #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
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Disappearing Mouse cursor in Zoho Mail / Windows 11 (Chrome + Edge)
I'm seeing an issue when writing mails with the light theme with the mouse cursor being white and the document area also being white - making it nearly impossible to see the mouse cursor. I see the problem on Windows 11 under Chrome and Edge. (Yet toZoho Assist not rendering NinjaTrader chart properly
Hi everyone. Just installed and testing Zoho Assist. I want to display my laptop' screen (Windows 11) on a monitor connected to my Mac mini. The laptop is running a stock trading program called NinjaTrader. Basically, when running, this program displaysDropshipping Address - Does Not Show on Invoice Correctly
When a dropshipping address is used for a customer, the correct ship-to address does not seem to show on the Invoice. It shows correctly on the Sales Order, Shipment Order, and Package, just not the Invoice. This is a problem, because the company beingBest way to schedule bill payments to vendors
I've integrated Forte so that I can convert POs to bills and make payments to my vendors all through Books. Is there a way to schedule the bill payments as some of my vendors are net 30, net 60 and even net 90 days. If I can't get this to work, I'll haveLink(s) between Notes
Hello Everyone, It would be great if links could be created between notes. Let's say we have 5 Notes A, B, C , D, E. I would like to be able to link Note A to Note B but not in other way, so no link appears in Note B linking to Note A. An so on, linkingOption to Hide Project Overview for Client Profiles
In Zoho Projects, the Project Overview section is currently visible to client profiles by default. While user profiles already have the option to restrict or hide access to the project overview, the same flexibility isn’t available for client profiles.Zoho Books | Product updates | August 2025
Hello users, We’ve rolled out new features and enhancements in Zoho Books. From the right sidebar where you can manage all your widgets, to integrating Zoho Payments feeds in Zoho Books, explore the updates designed to enhance your bookkeeping experience.Feature Request: Assign Documents to Already Entered Bills, Expenses, Invoices, etc.
Hi Zoho Team, We are regular users of the Documents module in Zoho Books and appreciate its ability to keep financial records well-organized. However, we’ve noticed a limitation: There is no way to attach a document from the "Documents > Files" sectionI don't see any WITHDRAWL transaction at all
Hi I manually imported my bank statement to Zoho books today and I am a complete newbie. I have been reading the knowledgebase but unable to fix this. I only see "Uncategorized 91 DEPOSIT transactions". I don't see any WITHDRAWL transaction at all. Also,Shared inbox unable to see replies
Hi we are a small company me and someone else, we have a shared inbox for our sale@ and contact@ however we have this issue where by if i reply to an email or the other person reply to the email, it does not show it to them and therefore we end up replyingKaizen #136 - Zoho CRM Widgets using ReactJS
Hey there! Welcome back to yet another insightful post in our Kaizen series! In this post, let's explore how to use ReactJS for Zoho CRM widgets. We will utilize the sample widget from one of our previous posts - Geocoding Leads' Addresses in ZOHO CRM404 error at checkout
Our customers are getting a 404 error at checkout. Anyone else with the same problem?FONT Sizing in Notebook
Hi Kishore - What is the status of adding font sizing to the application? I have several things that I have pasted directly into Notebook and the fonts are HUGE! I would like the ability to highlight them and reduce the font to a legible size. NothingCan managers Upload documents to their direct rapports?
Admin employees have the ability to upload documents to employees' files; however, managers do not have add/manage button - is it possible for managers to upload their direct reports' documents, such as absence documents or 121 documents. Is there somethingLeave balance display for next year
Is there a way to not have a rollover or not limit the leave balance depending on the date. For example an employee has 10 days leave balance and wants to apply for January leave in December. They cant because the rollover doesnt show the leave balancePlease add an “Auto-Apply Unused Credits” toggle
Hello — please add a simple org-level option to automatically apply unused credits (credit notes, excess payments, retainers) to new invoices and/or bills. An ON/OFF toggle with choices “invoices”, “bills”, or “both” would save lots of manual work forZoho Books not working/loading
Hi! I haven't been able to access/load Zoho Books for the past hours. I get a time out (and it is not due to my internet connection). Could you please check this asap? Thank you!Custom Fields with Data Types for Expense and Payments Received in Zoho Books
Hi all, We are glad to present to you, the option to create Custom Fields for the Expense and Payments received modules in Zoho Books. This also comes with an icing on top of it - Yes, the custom fields can now be created with different data types. Types like Text, Number, Decimal, Amount, Auto Number and Check Box are supported as of now. Rush to the gear icon at the top right corner, select 'More Settings', choose 'Preferences' in the left pane. Click the Expense/Payment preferences where you canZoho Cliq - Incident alert (Server outage - IN DC) | August 28
We've received server down alerts and are currently investigating the issue (IN DC) to find the root cause. Our team is actively working to restore normal operations at the earliest. Status: Under investigation Start time: 09:44:21 AM IST Affected location:Claude + MCP Server + Zoho CRM Integration – AI-Powered Sales Automation
Hello Zoho Community 👋 I’m excited to share a recent integration we’ve worked on at OfficehubTech: ✅ Claude + MCP Server + Zoho CRM This integration connects Zoho CRM with Claude AI through our custom MCP Server, enabling intelligent AI-driven responsesHow can I see content of system generated mails from zBooks?
System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.Limitations on editing a message in Cliq
Hi I've checked the documentations and there's no mention of how many times a message can be edited. When trying with code, I get various numbers such as ~1000 edits or so. Please mention if there's a limit on how many times one can change a message viaNarrative 10: Assignment Rules - Streamlining Ticket Management
Behind the scenes of a successful ticketing system: BTS Series Narrative 10: Assignment Rules - Streamlining Ticket Management In the complex world of customer support, a flood of incoming tickets can hit the help desk in seconds. Businesses must do moreFree webinar! Digitize recruitment and onboarding with Zoho Sign and Zoho Recruit
Hello, Tired of being buried in onboarding paperwork? With the integration between Zoho Sign and Zoho Recruit, a powerful applicant tracking system, you can digitize and streamline the entire recruitment and onboarding process, all from one platform.Custom form - Duplicate Value Present
I am new to Zoho People. I create a new form on Zoho People quite simple. A date (by default the current date) and a radio button with 3 options (Yes, No, Not applicable) I defined the date as ‘No duplicate’ as only one entry by date is allowed. I added:Zoho API connection issues
Hi, Today at around 1930 GMT our application started experiencing intermittent timeouts from the Zoho API. These intermittent timeouts are not enabling our app to work properly. The API connection was working just fine before. HTTPSConnectionPool(host='www.zohoapis.com',Query Regarding our Partnership between AIC-JKLU and Zoho
Dear Zoho Team, I am writing to raise a concern on behalf of AIC-JKLU, one of Zoho’s incubator partners. Recently, our startups have been facing difficulties while trying to get themselves onboarded on Zoho through our dedicated partner link. Unfortunately,Disputed Purchase Invoices
We have recently moved to Zoho Books from Sage. In Sage we were able to post a purchase/vendor invoice but mark it as on dispute. This would usually be a pricing query or if something was damaged. It would show in their ledger, so we could agree theirGetting events in the future
Hi I am trying to get events in the future by calling this API Endpoint https://www.zohoapis.eu/crm/v8/Events?fields=Event_Title,Created_By,Created_Time,Start_DateTime But that gives me all events in the database. How do I make a query that returns allCreated Date/Invalid Fields
Since Saturday we have suddenly had issues with our webhooks and data retrieval from CRM. Specifically how Created Date is handled. It appears there was some sort of change within CRM that broke a lot of our code that has been in place for several years.Zoho Inventory. Preventing Negative Stock in Sales Orders – Best Practices?
Dear Zoho Inventory Community, We’re a small business using Zoho Inventory with a team of sales managers. Unfortunately, some employees occasionally overlook stock levels during order processing, leading to negative inventory issues. Is there a way tointegration zoho form - drive
I integrated my form with Google Drive. The report of user submissions from the Google Form becomes a Google Sheets table. When I used Google Forms for the same task, the summary sheet adapted to the form. For example, if I added a new field to the form,add employees and customiz
I want a Zoho software to track employees record. I logged in a demo so now I tried adding employee, first thing when I click on add employee it takes me to a page where it says add user maximum 10 users, my first doubt why users I don't want employeesRevenue Management: #9 Revenue Recognition in Media & Publishing
Media & Publishing industry has evolved in recent times. It offers subscriptions, bundles digital and print access, runs sponsored content, and sometimes even sells ad spaces. If you run a media or publishing business, you will always get into a situationZoho CRM Community Digest - July 2025 | Part 2:
Hello, Everyone! We’re closing out July with a can’t-miss highlight: Zoholics Europe 2025! Happening from September to October, it’s your chance to level up your CRM skills, covering everything from automation and CPQ to dashboards and advanced workflows.How can I trigger a flow action only once while updating contact?
Hi, we have a trigger to merge&mail file when the field YYY is filled out. For this acion I used "Create or update module entry". But unfortunately we get tens of email on a day with this merged file, because the contact is being regularly updated. TheCopy a Record Template from one Form to another
I have a Creator application with several forms. I developed a record template for one of the reports/forms but want to use most of it for another of the form/report combinations in the application. Is there a way to copy the template (code or otherwise) to another form?Tip of the Week #70 – Create common team signatures for your shared inboxes
Did you know that a small detail, such as an email signature, can make a big difference in how your brand is perceived? One simple yet smart way to enhance your team’s communication is by creating common team signatures for your shared inboxes. InsteadEnhanced data export features: XLSX format, custom character encoding, and selective record export
Greetings all, Here are a few enhancements related to exporting CRM data, including the ability to export data in XLSX file format now. The Export feature under Data Administration now offers new options that expand its flexibility and enable users toTip #42 – How to manage data security with Privacy Settings – 'Insider Insights'
Data privacy is a cornerstone of trust in remote support. Through Privacy Settings in Zoho Assist, you can set up how data is gathered, stored, and handled in your organization. These settings ensure compliance, data protection for sensitive details,Next Page