# Zoho Desk API Guide: OAuth, Credits, Webhooks and Limits

> Zoho Desk API guide: OAuth setup, daily credits and concurrency per edition, webhooks from Professional, add-on credit prices and how to avoid limits.

_Source: https://professionalstoolkit.com/articles/zoho-desk-api — The Professional's Toolkit · updated November 2026_

---

Zoho Desk ships a full REST API on every edition, Free included, so the real question is how much of it you get. Each organization receives a daily pool of API credits: 5,000 on Free, 25,000 plus 100 per user on Express, 50,000 plus 250 on Standard, 75,000 plus 500 on Professional and 100,000 plus 1,000 on Enterprise [1]. Calls run over OAuth 2.0 with one-hour access tokens. The limit most teams hit first is concurrency, not volume. Our verdict: Standard covers a nightly sync, but anything event-driven belongs on Professional, the first edition with webhooks.


**75,000 + 500** — Daily API credits on Zoho Desk Professional (base plus 500 per user), the first edition with webhooks.



- **5,000** — Daily API credits on the Free plan, with no per-user top-up
- **25** — Concurrent API calls on Enterprise (15 on Professional, 10 on Express and Standard)
- **1 hour** — Lifetime of a Zoho Desk OAuth access token; refresh tokens renew it


## How much API each edition gives you

Credits are counted on a 24-hour cycle in your data center's time zone, and unused credits expire when that 24-hour cycle closes. Concurrency is separate and organization-wide: every OAuth client and token tied to your org ID shares one ceiling. Go above it and the call fails with TOO_MANY_REQUESTS. There is no per-minute cap and no per-token rate limit while you stay under that ceiling, so a well-behaved integration can spend its whole pool in bursts. Light agents add no credits, whatever edition they sit on.

| Edition | Daily API credits | Concurrent calls | Active webhooks |
|---|---|---|---|
| Free | 5,000 | 5 | none |
| Express | 25,000 + 100 per user | 10 | none |
| Standard | 50,000 + 250 per user | 10 | none |
| Professional | 75,000 + 500 per user | 15 | 5 |
| Enterprise | 100,000 + 1,000 per user | 25 | 10 |

For a ten-agent team the pool works out to 52,500 credits a day on Standard, 80,000 on Professional and 110,000 on Enterprise, by our arithmetic. The base matters far more than the per-user top-up. Licenses are priced per agent per month, from Express at $9 billed monthly or $7 billed annually up to Enterprise at $50 billed monthly or $40 billed annually, and every agent must sit on the same edition, so cost grows with headcount ([full pricing breakdown](/articles/zoho-desk-pricing)).

## Step 1: register a client and get your first token

The setup is standard OAuth 2.0, with a few Zoho-specific details that trip up first-time builders: a single-use grant token, an organization header on every call, and a base URL that depends on where your account lives. Zoho supports flows for server, client, mobile, desktop and self-client apps. Work through it in this order:

1. Register the app in the Zoho API Console: a server-based application gets a client ID, client secret and redirect URI, while a script you run yourself can use the Self Client option.
2. Generate a grant token with the scopes you need, such as Desk.tickets.READ, Desk.contacts.WRITE, Desk.search or Desk.events. Each grant token can be exchanged for tokens only once, within the validity you chose.
3. Exchange it for an access token, valid for one hour, and a refresh token you store to renew access.
4. Send every call with an Authorization header and an orgId header.

The access token response includes an api_domain value, and that is the base URL you should call. Zoho's API documentation lists base URLs for ten data centers: US, EU, IN, AU, CN, JP, CA, SA, SG and UAE. The US root is desk.zoho.com/api/v1. A token is bound to one Desk organization, so sending the wrong orgId returns OAUTH_ORG_MISMATCH. When your edition blocks an action, the error is LICENSE_ACCESS_LIMITED instead. Log both separately. They need different fixes.

## Step 2: spend credits on purpose

