Zendesk

A Zendesk account over the Support API a helpdesk integration actually uses: tickets through the whole status machine, public and private comments, requesters created implicitly from an email address, users and organizations, groups and the assignment rules between them, search over Zendesk’s query grammar, macros, derived ticket metrics and incremental exports. Zendesk publishes no first-class Python client, so the conformance suite pins Zendesk’s own OpenAPI document for the Support API and validates every response against it. Slug: zendesk

Three things a twin of this API has to get right

Every response is wrapped in a named key — {"ticket": …}, never a bare object — so a twin answering bare objects fails a caller on its first read. Every identifier is an integer: 35436, not "35436", and every relation is an integer foreign key. And there are three error envelopes, all real and all branched on separately:

Failure	Status	Envelope
Record validation	`422`	`{"error": "RecordInvalid", "description": …, "details": {…}}` — `error` is a string
Malformed parameter	`400`	`{"error": {"title": "Invalid attribute", "message": …}}` — `error` is an object
Pagination and throttles	`400`/`429`	`{"errors": [{"code": …, "title": …}]}` — an array

That inconsistency is Zendesk’s, and reproducing it is the point: a client written against the real API has branches for all three, and a twin that normalised them would let a caller ship code that crashes on the shape it did not see.

Two pagination mechanisms, both live

Zendesk is mid-migration from offset to cursor pagination and callers use both, on the same endpoints. page[size] opts a request into cursor pagination — meta.has_more, meta.after_cursor, links.next — and its absence means offset pagination, with next_page, previous_page and count. Offset is capped at 100 pages and 10,000 records, which the twin enforces with Zendesk’s own error rather than truncating silently, because that cap is the exact wall a caller hits in production. Every links.next and every url points at the container’s own host, so a paginating client cannot walk out of the sandbox.

What it models

Area	Modelled
The account	An owner who is an admin, two agents in two different groups, three end users, two organizations, a default ticket form and the fields on it — including an order-number text field and a refund-reason dropdown — plus four tickets across the status range, one of them solved long enough ago that advancing the sandbox closes it
Authentication	Both credentials Zendesk takes: an API token over HTTP basic as `you@example.com/token`, and an OAuth bearer token. The missing `/token` suffix, password basic authentication, an unknown token and a suspended identity are all refused with Zendesk’s one `401` body. Scopes gate the bearer presentation only, because an API token carries its user’s whole role
Roles	The role gate that is the most common real Zendesk integration failure after rate limits: an end-user credential is `403` on the agent surface and still answers `users/me`, and light agents are agents carrying a `custom_role_id`, exactly as Zendesk models them
Rate limits	Per-endpoint budgets rather than one bucket — the account’s plan-based per-minute limit, `tickets-index`, `tickets-update` (including 30 per ten minutes per identity per ticket), `search-index`, the exports’ ten a minute, and the user-update budgets — with `X-Rate-Limit`, the newer `ratelimit-` trio, the per-endpoint `Zendesk-RateLimit-` headers, and a `429` carrying a truthful `Retry-After`
Tickets	Create, retrieve, update and list; the status machine with `solved` back to `open` allowed and everything out of `closed` refused; `description` set once from the first comment; implicit requester creation from an inline email address; `submitter_id` deciding who authored that comment; tags as a set with `additional_tags` and `remove_tags`; `custom_fields` and `fields` as two names for one array; and `external_id` left non-unique because Zendesk leaves it non-unique
Closed tickets	Immutable, with the follow-up that is the only correct recovery: `via_followup_source_id` produces a new ticket whose id appears in the closed one’s `followup_ids`
Comments	Added through a ticket update, public or private, attributable to somebody other than the caller, with the ticket’s description as the first comment and cursor pagination over the rest
Users and organizations	Creation with Zendesk’s own default of end user, the duplicate-email `422` naming the field, `create_or_update` resolving `external_id` before `email` and case-insensitively, organization membership, and an organization’s tickets being the ones its members requested
Groups	Groups and memberships, and the refusal when a ticket is assigned to an agent outside its group — plus the refusals for an end user, a suspended agent and a group that does not exist
Search	Zendesk’s grammar over the subset the twin models, a heterogeneous `results` array with `result_type`, its own error format, its own rate limit, offset-only paging, and the thousand-result ceiling that is a `422` rather than an empty page
Bulk jobs	`update_many` and `create_many` answering a `queued` job that has not happened yet, the `queued` → `working` → `completed` lifecycle through `advance`, per-record results, partial failure against the one bad record, and the hundred-record ceiling
Macros, metrics, exports	Applying a macro, with the preview that answers what would change without changing it; ticket metrics derived from the comment and status history so they cannot disagree with it; satisfaction ratings only the requester may leave; and the incremental export with its `end_of_stream` and its refusal to return the most recent minute

Advancing the sandbox does three things, because three things in a helpdesk age: a solved ticket becomes closed once the account’s close window has passed — which no API call can trigger, and which is why advance exists — a queued bulk job moves towards completed, and an unanswered ticket crosses its first-reply target.

Scenarios

busy-helpdesk, wismo-queue, closed-ticket, sla-breached, end-user-token, rate-limited, pending-bulk-job.

Not modelled

Help Center and Guide, Talk and Chat, Sunshine Conversations and messaging, Side Conversations, Explore and reporting, triggers and automations, SLA policy evaluation (the twin models one first-reply target so a breach is reachable, not a policy engine), the Apps framework, webhooks, custom objects, Sell, attachments and uploads, views, and the admin APIs beyond what the sandbox’s own directives need. The Support API has no dated releases, so the twin’s behaviour is pinned to the OpenAPI document’s version and to the date that document and the API reference were read. No live Zendesk account was available when it was built — the trial locks after fourteen days, which is a large part of why this twin exists — so its README lists every place a live account would settle something the twin had to decide, including what Zendesk does when a ticket is assigned to an agent outside its group. A route Zendesk has and the twin has not built answers a 501 carrying a value Zendesk never sends, rather than RecordNotFound, which would read as missing data and send a caller away.

Getting Started

Concepts

Interfaces

Three things a twin of this API has to get right

What it models

Scenarios

Not modelled

​Three things a twin of this API has to get right

​Two pagination mechanisms, both live

​What it models

​Scenarios

​Not modelled

Three things a twin of this API has to get right

Two pagination mechanisms, both live

What it models

Scenarios

Not modelled