Update or Upsert Records Using Unique Custom Fields

Update or Upsert Records Using Unique Custom Fields

Hello customers,

We've enhanced the process of updating records via API. You can now:
  • Update records using unique custom fields
  • Upsert records using unique custom fields
Note: Both the features are available in the Zoho Books and Zoho Inventory apps.

Update Records Using Unique Custom Fields

Until now, records were updated using their unique ID. For example, when updating an invoice, the number displayed in the URL after invoices/ (/invoices/xxxx...) is the invoice's unique ID. When a PUT call is made, the record will be updated if the unique ID exists. If it does not exist, an error will be thrown.

You can now update records using unique custom fields if the Prevent Duplicate Values option is enabled for those custom fields. When a PUT call is made, the record will be updated if the unique custom field exists. If it does not exist, an error will be thrown.

For example, when integrating Zoho Books with a third-party application where a record, such as an item, has different unique IDs in both applications, you can create a custom field in Zoho Books to store the third-party application's unique ID. By enabling the Prevent Duplicate Values option for a custom field in the Items module, you can update records in the Items module using either the item's unique ID or the unique custom field.

How do I update records using unique custom field?  

To update a record using a unique custom field:
  • Pass the custom field's API name in the header X-Unique-Identifier-Key.
  • Pass the value of the third-party record's entity ID stored in the unique custom field in the header X-Unique-Identifier-Value.

Upsert Records Using Unique Custom Fields

What is Upsert?

Upsert is the combination of the terms Update and Insert. It refers to an API operation that allows you to either update an existing record or insert a new record if it does not already exist. This operation is particularly useful in scenarios where you want to ensure that a record is present in the database without having to first check if it exists.

How does Upsert work?

This is how Upsert works:
  • If the record exists, the Upsert method will update the existing record.  
  • If the record does not exist, the Upsert method will create a new record.

How do I Upsert records?

To upsert records:
  • Pass the custom field's API name in the header X-Unique-Identifier-Key.
  • Pass the value of the third-party record's entity ID stored in the unique custom field in the header X-Unique-Identifier-Value.
  • Pass the header X-Upsert with value set to true to make the API an Upsert API.
In the JSON string parameter, include the respective record's update payload.

To learn more, read our API help document on updating an item using a custom field's unique value.

If you've any queries regarding updating and upserting records, please contact support@zohobooks.com or support@zohoinventory.com, and we'll be happy to help you. 

