READING Complete Zoho API Guide: From Setup to Integrations
On This Page

    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.

    Keval Kothari Founder & CEO

    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:

    CategoryProduct APIsTypical Use
    Sales & MarketingCRM, Bigin, Campaigns, Commerce, SalesIQ, Bookings, SignLead capture, pipeline automation, marketing ops
    Customer ServiceDesk, AssistTicketing, support automation, and remote sessions
    FinanceBooks, Invoice, Inventory, Expense, BillingAccounting sync, subscription billing, and stock control
    Human ResourcesPeople, RecruitHRIS sync, ATS integration
    CollaborationMail, Cliq, Projects, Sprints, WorkDrive, Writer, Sheet, MeetingProductivity integrations, document automation
    Business IntelligenceAnalyticsReporting, embedded dashboards
    Custom SolutionsCreator, CatalystLow-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

    RegionAccounts URL (OAuth)API Domain (Data)
    United Stateshttps://accounts.zoho.comhttps://www.zohoapis.com
    European Unionhttps://accounts.zoho.euhttps://www.zohoapis.eu
    Indiahttps://accounts.zoho.inhttps://www.zohoapis.in
    Australiahttps://accounts.zoho.com.auhttps://www.zohoapis.com.au
    Japanhttps://accounts.zoho.jphttps://www.zohoapis.jp
    Chinahttps://accounts.zoho.com.cnhttps://www.zohoapis.com.cn
    Saudi Arabiahttps://accounts.zoho.sahttps://www.zohoapis.sa
    Canadahttps://accounts.zohocloud.cahttps://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.

    1. Log in to api-console.zoho.com using the correct regional console for your org.
    2. Click Add Client and choose Self Client.
    3. Copy the generated Client ID and Client Secret.
    4. Open the Generate Code tab, enter the scopes you need (comma-separated), select a validity of up to 10 minutes, and pick the organization.
    5. 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.

    1. In the API console, click Add Client and choose Server-based Applications.
    2. Enter your app name, homepage URL, and authorized redirect URI (must match exactly at runtime, including trailing slash).
    3. Copy the Client ID and Client Secret.
    4. 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:

    ScopeWhat it Unlocks
    ZohoCRM.modules.leads.READRead Leads only
    ZohoCRM.modules.leads.ALLFull CRUD on Leads
    ZohoCRM.modules.ALLFull CRUD on every module
    ZohoCRM.settings.READRead all settings metadata
    ZohoCRM.bulk.ALLBulk read and bulk write
    ZohoCRM.notifications.ALLManage webhook subscriptions
    ZohoCRM.coql.READRun COQL queries
    ZohoBooks.fullaccess.allFull access to Zoho Books
    ZohoDesk.tickets.ALLFull 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:

    1. Redirect the user to Zoho for authorization
    2. Zoho redirects back with a code, location, and accounts-server
    3. Exchange the code at the returned accounts-server for access and refresh tokens
    4. 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.

    CategoryPurpose
    Metadata APIsFetch modules, fields, layouts, custom views, and related lists
    Core APIsCRUD on records within any module
    Composite APICombine up to 5 API calls in a single request
    Bulk APIsAsync read/write for large datasets
    Notification APIsWebhooks 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

    MethodActionExample
    GETRetrieve records or metadataFetch Leads, Deals, or field definitions
    POSTCreate recordsInsert new Leads; run Upsert
    PUTUpdate recordsChange Lead status or merge
    DELETEDelete 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)

    PlanBase CreditsPer UserMax
    Free5,000—5,000
    Standard / Starter50,000+250/user100,000
    Professional50,000+500/user3,000,000
    Enterprise / Zoho One50,000+1,000/user5,000,000
    Ultimate / CRM Plus50,000+2,000/userUnlimited


    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:

    OperationCredits
    Standard GET / POST / PUT / DELETE1
    COQL query1
    Composite request1 per sub-request
    Convert Lead5
    Send Mail20
    Bulk Read Initialize50
    Bulk Write Initialize500

    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:

    PlanMax Concurrent Calls
    Free5
    Standard / Starter10
    Professional15
    Enterprise / Zoho One20
    Ultimate / CRM Plus25

    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&amp;per_page=200&amp;page_token=${pageToken}`
          : `${apiDomain}/crm/v8/Leads?fields=Last_Name,Email&amp;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.

    RELATED:
    Explore how we helped a client automate Shopify and Zoho workflows with a custom API integration solution.
    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

    CodeMeaningWhat to Do
    200SuccessProceed normally
    201CreatedCheck data[].status === ‘success’ per record
    202Multi-statusSome records succeeded, some failed — inspect each
    204No contentValid response for empty queries
    400Bad requestFix the request structure or field values
    401Invalid tokenRefresh the access token
    403ForbiddenMissing scope or the user lacks module permission
    404Not foundThe record ID is wrong, or the record is in the Recycle Bin
    413Payload too largeReduce batch size (max 100 records per POST)
    429Concurrency/credit limitBackoff and retry
    500Server errorRetry 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.

    AspectRaw RESTOfficial SDK
    SetupOne HTTP clientMultiple dependencies, config file
    AuthYou handle refresh flowAuto-refresh built in
    Multi-DCYou handle routingBuilt in once configured
    Type safetyNoneFull types for v8
    Lock-inNoneCouple your code to Zoho’s SDK lifecycle
    DebuggabilityEasy (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.

    Connect with Smart WebTech to get started.