Where to start with the Zendesk API

The API reads and writes almost everything the interface does. Two numbers decide whether your integration survives real volume, and both depend on your plan.

The API reads and writes almost everything: tickets, users, organisations, fields, configuration. Anything the interface does, and some things it does not. Two numbers decide whether your integration survives contact with real volume, and both depend on your plan.

Know your rate limit before you write anything

Exceed it and the API answers 429 Too Many Requests. The Retry-After header says how many seconds to wait, and X-Rate-Limit reports your account's limit. Handle the 429 and honour Retry-After: an integration that ignores this works perfectly in testing and fails on your busiest morning.

Use cursor pagination, not offset

Offset pagination with per_page and page is capped at the first 100 pages and 10,000 resources, a limit in force since 15 August 2023. Anything that might grow past that has to use cursor pagination.

Cursor pagination uses page[size] and page[after], with most endpoints allowing at most 100 records per page. Keep requesting until meta[has_more] is false. On offset, you stop when next_page is null.

Use a service account

Not somebody's personal credentials. When that person leaves and their account is deactivated, every integration using it stops, usually on the day they leave. That breaks the integration, and a dedicated account avoids it entirely.

Give it the narrowest role that works, too. An integration that reads tickets does not need admin, and scoping it means a mistake or a leaked token cannot reach further than the job requires.

Try configuration first, genuinely

Triggers, webhooks and fields cover a great deal. Code has to be maintained by somebody who understands it, and that person will eventually change jobs.

When you do build, test in a sandbox rather than against live tickets, and log what the integration does on your side. When something changes tickets unexpectedly, that log is how you tell a person from an integration.

Write down what it does

What it touches, why it exists, who owns it, which account it uses, and what its rate-limit behaviour is. That note is what makes it maintainable, and it is the thing nobody writes.

See also

• Extending Zendesk: the options in a row
• When you need an app and when a webhook is enough
• What a sandbox is and what it is for