Zoho CRM Upsert: Sync Records Without Duplicates

Every integration that sends records into Zoho CRM faces the same question: does this record already exist? Get it wrong and you create duplicates, or overwrite the wrong record. Checking first with a search, then deciding whether to insert or update, doubles the calls and leaves a gap in which another process can create the same record. Zoho CRM upsert solves this by inserting a record when no match exists and updating it when one does, in a single call. This guide explains how the upsert API decides what counts as a match, how to choose and order duplicate check fields, how to use an external ID for reliable syncs, and what to check in the responses.

How Zoho CRM upsert works

According to Zoho's Upsert Records API documentation, the API checks for duplicates in specified fields. If a matching record exists, it is updated; otherwise, a new record is inserted. You control which fields are checked, and in what order, with the duplicate_check_fields array in your request.

Allowed fields are of two kinds, according to the same documentation:

• System-defined duplicate check fields, such as Email for Leads
• User-defined unique fields, which you mark as unique in the module's settings

If you do not specify duplicate_check_fields, the system checks system-defined fields first, then user-defined unique fields. If you specify the array but leave out the system-defined field, it is ignored and only the fields you listed are checked. A maximum of 100 records can be inserted or updated per call.

The response tells you what happened to each record: the documentation's sample shows an action of update and the duplicate_field that matched, which is exactly what you need for logging.

Choosing duplicate check fields

The duplicate check field decides which record gets updated, so choose it with care:

• Email is convenient for leads and contacts, but people change jobs, share addresses or use several, so it is not always stable
• Phone numbers are often formatted inconsistently and shared across a company
• Names are never safe as a match key

The most reliable choice for system-to-system syncs is an external ID: the record's ID in the source system, stored in a custom field marked as unique in Zoho CRM. It never changes and means the same thing in both systems. Use email as a secondary check only where it makes sense, such as web form leads that have no source ID.

Order matters when you list several fields. The first field that matches decides the record, so list the most reliable field first.

Using an external ID for reliable syncs

A pattern that works for most integrations:

1. Create a custom field such as Source_ID in the target module and mark it as unique
2. Send the source system's ID in that field on every upsert
3. List Source_ID first in duplicate_check_fields
4. Normalise values before sending, such as trimming spaces and using a consistent case, because "ab-123" and "AB-123" are different values

Because the same message produces the same result however many times it is sent, upsert with an external ID makes retries safe. If a call times out and you resend it, the record is updated rather than duplicated. Our guide to Zoho CRM API error handling covers retry design in more detail.

Worked example: syncing customers from an ordering system

Suppose a distributor syncs customer accounts from its ordering system into Zoho CRM. Each customer has a stable ID in the ordering system, stored in a unique custom field called Source_ID on Accounts. This simplified, untested request body shows one batch, posted to the module's upsert endpoint; the field names other than standard ones are the distributor's own.

{
  "data": [
    {
      "Account_Name": "Northfield Catering Supplies",
      "Source_ID": "ORD-10482",
      "Phone": "+44 20 7946 0000",
      "Billing_City": "Leeds"
    },
    {
      "Account_Name": "Harbour Lane Foods",
      "Source_ID": "ORD-10517",
      "Billing_City": "Bristol"
    }
  ],
  "duplicate_check_fields": ["Source_ID"],
  "trigger": ["workflow"]
}

The trigger array controls which automations run. Zoho's documentation says it can include workflow, approval or blueprint, that all of them run when trigger is not specified, and that an empty array stops workflows running. Here the distributor runs only workflows. For each record, its integration logs the action and matched field from the response, and sends rejected records to a review queue with the error. The phone number and company names are fictitious.

Handling errors and edge cases

Upsert removes one class of problem but not all of them:

• Duplicate data errors: the documentation lists a DUPLICATE_DATA error when a value duplicates a unique field, for example when two existing records already share a value; investigate rather than retrying blindly
• Validation errors: required fields, picklist values and field lengths are still checked, and invalid records are rejected
• Existing duplicates: if your CRM already contains duplicates, upsert cannot know which one to update; clean them first, as our guide to Zoho CRM deduplication explains
• Partial batches: some records in a batch can succeed while others fail, so read the result for every record, not just the overall response

Testing an upsert integration

Before switching an integration on, test the cases that matter most. Send a record that does not exist and confirm it is inserted. Send it again with a changed field and confirm the same record is updated rather than duplicated. Send a record whose external ID differs only in case or spacing to prove normalisation works. Send a record with a missing required field and confirm it reaches the review queue. Finally, resend a whole batch, as a retry would, and confirm the record count does not change. Run these tests in a sandbox or test account first.

Upsert at higher volumes

For thousands of records at once, the standard upsert API's 100-record limit means many calls. Bulk Write supports upsert as an operation, according to Zoho's Bulk Write overview, processing large zipped CSV files asynchronously. Use Bulk Write for initial loads and large periodic updates, and standard upsert for the steady stream of changes that follows. Our guide to the Zoho CRM Bulk Write API covers large imports.

Common mistakes

• Matching on names or other unstable fields
• Listing a weak field before a strong one in duplicate_check_fields
• Not normalising external IDs, so the same record appears with two values
• Running upsert against a module that already contains duplicates
• Treating the batch as successful without reading each record's result
• Forgetting that workflows run by default, so a sync triggers emails or tasks unexpectedly

Frequently Asked Questions

What does Zoho CRM upsert do?

It inserts a record when no match exists and updates the existing record when one does, based on duplicate check fields, in a single API call.

Which field should I use to match records?

For integrations, a unique custom field holding the source system's ID is most reliable. Email suits leads without a source ID but can change.

How many records can one upsert call handle?

Zoho's documentation says a maximum of 100 records can be inserted or updated per call. For larger loads, Bulk Write supports upsert asynchronously.

Does upsert trigger workflows?

By default, workflows, approvals and blueprints run. You can choose which run with the trigger array, or pass an empty array to stop workflows.

Sync records without duplicates

We build Zoho CRM integrations that match records reliably and handle every response. See our Zoho CRM automation services, or talk to us about your data sync.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.