Zendesk API Docs: Your First Request
Twenty minutes from nothing to a working request, using the Zendesk API docs and curl. No client library, no framework, and the mistake almost everybody makes on the way.
Step one: get a token
Token authentication is enabled per account, and tokens are created in Admin Center under the API settings. You need admin rights to get there, which is worth knowing before you promise anyone a demo this afternoon.
Create a token, give it a description that says which integration it belongs to, and copy it immediately. Zendesk shows it once. Lose it and you generate another, which is annoying but not fatal.
Put it in an environment variable rather than in a file you might commit.
export ZD_TOKEN="your_token_here"
export ZD_USER="you@acme.com"
export ZD_URL="https://acme.zendesk.com"Replace acme with your own subdomain, the one in the URL your agents log into. That's the single most common thing to get wrong in the first five minutes.
Step two: your first request from the Zendesk API docs
The safest first call asks who you are. It reads nothing sensitive, needs no parameters, and either works or tells you exactly what is broken.
curl -u "$ZD_USER/token:$ZD_TOKEN" "$ZD_URL/api/v2/users/me.json"Note the shape of the username. It's your email address, then a literal /token, then a colon, then the token as the password. Not the email on its own. Not the token on its own.
A success looks roughly like this, heavily trimmed:
{
"user": {
"id": 4417,
"name": "Ada Bell",
"email": "you@acme.com",
"role": "admin"
}
}Your own name and role, wrapped in a user object. Every response in the API is wrapped like this, so you'll be unwrapping for the rest of your life.
Step three: the mistake you're about to make
Most first attempts fail, and there are only a few reasons.
/token suffix and check that token access is enabled in the admin settings, because it can be switched off entirely./api/v2/api/v2/ from pasting a full URL onto a base you already set./api/v2 or a typo in the host.Add -i to curl to see the status line and headers. It turns an opaque failure into an obvious one, and it's the first thing to do rather than the last.
Step four: read something real
Now fetch some tickets. Keep it small.
curl -u "$ZD_USER/token:$ZD_TOKEN" \
"$ZD_URL/api/v2/tickets.json?page[size]=5"You get a tickets array, plus a meta object with has_more and a cursor, plus a links object with a next URL. That is cursor pagination, and following links.next until has_more is false is how you walk a whole list.
Look at what a ticket actually contains. Field values, IDs for the requester and assignee, a description, and no conversation. The description is the first comment and nothing more. Reading the rest is a separate call to the comments endpoint, which catches everybody exactly once. The ticket API guide has the detail.
Pipe the output through a JSON formatter while you explore. Reading a raw response in a terminal is character-building and slow.
Step five: write something, carefully
Creating a ticket is one POST, and you should do it in a sandbox rather than in your live queue.
curl -u "$ZD_USER/token:$ZD_TOKEN" -X POST \
-H "Content-Type: application/json" \
-d '{"ticket":{"subject":"API test","comment":{"body":"Ignore me."}}}' \
"$ZD_URL/api/v2/tickets.json"Two things happen that the docs mention quietly. The ticket is attributed to whoever your credentials belong to, not to a customer, so it looks like you raised it. And it's a completely normal ticket, so triggers fire and your autoresponder goes out. On a live account, to a real address, that is a genuinely embarrassing way to learn.
From here the reference stops being intimidating. You know the base URL, the auth format, the wrapper, the pagination and how errors read. The rest is looking up field names, and a Postman collection makes that part faster.
Frequently asked questions
Is there a Zendesk API tutorial for a first request?
This page is one. Zendesk API getting started needs three things: a subdomain, an API token and a Zendesk API curl example to paste, and the token has to be enabled in the admin settings first.
Where are the Zendesk API docs?
At developer.zendesk.com, split by product: Support, Sell, Chat and the apps framework are separate references. Start from the Support API section, because that's where tickets, users and organizations live.
Where do I get a Zendesk API token?
Admin Center, in the API settings, as an admin. The token is displayed once when created, so copy it straight away.
What is the correct curl auth format?
Basic auth with the username as email/token and the password as the token itself, for example -u "you@acme.com/token:$ZD_TOKEN".
Why do I get "Couldn't authenticate you"?
Usually a malformed username, missing the /token suffix. Also check that token access has not been disabled in the account API settings.
Will my first test ticket email a customer?
It fires triggers like any other ticket, so an autoresponder can go out. Test in a sandbox, and set a requester deliberately rather than letting it default to your integration user.
Do I need a client library to start?
No. Curl is enough to learn the conventions, and the conventions are the hard part. Libraries save typing once you know what you are typing.
Your first API ticket, and the duplicate right behind it
Ticket Merger merges duplicate Zendesk tickets automatically on requester, subject keywords and ticket fields within a time window you choose.
Start free trial14-day free trial. No credit card required.