Zoho CRM Bulk API: Choose the Right Option

Moving tens of thousands of records in or out of Zoho CRM one API call at a time is slow and burns through credits. Zoho provides asynchronous bulk APIs for exactly this work, but they are not the answer to every high-volume job, and picking the wrong approach leads to jobs that time out, partial updates and confusing results. The Zoho CRM bulk API family covers Bulk Read for large exports and Bulk Write for large imports and updates, alongside the standard record APIs that handle up to 100 records per call. This guide explains how each option works, how to choose between them, how to design a batch job that survives failures, and what to check after every run.

The options for high-volume work

Zoho CRM offers several ways to process many records. Choosing well starts with knowing what each is designed for.

Standard record APIs insert, update or upsert records synchronously. According to Zoho's documentation for the Upsert Records API, a maximum of 100 records can be inserted or updated per API call. They return results immediately and suit steady streams of changes, such as an integration syncing updates every few minutes.

Bulk Read exports records asynchronously. Zoho's Bulk Read documentation describes creating a job, then either receiving a notification at a callback URL or polling the job status, and downloading the result as a CSV file, or an ICS file for events. Each page of results contains up to 200,000 records, and a page token fetches the next set when there are more. Our guide to the Zoho CRM Bulk Read API covers exports in depth.

Bulk Write imports or updates records asynchronously. According to Zoho's Bulk Write overview, you upload a zipped CSV file, then create a job specifying the operation (insert, update or upsert), the module and the field mappings, and the API can process up to 25,000 records in a single call. The result file lists each row with its ID, status and any error. Our guide to the Zoho CRM Bulk Write API walks through imports step by step.

Choosing the right Zoho CRM bulk API

A simple way to decide:

• Fewer than a few hundred changes, needed immediately: standard record APIs
• Continuous changes from another system: standard APIs in small batches, with queueing and retries
• A full or filtered export of a large module: Bulk Read
• A one-off or scheduled import or update of thousands of records: Bulk Write
• A sequence of related calls that must succeed or fail together: the Composite API, which groups a small number of requests

Volume is not the only factor. Bulk jobs are asynchronous, so they suit work that can wait for a result, such as an overnight data load. If a user is waiting on screen, or a downstream step needs the new record ID immediately, use the standard APIs.

Designing a reliable bulk job

Large jobs fail in ways small ones do not: a file with one malformed row, a job that runs while users edit the same records, or a script that crashes halfway through polling. Design for these from the start.

• Prepare data carefully: validate required fields, picklist values, lookups and date formats before uploading, because rejected rows have to be fixed and reprocessed
• Use stable identifiers: match updates on record IDs or a unique external ID field rather than names
• Split large loads into files of a sensible size, each tracked separately, so one failure does not force a full rerun
• Record every job ID, file and status in your own log, so a crashed script can resume rather than start again
• Prefer callbacks where you can receive them, and poll at a modest interval otherwise
• Schedule heavy jobs outside working hours, and avoid running them while users are mass-editing the same module

Before the first real run, rehearse the job on a small file, ideally in a sandbox or test account, and read the full result. Rehearsal catches mapping mistakes, unexpected workflow triggers and permission problems while they are cheap to fix.

Worked example: an export job that survives interruption

Suppose an operations team exports its Contacts module every night to a reporting database. The module holds more than 200,000 records, so the export spans several pages. This simplified, untested Python sketch shows the structure; token handling, error handling and storage are left out for clarity.

import time
import requests

BASE = "https://www.zohoapis.com/crm/bulk/v8"

def run_export(token, fields, save_page, log):
    headers = {"Authorization": "Zoho-oauthtoken " + token}
    query = {"module": {"api_name": "Contacts"}, "fields": fields}
    while True:
        job = requests.post(BASE + "/read", json={"query": query}, headers=headers).json()
        job_id = job["data"][0]["details"]["id"]
        log("created", job_id)
        while True:
            time.sleep(60)
            info = requests.get(BASE + "/read/" + job_id, headers=headers).json()["data"][0]
            if info["state"] == "COMPLETED":
                break
        result = info["result"]
        save_page(job_id, requests.get(BASE + "/read/" + job_id + "/result", headers=headers).content)
        log("saved", job_id)
        if not result.get("more_records"):
            return
        query = {"page_token": result["next_page_token"]}

The job states and the page token follow Zoho's job details documentation, which lists ADDED, QUEUED, IN PROGRESS and COMPLETED as states and returns more_records and next_page_token in the result. In production, the team would also handle failed jobs, refresh tokens and stop after a maximum wait. Because each job ID is logged as it is created and saved, a restarted script can pick up from the last saved page.

Checking results

Never assume a bulk job did what you intended. After each run:

• Compare record counts with the source, by module and, for imports, by operation
• Download and read the Bulk Write result file, and reprocess failed rows after fixing the cause
• Spot-check a sample of records, including lookups and picklists
• Confirm that workflows triggered by the change ran, or were deliberately skipped
• Keep result files for an agreed period, so you can answer questions later

Limits and credits

Every approach consumes API credits and is subject to concurrency limits, which vary by edition and are documented in Zoho's API limits page. Check how your chosen APIs consume credits before scheduling large recurring jobs, and leave headroom for integrations that run during the day. Our guide to Zoho CRM API limits covers strategies for staying within them.

Common mistakes

• Using standard APIs record by record for large one-off loads
• Using bulk jobs where a user or process needs an immediate result
• Uploading unvalidated files and fixing errors row by row afterwards
• Matching on names instead of IDs or unique fields
• Not logging job IDs, so an interrupted script starts over
• Ignoring the result file because the job status says completed

Frequently Asked Questions

What is the Zoho CRM bulk API?

It refers to Zoho's asynchronous Bulk Read and Bulk Write APIs, which export or import large numbers of records through jobs that produce downloadable files.

How many records can Bulk Write process?

Zoho's documentation says Bulk Write can insert, update or upsert up to 25,000 records in a single API call, using a zipped CSV file.

When should I use standard APIs instead of bulk APIs?

When changes are small, continuous or needed immediately, such as an integration syncing updates. Bulk jobs suit large loads that can wait for a result.

How do you know a bulk job succeeded?

Check the job status, then read the result file, compare counts with the source and spot-check records. A completed job can still contain failed rows.

Move large data volumes safely

We design and run bulk data jobs for Zoho CRM with validation, logging and checks built in. See our Zoho CRM automation services, or talk to us about your data volumes.

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.