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