What we do
Tools
Industries
Department
How we workLet's talk →
Home/Zoho Desk/Zoho Desk API
Zoho Desk developer notes

The Zoho Desk API, From a Rejected First Call to a Sync That Runs All Day

You registered a client in the Zoho API Console, got a token, called /api/v1/tickets, and Desk said no. That's normal. Nearly every first failure comes down to four things, all fixable in minutes. After that, the limits that matter are daily API credits and how many requests run at once.

Four reasons a Zoho Desk request bounces

A working request goes to https://desk.zoho.com/api/v1/ (or your region's domain) with two headers: orgId and Authorization: Zoho-oauthtoken {access_token}.

The data center doesn't match

How you'll know: A token that looks valid is rejected outright.

Fix: Desk runs on separate regional domains: desk.zoho.com, desk.zoho.eu, desk.zoho.in, desk.zoho.com.au, desk.zoho.com.cn. The token has to come from the matching accounts domain too. An EU portal needs accounts.zoho.eu and desk.zoho.eu.

No orgId header

How you'll know: Calls fail on every endpoint except one.

Fix: Every endpoint except /organizations needs the orgId header. Call GET /api/v1/organizations first, which the Desk.basic.READ scope covers, and store the ID.

The token lacks the scope

How you'll know: A SCOPE_MISMATCH error on one kind of call while others work.

Fix: Desk scopes are per resource and action, such as Desk.tickets.READ or Desk.tickets.UPDATE. Scopes are fixed when the grant is issued, so add the missing one, generate a new grant code and exchange it again.

The token is in the wrong place, or expired

How you'll know: INVALID_OAUTH, often an hour after things worked.

Fix: Send it only in the Authorization header with the Zoho-oauthtoken prefix, not Bearer. Access tokens are short-lived, so refresh them from the stored refresh token instead of generating new grants.

Zoho Desk API credits and concurrency by edition

Credits reset every 24 hours. Heavier operations use more credits than simple reads, actions in the Desk interface don't use any, and light agents don't add to the per-agent amount. Your live usage is under Setup, then Developer Space, then APIs.

Edition Daily credits Requests at once
Free 5,000 5, the same as a trial portal.
Express 25,000, plus 100 per agent 10
Standard 50,000, plus 250 per agent 10
Professional 75,000, plus 500 per agent 15
Enterprise, Zoho One, CRM Plus 100,000, plus 1,000 per agent 25

Swap polling for Zoho Desk webhooks

A script that lists tickets every few minutes spends credits on tickets that haven't changed. Webhooks send the change to you instead.

  1. 1

    Open the webhook settings

    Setup Developer Space Webhooks

    How many webhooks you can create depends on your edition, so check the count before planning one per job.

  2. 2

    Pick the events

    Ticket events cover add, update and delete. Update comes in two forms, with or without the previous values. Take the version with previous values when your code needs to know what a status changed from.

  3. 3

    Narrow it to the departments that matter

    Ticket add and update subscriptions can be limited to chosen departments, so a billing integration doesn't receive every sales ticket.

  4. 4

    Keep a scheduled catch-up

    Run a light sync on a schedule that compares recent changes with what the webhook delivered. If your receiver was down when an event fired, the catch-up is what notices the gap.

Reaching the systems Zoho Desk can't see

If your stack is all Zoho, Desk already talks to Zoho CRM, Books and Inventory without code. The API earns its keep at the edges: the accounting system, warehouse tool or CRM that isn't Zoho, which is usually where an agent still copies and pastes. A ticket moved to a refund status can post the refund in the accounting system that owns it and log the result back on the ticket. A new ticket can trigger a lookup of order status or invoice balance outside Zoho, so the answer is on the ticket before an agent opens it.

n-frames writes and runs those integrations: the webhook receiver, the calls into the other system, the token refresh, and a credit budget with an alert before the day's limit. For the wider picture, see Zoho Desk integrations and Zoho Desk automation. The same login flow covers other Zoho products, as on Zoho CRM API.

Zoho Desk API questions

Does Zoho Desk have an API, and where does it live?

Yes. It's a REST API at /api/v1/ on your region's Desk domain, covering tickets, contacts, accounts, agents, departments and more. Authentication is Zoho's OAuth 2.0, set up through the Zoho API Console, and each request also carries your orgId.

Does Zoho Desk support webhooks?

Yes. You set them up under Setup, then Developer Space, then Webhooks, and subscribe to events such as a ticket being added, updated or deleted. The number you can create depends on your edition.

Why does my Zoho Desk API call fail even with a valid token?

Usually one of four things: the token came from a different data center than your portal, the orgId header is missing, the token doesn't carry the scope that call needs (a SCOPE_MISMATCH error), or it was sent with the wrong prefix. The list above walks through each.

Do I need the Zoho Desk API if my whole stack is Zoho?

Often not for routine work, since Desk connects to Zoho CRM, Books and Inventory natively. You need the API when a system outside Zoho is involved, or when you want reporting or logic the built-in connections don't offer.

How many API calls does Zoho Desk allow per day?

Desk counts credits rather than calls. Each edition gets a base amount plus more per agent, from 5,000 a day on Free to 100,000 plus 1,000 per agent on Enterprise, and heavier operations use more credits. When they run out, new requests are refused until the 24-hour reset, unless you buy more.

Where do I find my Zoho Desk orgId?

Call GET /api/v1/organizations with a token that has the Desk.basic.READ scope. It's the one endpoint that doesn't need the orgId header, and it returns the IDs of the portals your user can reach.

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.