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


    • Recent Topics

    • text length in list report mobile/tablet

      Is there a way to make the full text of a text field appear in the list report on mobile and tablet? With custom layouts, the text is always truncated after a certain number of characters.

    • Automation #4 - Auto Delete Tickets based on Rules

      This is a monthly series in which 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. Unwanted tickets spamming

    • Zoho Community Digest — Enero 2026

      ¡Hola, comunidad! 🌟 Aquí os traemos las novedades más interesantes de Zoho durante este mes de enero, incluyendo actualizaciones de productos, integraciones y un recordatorio sobre los workshops certificados que vuelven a España. 🎓 Eventos y Comunidad

    • Automation #3 - Auto-sync email attachments to 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. Most of our customers use email

    • Automation #11 - Auto Update Custom Fields with Values from Emails

      This is a monthly series designed to help you get the best out of Desk. We take our cue from what's being discussed or asked about the most in our community. Then we find the right use cases that specifically highlight solutions, ideas and tips to optimize

    • Automation #13 - Auto assign tickets based on agent shift time

      This is a monthly series designed to help you get the best out of Desk. We take our cue from what's being discussed or asked about the most in our community. Then we find the right use cases that specifically highlight solutions, ideas and tips to optimize

    • Automation #14: Capture Jira Issue Key/ID in a Ticket Custom Field

      Hello Everyone! This month's edition brings you a custom function to consolidate your records associated with Jira integration. Jira integration enables support engineers and R&D units to collaborate seamlessly on feature development, product improvement,

    • Automation #16: Automate Ticket Reopening on Scheduled Timestamp

      Hello Everyone! This edition uncovers the option to schedule reopening a ticket automatically. Zylker Finance tracks insurance policyholder activities through Zoho Desk. For policyholders who pay monthly premiums, tickets are closed upon payment completion.

    • Automation#19:Auto-Close Tickets Upon Task Completion

      Hello Everyone! We’re excited to bring you another custom function this week. In this edition, we’ll show you how to automatically close tickets when all associated tasks are marked as completed. Let’s see how ZylkaPure, a leading water filter company,

    • 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

    • City field suggestion in Zoho Books

      Hi team, We are using Customers module in Zoho Books. In the Address section, we want to understand whether the City field can show suggestions while typing using any API or built-in feature. For example, if a user types “Mum”, can the system suggest

    • Improved UX design for Projects CRM integration

      The current integration embeds the entier projects inteface into the CRM this is confusing and allows users to get lost. For example as a user i navigate to an account and go down to the related projects list and want to get information about a specific

    • Link Purchase Order to Deal

      Zoho Books directly syncs with contacts, vendors and products in Zoho CRM including field mapping. Is there any way to associate vendor purchase orders with deals, so that we can calculate our profit margin for each deal with connected sales invoices

    • Transformer vos stocks en décisions intelligentes avec Zoho Inventory et Zoho Analytics

      Zoho Inventory permet de suivre facilement les niveaux de stock et d’anticiper les restockages. Pour de nombreuses entreprises, cela suffit à gérer les opérations au quotidien. Mais à mesure que l’activité se développe, cette clarté peut commencer à montrer

    • WorkDrive Download Issue

      My client has been sending me files via WorkDrive, which generally has worked fine. Recently files won't download at all. If you try and individually select and download a file, a popup will appear in the bottom right saying it's preparing and then it

    • Zoho Commerce - Poor Features Set for Blogging

      Hi Zoho Commerce team, I'm sure you will have noticed that I have been asking many questions about the Blogs feature in Commerce. I thought that it would be useful if I share my feedback in a constructive way, to highlight the areas which I feel need

    • Security Enhancements | Migrate to the Updated Policies

      Hello everyone, Zoho Directory's security policies have been updated and reorganized into three new policies with features that enhance the overall organization security. These policies provide a stronger and more secure sign-in methods and improve the

    • Bring Zoho Shifts Capabilities into Zoho People Shift Module

      Hello Zoho People Product Team, After a deep review of the Zoho People Shift module and a direct comparison with Zoho Shifts, we would like to raise a feature request and serious concern regarding the current state of shift management in Zoho People.

    • Quick Create needs Client Script support

      As per the title. We need client scripts to apply at a Quick Create level. We enforce logic on the form to ensure data quality, automate field values, etc. However, all this is lost when a user attempts a "Quick Create". It is disappointing because, from

    • How to block a WhatsApp user for sending spam

      Is there a way to block those whatsapp users that just come to play and annoy our service, they also spam us. We have a waba service with sales iq

    • Inquiry regarding auto-save behavior for Zoho Sign Embedded Sending

      Dear Zoho Support Team, I am currently integrating Zoho Sign's Embedded Sending functionality using iframes on my website. I would like to know if there is a way to ensure that the document state (including any added fields) is automatically saved as

    • Introducing Connected Records to bring business context to every aspect of your work in Zoho CRM for Everyone

      Hello Everyone, We are excited to unveil phase one of a powerful enhancement to CRM for Everyone - Connected Records, available only in CRM's Nextgen UI. With CRM for Everyone, businesses can onboard all customer-facing teams onto the CRM platform to

    • Automation#17: Auto-Create Tasks in Zoho Projects Upon Ticket Creation in Zoho Desk

      Hello Everyone, This edition delivers the solution to automatically create a task in Zoho Projects when a ticket is created in Zoho Desk. Zylker Resorts uses Zoho Desk for bookings and handling guest requests. Zylker resorts outsources cab bookings to

    • Automation#20 : Auto-Add Ticket Tags based on Keywords

      Hello Everyone! Welcome to unveiling custom functions on our Community series. This week's post lets you add tags to your tickets automatically based on the keywords in the ticket subject and the ticket thread. Discover how this custom function helps

    • Automation#21: Track Ticket Transfers Across Departments

      Hello Everyone! With Halloween just around the corner, we'd like to let you know the Zoho Desk team is always there to sweep away your customer service troubles! This week, we’re excited to introduce a custom function that tracks tickets moved between

    • Email Integration - Zoho CRM - OAuth and IMAP

      Hello, We are attempting to integrate our Microsoft 365 email with Zoho CRM. We are using the documentation at Email Configuration for IMAP and POP3 (zoho.com) We use Microsoft 365 and per their recommendations (and requirements) for secure email we have

    • Homepage not assignable to group

    • MS Teams for daily call operations

      Hello all, Our most anticipated and crucial update is finally here! Organizations using Microsoft Teams phone system can now integrate it effectively with Zoho CRM for tasks like dialling numbers and logging calls. We are enhancing our MS Teams functionality

    • Automation#22 Track Ticket Duration at Specific Status

      Hello Everyone! Welcome back to the Community Learning Series! Today, we explore how Zylker Techfix, a gadget servicing firm, boosted productivity by tracking the time spent at a particular ticket status in Zoho Desk. Zylker Techfix customized Zoho Desk’s

    • Automation#23: Automate Guided Conversations in Zoho Desk with Business Hours

      Hello Everyone, This week's edition introduces a custom function designed to automate Guided Conversations in Zoho Desk, based on your business hours. With this feature, you can align the bot's behavior with your business schedule, ensuring a smooth and

    • Address changes in quote form

      When entering a quote, the first piece of information required is the Account, which properly populates the billing and shipping address fields. Then I use the lookup function to select a contact, and when I do, the billing and shipping addresses are

    • Automation#24: Auto-Update custom field from Accounts to Tickets

      Hello Everyone! Welcome back to the Community Learning Series! This episode dives into how Zylker Techfix streamlines account-related ticket references. Previously, employees had to manually check account details to retrieve specific customer information,

    • Automation#31: Automate Splitting Names for New Contact Records

      Hello Everyone, This week, we present to you a custom function, which allows you to split the first and last names from the user's email ID based on the separator used in the ID. Having grown into a large firm, Zylker Techfix aims to optimize its processes,

    • local file csv import problem

      The issue occurs when I upload a CSV file via Databridge. In the preview, everything looks correct — the values are in the proper columns. However, after clicking Import, the first column becomes empty, and the values from that column appear in a new

    • Kaizen #227 : Client Script Support for List Page (Canvas)

      Hello everyone! Welcome to another week of Kaizen. In today's post lets see how Client Script can be used in Canvas List Page to mask sensitive information from specific roles and add colors to Canvas List Page records based on custom criteria.This use

    • Implement Date-Time-Based Triggers in Zoho Desk

      Dear Zoho Desk Support Team, We are writing to request a new feature that would allow for the creation of workflows triggered by specific date-time conditions. Currently, Zoho Desk does not provide native support for date-time-based triggers, limiting

    • Automation#25: Move Tickets to Unassigned When the Owner Is Offline

      Hello Everyone, Welcome to this week's Community Series! 'Tis the holiday season—a time when work often takes a brief pause. The holiday spirit is in full swing at Zylker Techfix too, with employees taking some well-deserved time off. During this period,

    • Automation#27: Retain Ticket Owner on Moved Tickets

      Hello Everyone! This week, we present to you a custom function that retains the ticket owner when a ticket is moved from one department to another. Here’s more to help you understand the custom function: At Zylker Techfix, Alex, the Support Engineer manages

    • Automation#28 Notify Agents on Article Expiry

      Hello Everyone! This week, we’re bringing you a feature that notifies your team when articles in the Knowledge Base are set to expire to keep your content relevant and helpful for customers. The Zoho Desk's Knowledge Base is an asset for customers to

    • Automation#29 Retain ticket status on moved tickets

      Hello Everyone, Hear out Zylker Techfix’s Success Story on Smoother Ticket Transitions! Zylker Techfix, a gadget servicing firm committed to quick repairs and timely deliveries, faced a challenge when ticket statuses changed automatically while moving

    • Next Page