Zendesk Support API Documentation
The Zendesk Support API documentation is large, well written and badly signposted. This is the map: base URL, auth, the resource families you'll touch, and the limits.
Every request starts the same way
One base URL, built from your own subdomain. If your agents log in at acme.zendesk.com, your API lives here.
https://acme.zendesk.com/api/v2/The v2 has been the current version of the Support API for years, so treat it as stable rather than as something you'll be migrating off next quarter. Paths mostly end in .json, which is optional in some places and harmless everywhere, so keep it for consistency.
A first call, to prove your credentials work at all:
curl -u "you@acme.com/token:$ZD_TOKEN" \
https://acme.zendesk.com/api/v2/users/me.jsonThat returns the user your credentials belong to. If it comes back with a name you recognise, everything else in the reference is now reachable. If it doesn't, stop and fix auth before you read another page.
The three ways in
Zendesk supports three authentication styles and the docs present them as equals. They aren't.
email/token as the username and the token as the password. Generated in Admin Center, revocable, and the right choice for anything internal. It's what almost every integration should use.Whichever you pick, create a dedicated integration user rather than borrowing an agent account. You will want to exclude that user from triggers later, and you can only do that cleanly if it belongs to nobody.
The other permission trap: your credentials carry the role of the user behind them. An end user token cannot list tickets it does not own. A 403 on an endpoint that clearly exists is almost always a role problem, not a bug.
The resource families worth knowing
The reference is organised by resource, and there are a lot of them. Realistically you will live in five or six.
Guide, Talk, Chat and the messaging products each have their own reference sections, on different base paths, with different conventions. Don't assume a pattern from Support carries across.
Rate limits, in the only way that matters
Zendesk publishes per-account rate limits that vary by plan, and some endpoints, search and incremental exports especially, have their own tighter allowances on top. Don't hard-code a number from a blog post, including this one. Check the current reference for your plan, then build as though the number is lower than you were told.
What matters more is behaviour when you hit one. You get a 429 and a Retry-After header telling you how long to wait. Honour it. Responses also carry rate limit headers describing your remaining budget, which is worth logging so you can see yourself approaching the ceiling rather than discovering it on a Monday morning.
Exponential backoff with jitter, a cap on retries, and a queue that can pause rather than spin. Three things, and they turn a fragile integration into a boring one.
How to actually use the Zendesk Support API documentation
The reference is a reference, not a tutorial, and reading it front to back is a bad use of an afternoon. Two habits help.
First, work from the JSON format table for a resource before the endpoint list. It tells you which fields are read-only, which are set by the system and which you can write. Half of all "why did my update do nothing" questions are answered there.
Second, prototype in a client rather than in your codebase. A Postman collection for the Zendesk API gets you to a working request faster than a compile loop will, and once the request works you translate it. If you are building in PHP, the Zendesk API in PHP walkthrough covers the client library route instead.
And keep a sandbox. Zendesk offers sandbox environments so you can point an integration at something that is not your live queue. Testing a bulk update against production because the sandbox was fiddly to set up is a decision people make exactly once.
Frequently asked questions
Where do the Zendesk developer docs live?
At developer.zendesk.com. The Zendesk developer docs cover the REST APIs, the apps framework and the theming API, each with its own reference and changelog.
What base URL does the Zendesk Support API documentation give?
It is built from your subdomain: https://yoursubdomain.zendesk.com/api/v2/. There is no shared hostname, so every account has its own base.
Which authentication method should I use?
An API token paired with an email address for internal integrations, OAuth for anything you distribute. Email and password works but breaks under two-factor and should be avoided.
Why am I getting a 403 on a valid endpoint?
Almost always the role of the authenticating user. Credentials carry that user permissions, so an end user or a restricted agent cannot see everything an admin can.
What are the Zendesk API rate limits?
They vary by plan, and search and incremental exports have their own tighter limits. Check the current reference for your account, then handle 429 with the Retry-After header regardless.
Is the v1 API still available?
No. Everything current lives under /api/v2/. Anything you find referencing v1 is old enough that the rest of its advice is probably stale too.
The API is happy to create the same ticket twice
Ticket Merger watches your Zendesk queue and merges duplicates on requester, subject keywords and ticket fields, inside a time window you set.
Start free trial14-day free trial. No credit card required.