Cheers,
The Zoho Finance Team



      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

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

                              Zoho CRM コンテンツ






                                ご検討中の方

                                  • Recent Topics

                                  • customer data security

                                    We are exploring ways to enhance our within Zoho CRM. Our Goal: We want to fully integrate RingCentral with Zoho CRM to enable click-to-call functionality for our sales team. However, to comply with data privacy regulations and protect customer contact
                                  • Zoho Cliq not working on airplanes

                                    Hi, My team and I have been having this constant issue of cliq not working when connected to an airplane's wifi. Is there a reason for this? We have tried on different Airlines and it doesn't work on any of them. We need assistance here since we are constantly
                                  • Sync CRM inventory data with Zoho Books

                                    I just switched everything over to ZoHo books, but I am trying to find out why the CRM Estimates, Invoices, and Sales Orders created in ZoHo CRM are not then duplicated in ZoHo Books? I had Quickbooks before, and had to do everything twice, I thought
                                  • mask Customer phone number and agents cant see customer phone number

                                    Is there any way we can integrate Zoom Phone with Zoho CRM while ensuring that customer phone numbers remain masked? We need a solution where agents can make outbound calls but cannot see customer phone numbers. Please let us know if there is any solution
                                  • Email Reminders on Shared Calendars

                                    How do we turn off the setting that emails reminders to everyone who has accepted or declined a calendar invite? If 8 of us have been invited to the same meeting, we receive 8 notifications for every step of the process, from invitation to decision.
                                  • WebDAV / FTP / SFTP protocols for syncing

                                    I believe the Zoho for Desktop app is built using a proprietary protocol. For the growing number of people using services such as odrive to sync multiple accounts from various providers (Google, Dropbox, Box, OneDrive, etc.) it would be really helpful if you implemented standard protocols such as WebDAV / FTP / SFTP so that alternative inc clients can be used.
                                  • What's New in Zoho Inventory | Q2 2025

                                    Hello Customers, The second quarter have been exciting months for Zoho Inventory! We’ve introduced impactful new features and enhancements to help you manage inventory operations with even greater precision and control. While we have many more exciting
                                  • How to refresh a ticket view ?

                                    I am doing a widget where I send a rest api call to make a new draft to the ticket I am viewing. The issue is sometimes it refresh a ticket view and I can see inserted draft right away, but sometimes I do not see it even if it is inserted correctly and
                                  • Ugh! - Text Box (Single Line) Not Enough - Text Box (Multi-line) Unavailable in PDF!

                                    I provide services, I do not sell items. In each estimate I send I provide a customized job description. A two or three sentence summary of the job to be performed. I need to be able to include this job description on each estimate I send as it's a critical
                                  • Merge Items

                                    Is there a work around for merging items? We currently have three names for one item, all have had a transaction associated so there is no deleting (just deactivating, which doesn't really help. It still appears so people are continuing to use it). I also can't assign inventory tracking to items used in past transactions, which I don't understand, this is an important feature moving forward.. It would be nice to merge into one item and be able to track inventory. Let me know if this is possible.
                                  • Supervisor Rules - Zoho Desk

                                    Hi, I have set up a Supervisor Rule in Zoho Desk to send an email alert when a ticket has been on hold for 48 hours. Is there a way to change it so that the alert only sends once and not on an hourly basis? Thank you Laura
                                  • ResponseCode 421, 4.7.0 [TSS04] Messages from 136.143.188.51 temporarily deferred due to user complaints

                                    Had email bounce. Let me know if you can fix this. Thanks. Michael
                                  • Automation #15: Automatically Adding Static Secondary Contacts

                                    Rockel is a top-tier client of Zylker traders. Marcus handles communications with Rockel and would like to add Terence, the CTO of Zylker traders to the email conversations. In this case, the emails coming from user address rockel.com should have Terence
                                  • New Zoho triggers Google Dangerous flag due toabnormal charcters

                                    Just signed up and doing my first email test. I sent it to my google email account but it got flagged as Dangerous" due abnormal characters. My DNS setup looks ok. Page snips attached Help Please Thanks, Rick DC PowerWorld
                                  • Is there a API to fetch tasks in a Board/Section

                                    I am writing a scheduled function that retrieves all the tasks and send an reminder on cliq. I cannot seem to find a API to fetch tasks (by user / board / section) What are the way to fetch tasks?
                                  • Having trouble fetching contents of Zoho Connect Feeds using the API, requesting alternative API documentation.

                                    I'm trying to retrieve feed/post data from Zoho Connect using the API but facing challenges with the current documentation. What I've tried: OAuth authentication is working correctly (getting 200 OK responses) Tested multiple endpoints: /pulse/nativeapi/v2/feeds,
                                  • Adding an Account Name to Tasks/Reminders

                                    Does anyone know how to add the related account name to a task?  When we look at the list of activities and when the reminders pop up, there is no way of quickly seeing who the account is. 
                                  • Triggering Zoho Flow on Workdrive File Label

                                    Right now Im trying to have a zoho flow trigger on the labeling/classification of a file in a folder. Looking at the trigger options they arent great for something like this. File event occurred is probably the most applicable, but the events it has arent
                                  • SendMail to multiple recipients

                                    Hi, I'm trying to send an email to a list of recipients.  Right now the "to" field is directed to a string variable. (List variables won't work here). In the string variable, how can I make it work? trying "user@app.com;user2@app.com" or "user@app.com; user2@app.com" just failed to send the emails. Ravid
                                  • Populate drop down field from another form's subform

                                    Hello, I found how to do that, but not in case of a subform. I have a Product form that has a subform for unit and prices. A product might have more than one unit. For example, the product "Brocoli" can be sold in unit at 3$ or in box of 10 at 25 $. Both
                                  • Usar o Inventory ou módulo customizado no CRM para Gestão de Estoque ?

                                    Minha maior dor hoje em usar o zoho é a gestão do meu estoque. Sou uma empresa de varejo e essa gestão é fundamental pra mim. Obviamente preciso que esse estoque seja visível no CRM, Inicialmente fiz através de módulos personalizados no próprio Zoho CRM,
                                  • Signup forms behaviour : Same email & multiple submissions

                                    My use case is that I have a signup form (FormA) that I use in several places on my website, with a hidden field so I can see where the contact has been made from. I also have a couple of other signup forms (FormB and FormC) that slight differences. All
                                  • getting error in project users api

                                    Hello, I'm getting a "Given URL is wrong" error when trying to use the Zoho Projects V3 API endpoint for adding users to a project. The URL I'm using is https://projectsapi.zoho.com/api/v3/portal/{portalid}/projects/{projectid}/projectusers/ and it's
                                  • Change total display format in weekly time logs

                                    Hi! Would it be possible to display the total of the value entered in the weekly time log in the same format that the user input? This could be an option in the general settings -> display daily timesheet total in XX.XX format or XX:XX.
                                  • Different Company Name for billing & shipping address

                                    We are using Zoho Books & Inventory for our Logistics and started to realize soon, that Zoho is not offering a dedicated field for a shipping address company name .. when we are creating carrier shipping labels, the Billing Address company name gets always
                                  • How to display historical ticket information of the total time spent in each status

                                    Hi All, Hoping someone can help me, as I am new to Zoho Analytics, and I am a little stuck. I am looking to create a bar chart that looks back over tickets raised in the previous month and displays how much time was spent in each status (With Customer,
                                  • Zoho Community Weekend Maintenance: 13–15 Sep 2025

                                    Hi everyone, We wanted to give you a heads-up that Zoho Community will undergo scheduled maintenance this weekend. During this period, some community features will be temporarily unavailable, while others will be in read-only mode. Maintenance Window:
                                  • Agent Performance Report

                                    From data to decisions: A deep dive into ticketing system reports An agent performance report in a ticketing system provides a comprehensive view of how support agents manage customer tickets. It measures efficiency and quality by tracking key performance
                                  • Show both Vendor and Customers in contact statement

                                    Dear Sir, some companies like us working with companies as Vendor and Customers too !!! it mean we send invoice and also receive bill from them , so we need our all amount in one place , but in contact statement , is separate it as Vendor and Customer, 
                                  • Pourquoi dans zohobooks version gratuite on ne peut ajouter notre stock d'ouverture??

                                    Pourquoi dans zohobooks version gratuite on ne peut ajouter notre stock d'ouverture ??
                                  • How can I adjust column width in Zoho Books?

                                    One issue I keep running into is as I show or hide columns in reports, the column widths get weird. Some columns have text cut off while others can take a fourth of the page for just a few characters. I checked report layout guides and my settings, but
                                  • Invalid value passed for file_name

                                    System generated file name does not send file anymore - what is the problem?
                                  • Custom Function for Estimates

                                    Hey everyone, I was wondering if there was a way to automate the Subject of an estimate whenever one is created or edited: * the green box using following infos: * Customer Name and Estimate Date. My Goal is to change the Subject to have this format "<MyFirm>-Estimate
                                  • This domain is not allowed to add. Please contact support-as@zohocorp.com for further details

                                    I am trying to setup the free version of Zoho Mail. When I tried to add my domain, theselfreunion.com I got the error message that is the subject of this Topic. I've read your other community forum topics, and this is NOT a free domain. So what is the
                                  • Search in module lists has detiorated

                                    Every module has a problem with the search function :-/
                                  • YouTube Live #1: AI-powered agreement management with Zia and Zoho Sign

                                    Hi there! We're excited to announce Zoho Sign’s first YouTube live series, where you can catch the latest updates and interact with our Zoho Sign experts, pose questions, and discover lesser-known features. We're starting off by riding the AI wave in
                                  • Search in module lists has detiorated

                                    Every module has a problem with the search function :-/
                                  • Sales Receipts Duplicating when I run reports why and how do we rectify this and any other report if this happens

                                    find attached extract of my report
                                  • Add Zoho Forms to Zoho CRM Plus bundle

                                    Great Zoho apps like CRM and Desk have very limited form builders when it comes to form and field rules, design, integration and deployment options. Many of my clients who use Zoho CRM Plus often hit limitations with the built in forms in CRM or Desk and are then disappointed to hear that they have to additionally pay for Zoho Forms to get all these great forms functionalities. Please consider adding Zoho Forms in the Zoho CRM Plus bundle. Best regards, Mladen Svraka Zoho Certified Consultant and
                                  • Bigin: filter Contacts by Company fields

                                    Hello, I was wondering if there's a way to filter the contacts based on a field belonging to their company. I.e.: - filter contacts by Company Annual Revenue field - filter contacts by Company Employee No. field In case this is not possibile, what workaround
                                  • Next Page