Not every call costs the same. Fetching one record costs 1 credit, while a list request costs 3 credits within the first 2,000 records of a result set, rising to 5 up to 10,000, 10 up to 50,000, 50 up to 100,000 and 100 beyond that. Moving a record to trash or restoring it costs 6 credits per record, and bulk updates cost 1 credit for every 2 records. List requests return 10 records by default and usually 50 at most, paged with the from and limit parameters. Deep pagination through a large ticket archive is the expensive pattern.

Polling is the classic budget killer. One list call a minute is 1,440 calls a day, or 4,320 credits at 3 credits each by our arithmetic, which eats most of the Free plan's 5,000 before any real work happens. Every response carries two headers that let your code see the meter: X-Rate-Limit-Request-Weight-v3 shows what the call cost, and X-Rate-Limit-Remaining-v3 shows what is left. Once the daily pool is gone, a Retry-After header appears and new requests are denied until the reset, which can stall any automation that depends on them.


> 💡 **Fetch related records in one call:** The include parameter returns details such as the ticket owner and assignee with the ticket itself, and the latestThread API returns a ticket's newest thread directly, saving separate calls and credits.


Credits are spent by external callers only. Integrations, Marketplace extensions, custom apps, SDKs and backend services draw from the pool, while agents working in the web app, the mobile app or Radar spend nothing. Two consumers surprise admins: the Zoho CRM ticket sync and Marketplace extension calls both use credits, whereas Zoho's in-house integrations under Setup do not, Zoho Flow excepted [2]. Zoho may also restrict a portal's calls if it detects unusual behavior, and it emails the support administrator when it does.

## Step 3: let webhooks push events to you

Webhooks replace polling with pushed events. Zoho Desk sends events such as ticket, contact or account creation and updates to a callback URL, and one URL can receive any number of event types. The catch is the edition: Professional allows 5 active webhooks and Enterprise 10, while Free, Express and Standard have none. Your endpoint must answer 200 OK within 5 seconds, or the delivery counts as failed. Returning 410 Gone removes the subscription entirely, which is useful for retiring an endpoint and dangerous if your server returns it by mistake [3].

Messaging has its own events. The IM message webhook fires for every incoming or outgoing instant message across WhatsApp, Instagram, Facebook Messenger and live chat, and session webhooks report states such as opened, assigned, on hold, ended and blocked, on Professional and Enterprise. Extensions can define their own webhooks too. If your extension writes back to Desk through the API, put its ignoreSourceId value in the sourceId header of those calls. Otherwise your own update fires the webhook again and loops. Below Professional, scheduled polling or the Zoho Flow and Zapier connectors, available on Standard and higher, are the realistic options.


> ⚠ **CRM sync spends your API credits:** Zoho Desk's ticket sync with Zoho CRM and every Marketplace extension call draw on the same daily credit pool as your own integrations, so a busy sync can starve them.


## When the pool runs dry: alerts, add-on credits or a bigger edition

Every paid edition has an API dashboard that breaks usage down by Zoho service, application, entity, most-used APIs, IP and user; the Custom Function view starts on Professional. It keeps 90 days of data with a 15-minute delay, and it also appears in the Radar app. The dashboard warns admins at 80% and 90% of the limit, which is your cue to act before automations stop. Plan for it. Logging the remaining-credits header daily gives you the same trend with more detail.

Add-on credits are priced per 1,000 daily credits a month: $4.20 for the first 25,000, $1.80 for the next 75,000, $1.50 for the next 150,000 and $0.75 above 250,000. The super admin of a paid plan requests them by email to support or the account manager, and paid editions can reach 5,000,000 credits a day in total. Ask before the pool runs out, not after. Once the daily credits are gone, every integration on the account waits for the reset together.

The alternative is a higher edition, and the break-even depends on headcount. On annual billing, Professional costs $23 per agent per month and Enterprise $40 per agent per month. The step up adds 25,000 base credits plus 500 more per agent. For six agents, the upgrade comes to $102 a month and yields 28,000 credits, while the same 28,000 as add-on blocks run about $110 a month, by our arithmetic. From seven agents the add-on wins, about $112 against $119. Credits alone rarely justify the move. Concurrency rising from 15 to 25 calls might.


