What we do
Tools
Industries
Department
How we workLet's talk →
Home/Zoho CRM/Zoho CRM API v8
Zoho CRM developer reference

Zoho CRM API Reference: Domains, Credits, the Right Call per Job, COQL and Notifications

The Zoho CRM API is REST over JSON, versioned in the path, with v8 the current version. Everything here is what you need once you have a token. Getting the token itself is the same OAuth flow for every Zoho product, and it's laid out step by step on our Zoho API token guide. Deciding what to connect, rather than how? The Zoho CRM integrations hub is for that.

The essentials

Base URL: {api_domain}/crm/v8/, for example https://www.zohoapis.com/crm/v8/Leads. Take api_domain from the token response instead of hard-coding it, because it differs by data center.

Header: Authorization: Zoho-oauthtoken {access_token}. Access tokens last an hour; the refresh token doesn't expire unless it's revoked.

Scopes: ZohoCRM.modules.ALL while testing, then narrow to ZohoCRM.modules.{module}.READ or .ALL for each module the integration really touches.

Which call for which job

Job Call Watch for
Read a list of records GET /crm/v8/{module}?fields=... fields is required, up to 50 per call. 200 records per page. Past 2,000 records, switch from page to the next_page_token, which is valid for 24 hours.
Find records with conditions or joins POST /crm/v8/coql with select_query LIMIT defaults to 200 and tops out at 2,000. Up to 25 WHERE criteria. One set of criteria can page through 100,000 records, after that use Bulk Read.
Create or update from another system POST /crm/v8/{module}/upsert Up to 100 records per call, at 1 credit per 10 records. Set duplicate_check_fields to your external ID so reruns update instead of duplicating.
Export a whole module Bulk Read API Starting a job costs 50 credits, then you download the file. Far cheaper than paging a large module record by record.
React to changes POST /crm/v8/actions/watch Channels expire. See the notifications section below.
Custom modules and fields Same endpoints, using the API name Use the field and module API names from the metadata calls, not the labels users see. Labels get renamed; API names don't.

How the daily API credits add up

Credits run on a rolling 24-hour window. Each edition gets 50,000 plus an amount per user license: 250 on Standard (capped at 100,000), 500 on Professional, 1,000 on Enterprise and Zoho One, 2,000 on Ultimate. The Free edition gets a flat 5,000.

Example: a 20-user Professional org with one sync
Base allowance 50,000
20 Professional licenses (500 each) 10,000
Hourly upsert of 2,000 changed records (20 calls of 100 records, 10 credits each, 24 runs) −4,800
COQL lookups every 5 minutes (2,000-row limit, 3 credits, 288 runs) −864
500 emails a day through Send Mail (20 credits each) −10,000
Left for everything else 44,336

Once half the day's credits are used, responses carry an X-API-CREDITS-REMAINING header. Log it. Extra credits can be bought from the API Dashboard, but most overruns come from re-reading records that haven't changed.

Getting change notifications from Zoho CRM

Two options. Notification channels come from the API. Webhooks are a workflow action an admin sets up in Zoho CRM, available from the Standard edition up and capped per day.

  1. 1

    Open a channel

    POST to /crm/v8/actions/watch with a numeric channel_id, the events you want such as ["Deals.edit", "Leads.create"], and your notify_url. The operations are create, edit, delete and all.

  2. 2

    Set a token so you can trust the callback

    Add a token of up to 50 characters. Zoho sends it back with every notification, so your endpoint can reject anything that doesn't carry it.

  3. 3

    Narrow it to the fields that matter

    A notification_condition makes the channel fire only when particular fields change, such as the deal stage, rather than on every edit.

  4. 4

    Renew it before it expires

    Set channel_expiry to at most one week ahead. Leave it out and the channel lasts one hour.

    Watch for: the silent stop. Nothing errors when a channel expires; the notifications just end. Schedule a renewal, and run a periodic COQL check on Modified_Time to catch anything missed.

Why Zoho CRM API calls fail

The token works for one org and not another

How you'll know: INVALID_TOKEN or an empty result, though the same code works for a colleague's account.

Fix: The org is in a different data center. Accounts live at accounts.zoho.com, .eu, .in, .com.au, .jp or .com.cn, and Canada at accounts.zohocloud.ca. Use the accounts server and api_domain that belong to that org.

It worked in production but fails in the sandbox

How you'll know: A token that's fine against the live org is rejected by the sandbox or developer org.

Fix: Tokens are specific to the environment they were issued for. Generate a separate token for each environment and keep them apart in your config.

TOO_MANY_REQUESTS with credits still left

How you'll know: Bursts of parallel upserts or COQL queries fail while the credit count looks healthy.

Fix: You've hit concurrency, not credits. Orgs allow 5 to 25 calls at once depending on edition, and heavier calls, including COQL, upserts of more than 10 records and Send Mail, share a limit of 10 at once on every edition. Queue them.

COQL stops returning rows partway through

How you'll know: Paging a big query with LIMIT and an offset dries up around 100,000 records.

Fix: That's the ceiling for one set of criteria. Split the query by date range, or use Bulk Read for the full module.

Questions people ask

Do I need a developer to use the Zoho CRM API?

Not to try a call or two. For anything that runs on a schedule, listens for notifications, or writes records on its own, yes: it needs someone to build it, watch credit use and renew channels. That's the part n-frames builds and runs.

Does Zoho CRM use OAuth2 for API access?

Yes. You register a client in the Zoho API Console and exchange a grant code for access and refresh tokens, scoped to the modules the integration needs. The full sequence is on our Zoho API token guide, since it's shared across Zoho products.

Are there rate limits on the Zoho CRM API?

Yes, two kinds. A daily credit allowance on a rolling 24 hours, set by edition and number of user licenses, and a limit on simultaneous calls. The ledger above shows how a typical sync spends the credits.

Can the Zoho CRM API reach custom modules and fields?

Yes, through the same endpoints as the standard modules. Address them by API name, which you can read from the module and field metadata calls at 1 credit each.

Does Zoho CRM support webhooks?

Yes, as a workflow action on Standard and higher editions, and separately through notification channels opened with the API. Channels last a week at most, so they have to be renewed.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.