Complete Zoho API Guide: From Setup to Integrations
Learn how to use Zoho API v8 for OAuth authentication, CRM integrations, multi-DC routing, and large-scale data automation.
If you have ever tried to sync thousands of leads from a marketing tool into Zoho CRM, you already know how important the API is. It is the layer that connects your Zoho org to every integration, automation, and custom workflow you want to build.
In many cases, it is the difference between a Zoho deployment that scales across regions and one that breaks the moment a European customer signs up, and their data lands in Zoho.eu instead of zoho.com.
Zoho development has shifted significantly over the last year. Zoho CRM API v8 is the current stable version, replacing v7 as the default for new integrations. OAuth 2.0 is the only supported authentication protocol. The old auth-token model is gone. And Zoho now operates eight regional data centers, each with its own accounts URL and API domain, but getting this wrong is the single most common reason integrations fail in production.
This guide walks through everything you need to work effectively with the Zoho API.
What is the Zoho API?
The Zoho API is a collection of REST interfaces that let external applications and services interact with data inside a Zoho organization. Through these APIs, developers can read, create, update, and manage resources such as CRM records, invoices, support tickets, inventory levels, HR data, and custom Creator app data.
In practical terms, the Zoho API is the connection layer between your Zoho org and external systems or custom features. It lets applications securely read and write data across any Zoho product, making it possible to automate processes and extend Zoho beyond its default capabilities.
From syncing leads between a landing page and Zoho CRM, to pushing purchase orders from Zoho Inventory into a 3PL, to powering internal dashboards or embedding Zoho data into a custom portal, the API provides the programmatic access needed to connect Zoho with the rest of your technology stack.
Zoho API Types: Which One Do You Need in 2026?
Zoho is not a single product but a suite of more than thirty applications, and each one has its own REST API. Picking the wrong one is the most common mistake developers make before writing a single line of code.
The main Zoho APIs available today, grouped by category:
| Category | Product APIs | Typical Use |
|---|---|---|
| Sales & Marketing | CRM, Bigin, Campaigns, Commerce, SalesIQ, Bookings, Sign | Lead capture, pipeline automation, marketing ops |
| Customer Service | Desk, Assist | Ticketing, support automation, and remote sessions |
| Finance | Books, Invoice, Inventory, Expense, Billing | Accounting sync, subscription billing, and stock control |
| Human Resources | People, Recruit | HRIS sync, ATS integration |
| Collaboration | Mail, Cliq, Projects, Sprints, WorkDrive, Writer, Sheet, Meeting | Productivity integrations, document automation |
| Business Intelligence | Analytics | Reporting, embedded dashboards |
| Custom Solutions | Creator, Catalyst | Low-code apps, serverless backends |
If you are building a CRM integration, which covers most Zoho API work, use the Zoho CRM v8 REST API. It is actively maintained, has the most complete feature coverage, and receives all new capabilities first.
If you are working with finance data, the Zoho Books or Zoho Invoice APIs are the right choice and use the same OAuth 2.0 flow as CRM.
For support workflows, use the Zoho Desk API. For custom apps, Catalyst provides a serverless runtime, and Creator exposes REST endpoints for every Creator app you deploy.
Important: all Zoho product APIs share the same OAuth 2.0 authentication system and data-center routing. Once you understand the CRM flow, the same credentials and patterns work across every other Zoho product, such as just adding the correct scopes for each.
How Zoho API Versioning Works
Zoho CRM’s current stable API is v8, released in 2025. It replaced v7 as the default version for new integrations. Older versions (v2, v3, v6, v7) are still accessible, but v8 receives all new features, SDK updates, and performance improvements.
Version names are simple integers appended to the URL path:
https://www.zohoapis.com/crm/v8/Leads
https://www.zohoapis.com/crm/v7/Leads
Each stable version is supported for an extended period, typically several years, giving you a long runway to migrate. Unlike Shopify’s quarterly cadence, Zoho does not publish a fixed release calendar. Major versions appear roughly every 18 to 24 months, and deprecation notices are announced well in advance through the developer console and email to app owners.
Key Versioning Rules
- Always pin the version in the URL. Never rely on a default. A request to /crm/Leads without a version can break at any time.
- Test against v8 for all new work. v7 is still supported but will not receive new features such as the Zia Assistant API, Workflow APIs, Recycle Bin APIs, or Data Sharing Rules APIs.
- Do not mix versions in a single integration. Some response shapes changed between v7 and v8 (for example, the structure of related records and the info object in list responses). Pick one and stay on it until you migrate deliberately.
- Subscribe to the Zoho Developer Community forum. That is where Zoho publishes breaking changes and deprecation notices earlier than the release notes page.
What’s New in v8
v8 shipped with a large batch of new capabilities that are not available in v7:
- Zia Assistant API: ask AI questions using your org-specific context
- Workflow, Connected Workflow, and Actions APIs: full programmatic control over automation rules, field updates, email notifications, tasks, and webhook actions
- Recycle Bin APIs: list, restore, and permanently delete records
- Data Sharing Rules APIs: manage cross-module access
- Record-Level Email Sharing and Link/Unlink Deal
- OpenAPI 3.0.0 specification for automatic SDK generation across Java, Python, Node.js, PHP, C#, Ruby, TypeScript, JavaScript, and Scala
If your integration depends on any of these features, you are on v8 by default.
Zoho Data Centers: The Thing That Breaks Most Integrations
Zoho operates eight independent regional data centers. Each one has its own accounts server (for OAuth) and its own API domain (for data). A user’s data lives in exactly one data center and can never be accessed from the others.
This is the single most important concept in Zoho API development. If you hardcode accounts.zoho.com and zohoapis.com into your integration, it will silently break the first time a European, Indian, or Australian customer installs it.
Complete Data Center Reference
| Region | Accounts URL (OAuth) | API Domain (Data) |
|---|---|---|
| United States | https://accounts.zoho.com | https://www.zohoapis.com |
| European Union | https://accounts.zoho.eu | https://www.zohoapis.eu |
| India | https://accounts.zoho.in | https://www.zohoapis.in |
| Australia | https://accounts.zoho.com.au | https://www.zohoapis.com.au |
| Japan | https://accounts.zoho.jp | https://www.zohoapis.jp |
| China | https://accounts.zoho.com.cn | https://www.zohoapis.com.cn |
| Saudi Arabia | https://accounts.zoho.sa | https://www.zohoapis.sa |
| Canada | https://accounts.zohocloud.ca | https://www.zohoapis.ca |
How to Handle Multi-DC Correctly
When a user authenticates, Zoho’s authorization server returns three values in the redirect, not just a code:
- code — the grant token
- location — the user’s region (us, eu, in, au, jp, com.cn, sa, ca)
- accounts-server — the exact accounts URL to call for the token exchange
Your integration must use accounts-server for the token exchange, not a hardcoded URL. The token response then includes an api_domain field, use that as the base URL for all subsequent API calls for that user.
// After OAuth callback
const { code, location, 'accounts-server': accountsServer } = req.query;
// Token exchange MUST go to the returned accounts-server, not a fixed URL
const tokenResponse = await fetch(`${accountsServer}/oauth/v2/token`, {
method: 'POST',
body: new URLSearchParams({
grant_type: 'authorization_code',
client_id: process.env.ZOHO_CLIENT_ID,
client_secret: process.env.ZOHO_CLIENT_SECRET,
redirect_uri: process.env.ZOHO_REDIRECT_URI,
code
})
});
const { access_token, refresh_token, api_domain, expires_in } =
await tokenResponse.json();
// Persist api_domain alongside the tokens -- you need it for every API call
await db.tokens.save({
userId,
access_token,
refresh_token,
api_domain,
expires_at: Date.now() + expires_in * 1000
});
Multi-DC Warning
Your Client ID and Client Secret are region-specific. If you registered your app at api-console.zoho.com, those credentials work for the US data center only.
To support other regions, you must register the same app at each regional developer console (api-console.zoho.eu, api-console.zoho.in, and so on) and use the matching credential pair at runtime, selected by the location value returned during OAuth.
Most failed Zoho integrations fail here. Build the DC-routing logic on day one.
How to Get Zoho API Access
Before you can make API requests to a Zoho org, you need to register a client application and obtain OAuth credentials.
For a Single Organization (Self-Client)
Self-Client apps are intended for internal integrations, scripts, and back-office automation where the app will only ever run against your own Zoho org. There is no end-user OAuth redirect; rather, you generate a grant token manually from the console.
- Log in to api-console.zoho.com using the correct regional console for your org.
- Click Add Client and choose Self Client.
- Copy the generated Client ID and Client Secret.
- Open the Generate Code tab, enter the scopes you need (comma-separated), select a validity of up to 10 minutes, and pick the organization.
- Copy the grant code immediately; it expires in minutes, and exchange it for access and refresh tokens using the token endpoint.
Self-Client grant tokens expire in two minutes to ten minutes, depending on what you select. Refresh tokens do not expire until revoked, so you only do the grant exchange once per environment.
For Multiple Organizations (Server-Based App)
If you are building an application that many Zoho customers will install, you need a Server-Based client. This uses the standard OAuth 2.0 authorization code flow with a redirect URI and handles each customer’s auth independently.
- In the API console, click Add Client and choose Server-based Applications.
- Enter your app name, homepage URL, and authorized redirect URI (must match exactly at runtime, including trailing slash).
- Copy the Client ID and Client Secret.
- Repeat the registration in every regional console you plan to support (api-console.zoho.eu, .in, .com.au, etc.).
Scopes: Request Only What You Need
Scopes are granular in Zoho but much more so than in most APIs. A single scope covers a specific module and operation:
| Scope | What it Unlocks |
|---|---|
| ZohoCRM.modules.leads.READ | Read Leads only |
| ZohoCRM.modules.leads.ALL | Full CRUD on Leads |
| ZohoCRM.modules.ALL | Full CRUD on every module |
| ZohoCRM.settings.READ | Read all settings metadata |
| ZohoCRM.bulk.ALL | Bulk read and bulk write |
| ZohoCRM.notifications.ALL | Manage webhook subscriptions |
| ZohoCRM.coql.READ | Run COQL queries |
| ZohoBooks.fullaccess.all | Full access to Zoho Books |
| ZohoDesk.tickets.ALL | Full access to Desk tickets |
Advanced tip: Request narrow scopes. A customer who sees ZohoCRM.modules.ALL in the consent screen is far more likely to decline than one who sees ZohoCRM.modules.leads.READ, ZohoCRM.modules.contacts.READ. Zoho’s review team also flags apps that request scopes they never use.
How to Authenticate with the Zoho API (OAuth 2.0)
Authentication is the first thing every Zoho integration needs to get right. Zoho supports only OAuth 2.0 because there is no static API key option for CRM, Books, Desk, or any modern Zoho product.
For Self-Client apps, the grant token is generated in the console once and exchanged for tokens.
For Server-Based apps, you implement the full authorization code flow.
The OAuth 2.0 Flow for Server-Based Apps
The OAuth process consists of four steps:
- Redirect the user to Zoho for authorization
- Zoho redirects back with a code, location, and accounts-server
- Exchange the code at the returned accounts-server for access and refresh tokens
- Store tokens and api_domain securely for future API requests
Step 1: Redirect the User to Zoho
https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL,ZohoCRM.settings.READ&client_id={client_id}&response_type=code&access_type=offline&redirect_uri=https://yourapp.com/oauth/callback
Parameters:
- scope — comma-separated list of the scopes your integration needs
- access_type=offline — required to get a refresh token; without it, you only get a one-hour access token
- prompt=consent — optional; forces the consent screen even if the user previously approved
For users in other regions, start at accounts.zoho.com anyway. Zoho automatically redirects EU, IN, and AU users to their regional accounts server during login. The redirect parameters returned to your callback will reflect the user’s actual region.
Step 2: Exchange the Code for Tokens
After the user approves, Zoho redirects to your callback with query parameters:
https://yourapp.com/oauth/callback?code=1000.xxxxxxx&location=eu&accounts-server=https://accounts.zoho.eu
Exchange the code at the exact accounts-server URL returned:
cURL:
curl -X POST "https://accounts.zoho.eu/oauth/v2/token" \
-d "grant_type=authorization_code" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "redirect_uri=https://yourapp.com/oauth/callback" \
-d "code={grant_token}"
Node.js:
const params = new URLSearchParams({
grant_type: 'authorization_code',
client_id: process.env.ZOHO_CLIENT_ID,
client_secret: process.env.ZOHO_CLIENT_SECRET,
redirect_uri: process.env.ZOHO_REDIRECT_URI,
code: req.query.code
});
const response = await fetch(`${req.query['accounts-server']}/oauth/v2/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params
});
const tokens = await response.json();
// { access_token, refresh_token, api_domain, token_type: "Bearer", expires_in: 3600 }
Step 3: Use the Access Token
Every API request must include the access token in the Authorization header, with note the non-standard scheme name:
Authorization: Zoho-oauthtoken {access_token}
Not Bearer. This trips up developers who assume Zoho follows the OAuth 2.0 Bearer spec verbatim.
Step 4: Refresh the Access Token
Access tokens expire after 3,600 seconds (one hour). Refresh tokens do not expire, and they remain valid until the user revokes access or you hit the per-user token limit (Zoho stores up to 20 active refresh tokens per user per app; the oldest is evicted when the 21st is issued).
async function refreshAccessToken(userId) {
const { refresh_token, accounts_server } = await db.tokens.get(userId);
const response = await fetch(`${accounts_server}/oauth/v2/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.ZOHO_CLIENT_ID,
client_secret: process.env.ZOHO_CLIENT_SECRET,
refresh_token
})
});
const { access_token, expires_in } = await response.json();
await db.tokens.update(userId, {
access_token,
expires_at: Date.now() + expires_in * 1000
});
return access_token;
}
Advanced tip: refresh proactively, not reactively. Check expires_at before every request and refresh if less than 60 seconds remain. Reactive refresh (waiting for a 401) doubles your latency on every expired request and creates a thundering-herd problem when many tokens expire at once.
Zoho REST API: Core Endpoints and CRUD Operations
Zoho’s CRM API is organized into six functional categories. Every other Zoho product API follows a similar structure.
| Category | Purpose |
|---|---|
| Metadata APIs | Fetch modules, fields, layouts, custom views, and related lists |
| Core APIs | CRUD on records within any module |
| Composite API | Combine up to 5 API calls in a single request |
| Bulk APIs | Async read/write for large datasets |
| Notification APIs | Webhooks for create, update, and delete events |
| Query APIs (COQL) | SQL-style SELECT queries across modules |
Every API request follows the same base structure: {api_domain}/crm/v8/{module_api_name}, where api_domain is the value returned in the OAuth token response (e.g., https://www.zohoapis.com, https://www.zohoapis.eu).
How to Fetch Records from Zoho CRM
The following example retrieves the first 200 Leads, selecting only the fields you care about.
cURL:
curl -X GET \
"https://www.zohoapis.com/crm/v8/Leads?fields=Last_Name,Email,Company,Lead_Status&per_page=200" \
-H "Authorization: Zoho-oauthtoken {access_token}."
Node.js:
const response = await fetch(
`${apiDomain}/crm/v8/Leads?fields=Last_Name,Email,Company,Lead_Status&per_page=200`,
{
headers: { Authorization: `Zoho-oauthtoken ${accessToken}` }
}
);
const { data, info } = await response.json();
console.log(`Fetched ${info.count} of up to ${info.per_page}`);
Response shape:
{
"data": [
{
"id": "554023000000807001",
"Last_Name": "Doe",
"Email": "jane@example.com",
"Company": "Acme",
"Lead_Status": "Contacted"
}
],
"info": {
"per_page": 200,
"count": 1,
"page": 1,
"more_records": false,
"next_page_token": null,
"previous_page_token": null,
"sort_by": "Modified_Time",
"sort_order": "desc"
}
}
Important: the fields parameter is mandatory when fetching lists of records and accepts at most 50 field API names. Asking for every field is not an option, but you must be explicit. This is a performance safeguard introduced in v7 and enforced strictly in v8.
How to Create a Record
const response = await fetch(`${apiDomain}/crm/v8/Leads`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: [
{
Last_Name: 'Doe',
First_Name: 'Jane',
Email: 'jane@example.com',
Company: 'Acme',
Lead_Source: 'Web Download'
}
],
trigger: ['workflow', 'approval', 'blueprint']
})
});
const result = await response.json();
The data array accepts up to 100 records per call. The trigger array controls which CRM automations fire on insert. Omit it in high-volume imports to avoid flooding workflow queues.
How to Upsert Records
Upsert matches on a configurable field (by default, any unique field on the module) and updates the existing record or creates a new one:
await fetch(`${apiDomain}/crm/v8/Leads/upsert`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: [{ Email: 'jane@example.com', Company: 'Acme (updated)' }],
duplicate_check_fields: ['Email']
})
});
Upsert is one of the most underused Zoho endpoints. For any sync-from-external-system workflow, it replaces the awkward “search-then-update-or-create” pattern with a single idempotent call.
HTTP Methods Quick Reference
| Method | Action | Example |
|---|---|---|
| GET | Retrieve records or metadata | Fetch Leads, Deals, or field definitions |
| POST | Create records | Insert new Leads; run Upsert |
| PUT | Update records | Change Lead status or merge |
| DELETE | Delete records (soft) | Move records to the Recycle Bin |
Deletes are soft by default. The records move to the Recycle Bin for 60 days and can be restored via the Recycle Bin API. Only permanent deletion is destructive.
COQL: The Query API You Should Be Using
The Composite Object Query Language (COQL) is Zoho’s SQL-style query engine and is often the single biggest performance win in a Zoho integration. Instead of fetching records and filtering client-side, you write a SELECT statement, and Zoho returns exactly what you asked for in one call.
const query = `
SELECT First_Name, Last_Name, Email, Lead_Status
FROM Leads
WHERE ((Lead_Status = 'Contacted') AND (Created_Time > '2026-01-01T00:00:00+00:00'))
ORDER BY Created_Time DESC
LIMIT 200
`;
const response = await fetch(`${apiDomain}/crm/v8/coql`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ select_query: query })
});
const { data, info } = await response.json();
COQL supports JOINs across related modules, aggregate functions, and subqueries. It counts as a single API credit per call regardless of how many records you scan, which makes it dramatically cheaper than equivalent pagination-based fetches.
Limitations:
- LIMIT cannot exceed 2,000 per query.
- OFFSET pagination works but is slow beyond 10,000 rows. You should use cursor-based criteria (WHERE Created_Time > last_seen) for large scans.
- Not every field is queryable. Rich text and some formula fields are excluded.
Composite API: Five Calls in One Request
The Composite API bundles up to five independent API calls into a single HTTP request. This is useful when you need to fetch related data in one round trip, a record plus its notes plus its related deals, without writing COQL.
const response = await fetch(`${apiDomain}/crm/v8/__composite_request`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
composite_request: [
{ method: 'GET', uri: '/crm/v8/Leads/554023000000807001?fields=Last_Name,Email' },
{ method: 'GET', uri: '/crm/v8/Leads/554023000000807001/Notes' },
{ method: 'GET', uri: '/crm/v8/Leads/554023000000807001/Deals' }
]
})
});
Each sub-request counts as a separate API credit, but you save on HTTP round-trip latency, which matters on mobile clients and long-haul regions.
How to Handle Zoho API Credits and Rate Limits
Zoho uses a credit-based rate limit system, not requests-per-second. Each API call costs one or more credits, and each org has a daily credit budget that resets every 24 hours.
API Credit Limits by Plan (per 24 hours)
| Plan | Base Credits | Per User | Max |
|---|---|---|---|
| Free | 5,000 | — | 5,000 |
| Standard / Starter | 50,000 | +250/user | 100,000 |
| Professional | 50,000 | +500/user | 3,000,000 |
| Enterprise / Zoho One | 50,000 | +1,000/user | 5,000,000 |
| Ultimate / CRM Plus | 50,000 | +2,000/user | Unlimited |
A Standard-edition org with 10 users has 52,500 credits per day.
Credit Costs by Operation
Most calls cost 1 credit. Expensive operations cost more:
| Operation | Credits |
|---|---|
| Standard GET / POST / PUT / DELETE | 1 |
| COQL query | 1 |
| Composite request | 1 per sub-request |
| Convert Lead | 5 |
| Send Mail | 20 |
| Bulk Read Initialize | 50 |
| Bulk Write Initialize | 500 |
A nightly sync that calls Convert Lead 10,000 times burns 50,000 credits because it is enough to wipe out a Standard org’s daily budget in one job. Watch the expensive endpoints.
Concurrency Limits
Separate from daily credits, Zoho enforces a cap on simultaneous in-flight requests per org per app:
| Plan | Max Concurrent Calls |
|---|---|
| Free | 5 |
| Standard / Starter | 10 |
| Professional | 15 |
| Enterprise / Zoho One | 20 |
| Ultimate / CRM Plus | 25 |
Additionally, a sub-concurrency limit of 10 applies to heavy endpoints (Convert Lead, Send Mail, Bulk Write Initialize, and COQL). If more than 10 of those are in flight at once, new requests get a TOO_MANY_REQUESTS error even if you’re well under the main concurrency cap.
How to Implement Retry Logic with Exponential Backoff
async function zohoRequest(url, options, maxRetries = 5) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.status === 429) {
const waitMs = Math.min(60000, 1000 * Math.pow(2, attempt));
console.log(`Rate limited. Waiting ${waitMs}ms (attempt ${attempt + 1})`);
await new Promise(r => setTimeout(r, waitMs));
continue;
}
if (response.status === 401) {
// Access token expired mid-retry -- refresh and try again
options.headers.Authorization = `Zoho-oauthtoken ${await refreshAccessToken(userId)}`;
continue;
}
return response;
}
throw new Error('Max retries exceeded for Zoho API');
}
Zoho does not return a Retry-After header. Exponential backoff capped at 60 seconds works well in practice because Zoho’s concurrency limits clear within a few seconds, while daily-credit exhaustion needs human intervention regardless.
Real-World Warning
During development, you will rarely hit credit limits. In production, a single runaway backfill job can burn through a day’s budget in minutes and block every other integration sharing the same org. Always:
- Run bulk operations through Bulk APIs, not record-by-record loops
- Cache metadata (module, field, layout definitions) for at least 24 hours, as it rarely changes
- Throttle imports to leave headroom for user-driven traffic
- Monitor X-RATELIMIT-REMAINING response headers (returned on every CRM API call) and alert when below 20% of the daily budget
How to Paginate Zoho CRM Results
Pagination in Zoho CRM v8 works two ways, and you need to pick the right one based on the dataset size.
Page-Based Pagination (up to 2,000 records)
For the first 2,000 records, use page and per_page:
async function getFirstBatch(apiDomain, accessToken) {
const leads = [];
let page = 1;
while (page <= 10) { // 10 pages × 200 per page = 2,000 records
const response = await fetch(
`${apiDomain}/crm/v8/Leads?fields=Last_Name,Email&per_page=200&page=${page}`,
{ headers: { Authorization: `Zoho-oauthtoken ${accessToken}` } }
);
const { data, info } = await response.json();
leads.push(...data);
if (!info.more_records) break;
page++;
}
return leads;
}
Token-Based Pagination (beyond 2,000 records)
Beyond record 2,000, page-based pagination stops working, and you must switch to page_token:
async function getAllRecords(apiDomain, accessToken) {
const leads = [];
let pageToken = null;
while (true) {
const url = pageToken
? `${apiDomain}/crm/v8/Leads?fields=Last_Name,Email&per_page=200&page_token=${pageToken}`
: `${apiDomain}/crm/v8/Leads?fields=Last_Name,Email&per_page=200`;
const response = await fetch(url, {
headers: { Authorization: `Zoho-oauthtoken ${accessToken}` }
});
const { data, info } = await response.json();
leads.push(...data);
if (!info.more_records) break;
pageToken = info.next_page_token;
}
return leads;
}
Key facts about token pagination:
- Page tokens are user-specific; a token issued for one OAuth session cannot be used by another.
- Tokens expire after 24 hours.
- The total ceiling per query is 100,000 records. For larger scans, use Bulk Read.
- You cannot combine page and page_token in the same request.
How to Use Zoho Bulk APIs for Large Datasets
Standard pagination tops out at 100,000 records per query. For anything larger, full-org exports, initial data migrations, and nightly warehouse sync, use the Bulk Read and Bulk Write APIs. These run asynchronously on Zoho’s servers and produce a downloadable CSV.
Bulk Read costs 50 credits to initialize and then nothing per record. Bulk Write costs 500 credits to initialize. Given that page-based fetching of 500,000 records would cost 2,500 individual API credits plus hit the 100k ceiling, Bulk is dramatically cheaper for any export above a few thousand records.
Step 1: Initialize a Bulk Read Job
const response = await fetch(`${apiDomain}/crm/bulk/v8/read`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: {
module: { api_name: 'Leads' },
fields: ['Last_Name', 'Email', 'Company', 'Lead_Status'],
page: 1
}
})
});
const { data } = await response.json();
const jobId = data[0].details.id;
Step 2: Poll Until Complete
async function waitForBulkJob(apiDomain, accessToken, jobId) {
while (true) {
const response = await fetch(`${apiDomain}/crm/bulk/v8/read/${jobId}`, {
headers: { Authorization: `Zoho-oauthtoken ${accessToken}` }
});
const { data } = await response.json();
const job = data[0];
if (job.state === 'COMPLETED') return job.result.download_url;
if (job.state === 'FAILED') throw new Error(`Bulk job failed: ${JSON.stringify(job)}`);
console.log(`Status: ${job.state}, records so far: ${job.result?.count ?? 0}`);
await new Promise(r => setTimeout(r, 10000));
}
}
Step 3: Download and Parse the Result
The result is a zipped CSV. Stream it rather than loading it into memory, so bulk exports can easily exceed several GB.
const downloadUrl = await waitForBulkJob(apiDomain, accessToken, jobId);
const result = await fetch(`${apiDomain}/crm/bulk/v8/read/${jobId}/result`, {
headers: { Authorization: `Zoho-oauthtoken ${accessToken}` }
});
// Pipe result.body directly to a file, then unzip and parse the CSV
A single bulk read fetches up to 200,000 records per job across up to five pages. For larger scans, issue sequential jobs incrementing the page.
See the case study → Zoho Integration with Shopify for Real-Time Orders Sync
How to Set Up and Verify Zoho CRM Notifications (Webhooks)
Zoho CRM Notifications are webhook-style subscriptions that push events to your app whenever records are created, updated, or deleted.
How to Subscribe to Events
const response = await fetch(`${apiDomain}/crm/v8/actions/watch`, {
method: 'POST',
headers: {
Authorization: `Zoho-oauthtoken ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
watch: [
{
channel_id: '1001',
channel_expiry: '2026-05-20T00:00:00+00:00',
events: ['Leads.create', 'Leads.edit', 'Leads.delete'],
notify_url: 'https://yourapp.com/webhooks/zoho',
token: 'shared-secret-for-verification',
notify_on_related_action: true
}
]
})
});
Key fields:
- channel_id — a unique integer you assign; you’ll use it to update or cancel the subscription later.
- channel_expiry — subscriptions expire (max one day for free orgs, up to a year for Enterprise). You must renew them.
- events — {Module}.{create|edit|delete}.
- token — your own shared secret. Zoho returns it unchanged in every notification payload, so you can verify the request came from your registered subscription.
- notification_condition — optional filter; fire only when a specific field changes (e.g., Deal Stage).
How to Verify Incoming Notifications
Zoho does not sign webhook payloads with HMAC. Verification is done by comparing the token value in the payload against the secret you registered.
app.post('/webhooks/zoho', express.json(), (req, res) => {
const payload = req.body;
if (payload.token !== process.env.ZOHO_WEBHOOK_SECRET) {
return res.status(401).send('Unauthorized');
}
const { module, operation, resource_uri, ids } = payload;
console.log(`${operation} on ${module}:`, ids);
// Always respond 200 immediately, then process async
res.status(200).send('OK');
queueForProcessing({ module, operation, ids });
});
Advanced tips:
- Respond in under 5 seconds. Zoho retries failed deliveries, but the retry policy is limited. Push the work into a queue.
- The payload contains only record IDs, not full records. You still need a GET to fetch updated data. This is by design as it guarantees you see the current state, not a stale snapshot.
- Subscriptions expire. Build a daily cron that lists your active subscriptions via GET /crm/v8/actions/watch and renews any expiring within 48 hours.
- Use notify_on_related_action: true to catch changes to notes, attachments, and related records. Without it, adding a note to a Lead does not trigger a Lead edit event.
Zoho API Error Handling
HTTP Status Code Reference
| Code | Meaning | What to Do |
|---|---|---|
| 200 | Success | Proceed normally |
| 201 | Created | Check data[].status === ‘success’ per record |
| 202 | Multi-status | Some records succeeded, some failed — inspect each |
| 204 | No content | Valid response for empty queries |
| 400 | Bad request | Fix the request structure or field values |
| 401 | Invalid token | Refresh the access token |
| 403 | Forbidden | Missing scope or the user lacks module permission |
| 404 | Not found | The record ID is wrong, or the record is in the Recycle Bin |
| 413 | Payload too large | Reduce batch size (max 100 records per POST) |
| 429 | Concurrency/credit limit | Backoff and retry |
| 500 | Server error | Retry with backoff |
The 202 Trap
Zoho’s batch insert and update endpoints return HTTP 202 when some records in the batch succeed, and others fail. Integrations that check only the top-level status code will silently lose data. Always inspect every record in the response:
const result = await response.json();
for (const record of result.data) {
if (record.status !== 'success') {
console.error('Record failed:', record.code, record.message, record.details);
await logFailure(record);
}
}
Custom Error Classes
class ZohoAPIError extends Error {
constructor(message, statusCode, details = {}) {
super(message);
this.name = 'ZohoAPIError';
this.statusCode = statusCode;
this.details = details;
}
}
class ZohoRateLimitError extends ZohoAPIError {
constructor() {
super('Zoho concurrency or credit limit exceeded', 429);
this.name = 'ZohoRateLimitError';
}
}
class ZohoAuthError extends ZohoAPIError {
constructor(details) {
super('Zoho authentication failed', 401, details);
this.name = 'ZohoAuthError';
}
}
class ZohoValidationError extends ZohoAPIError {
constructor(recordErrors) {
super('One or more records failed validation', 400, { recordErrors });
this.name = 'ZohoValidationError';
}
}
Zoho REST vs. SDK: Which Should You Use?
Zoho publishes official SDKs for Java, Python, Node.js, PHP, C#, Ruby, TypeScript, JavaScript, and Scala. All are regenerated from the v8 OpenAPI 3.0.0 specification.
| Aspect | Raw REST | Official SDK |
|---|---|---|
| Setup | One HTTP client | Multiple dependencies, config file |
| Auth | You handle refresh flow | Auto-refresh built in |
| Multi-DC | You handle routing | Built in once configured |
| Type safety | None | Full types for v8 |
| Lock-in | None | Couple your code to Zoho’s SDK lifecycle |
| Debuggability | Easy (curl-equivalent) | SDK-specific logging |
Use the SDK for greenfield integrations in a supported language. Use raw REST when you need a language not on the list, when you’re running in a lightweight environment (edge functions, Lambdas with tight cold-start budgets), or when you need fine-grained control over retry and caching.
Advanced: Multi-Org Integrations
If your app will be installed by many Zoho customers, each with their own org, you need to treat tokens, refresh tokens, and api_domain as per-customer state.
Minimal schema:
CREATE TABLE zoho_connections (
user_id UUID PRIMARY KEY,
zoho_location VARCHAR(10) NOT NULL, -- 'us', 'eu', 'in', etc.
accounts_server TEXT NOT NULL, -- 'https://accounts.zoho.eu'
api_domain TEXT NOT NULL, -- 'https://www.zohoapis.eu'
access_token TEXT NOT NULL,
refresh_token TEXT NOT NULL,
access_token_expires_at TIMESTAMPTZ NOT NULL,
scopes TEXT[] NOT NULL,
installed_at TIMESTAMPTZ DEFAULT now()
);
Store tokens encrypted at rest (AWS KMS, GCP KMS, or Vault). Never log access tokens or refresh tokens, but they are credentials, not identifiers. Rotate your Client Secret at least annually, and remember that rotating it invalidates every access token issued under the old secret (refresh tokens continue to work).
2026-Specific Warnings
- v7 is maintenance-only. New features ship to v8 first and often exclusively. If you are starting a new integration today, use v8.
- Zia Assistant API costs vary by plan. AI calls count against a separate quota, not the standard.
credit bucket. Check your edition’s Zia allowance before building production features on top of it. - Connected Workflow APIs changed the recommended automation model. If your integration currently creates hundreds of individual Workflow rules programmatically, consider migrating to Connected Workflows; they scale better and are the path forward.
- Multi-DC is non-optional. Zoho’s European and Indian customer base has grown fast; an integration that only supports zoho.com will fail for a significant fraction of real customers. Build DC handling on day one, not as a retrofit.
Struggling to Scale and Connect Your Zoho Systems Effectively?
As your Zoho ecosystem expands, standard configurations and built-in features often start to fall short. Managing multiple Zoho apps, syncing data across regions, integrating external platforms, or automating complex workflows requires more than basic setup; it demands solid technical architecture and reliable API integrations.
This is where many businesses hit limitations. Without the right foundation, integrations break, data becomes inconsistent, and scaling across teams or regions becomes difficult.
Smart WebTech helps businesses overcome these challenges by building and extending Zoho systems with custom development, API integrations, and automation. From implementing Zoho CRM API v8 with secure OAuth 2.0 flows to designing scalable multi-region architectures, we create solutions that keep your Zoho environment stable, flexible, and efficient.
If your Zoho setup is becoming more complex and needs to scale properly, Smart WebTech can help you do it right.