> 💡 **Skip automations on API updates:** A featureFlag setting lets a ticket update bypass the automation engine, so a bulk fix through the API does not set off workflow rules you did not intend.


## Building inside Desk: SDKs, extensions and Zoho MCP

You do not have to call raw HTTP. The Java SDK, currently version 1.3.0 through Zoho's Maven repository, wraps the REST API and refreshes access tokens automatically once your app persists them through its ZohoPersistenceHandler interface. For customer-facing apps, the ASAP SDKs for Android, iOS, Flutter and React Native embed the help center, tickets and community in your app; ASAP needs Standard or higher, and its bot and live chat need Enterprise. A separate mobile SDK for building custom agent apps, Kotlin on Android and CocoaPods on iOS, starts on Professional.

Extensions run inside Desk itself. You build them on Zoho's Sigma platform with server-side Deluge functions, and they reach Desk or outside services through the Invoke API, an authenticated proxy that checks an HMAC SHA256 hash signed with your manifest secret. Public extensions pass a review and can be free or paid; private ones skip review, must be free and install by URL. Public extensions work from Standard, private ones from Professional. Remember that their calls draw on the same daily pool as everything else ([how extensions fit the wider integration picture](/articles/zoho-desk-integrations)).

Zoho MCP is the newest route. It lets you build an MCP server that exposes Desk tools, alongside other Zoho apps, to any MCP-compatible AI agent, with OAuth authorization and user-level permissions. It costs $0 and is included for all Zoho users, but every MCP action counts against Desk's existing API quota and adds no limit of its own [4]. An agent that reads tickets in a loop can drain the pool faster than any script. Watch the meter.


## FAQ

**Can I test Zoho Desk API changes without touching production?**

On Enterprise, yes: it includes up to 3 sandboxes, and the API has endpoints to create and rebuild a sandbox, validate changesets and deploy them to production.

**Do old Zoho Desk authtoken scripts still work?**

No. Zoho Desk deprecated authtokens in favor of Zoho OAuth; a Migration API converts them, and old authtokens are deleted 24 hours after migration. Custom functions move to Connections instead.

**Is there an OpenAPI specification for the Zoho Desk API?**

Yes. Zoho publishes an OpenAPI 3.1.0 specification in JSON on GitHub; it is generic and does not include application-specific business logic.

**Will Zoho change the Desk API under my integration?**

Zoho says it keeps backward compatibility: minor deprecations are announced on its forum with a transition period, and only major interface changes alter the version number in the URL.


## The bottom line

The Zoho Desk API is mature and well documented, and on every paid edition it gives a small team far more credits than ordinary syncs consume. The real gates are elsewhere: webhooks start on Professional, concurrency stays at 10 calls or fewer below Professional, and every CRM sync, extension and MCP agent quietly shares one daily pool. Choose Standard if your integration runs on a schedule. Choose Professional if it must react in seconds. Reach for Enterprise only when you need 25 concurrent calls, not just more credits.



## Sources

[1] Zoho Desk API: Zoho Desk API Documentation — https://desk.zoho.com/DeskAPIDocument (2026-11)
[2] Zoho Desk help: Working with API Credits — https://help.zoho.com/portal/en/kb/desk/developer-space/apidashboard/articles/working-with-api-credits (2026-11)
[3] Zoho Desk help: IM Message Add Webhook — https://help.zoho.com/portal/en/kb/desk/support-channels/instant-messaging/webhooks/articles/im-message-add-webhook (2026-11)
[4] Pricing — https://www.zoho.com/mcp/pricing.html (2026-11)
[5] Zoho Desk pricing page — https://www.zoho.com/desk/pricing.html
[6] Zoho Desk help center — https://help.zoho.com/portal/en/kb/desk
[7] Zoho Terms of Service — https://www.zoho.com/terms.html
[8] Zoho Desk plan comparison — https://www.zoho.com/desk/pricing-comparison.html