The Zendesk API Users Endpoint
The Zendesk API users endpoint is the second resource you learn and the first one you get wrong. Roles, identities and duplicate people all live here.
The Zendesk API users object
Users hang off /api/v2/users. The object is broad, but a handful of fields drive everything.
end-user, agent or admin. This isn't cosmetic. It decides what the account can see and, if you authenticate as them, what your integration can do.Creating and updating
Creation is a POST to /api/v2/users.json with the payload wrapped, as everything is.
{
"user": {
"name": "Ada Bell",
"email": "ada@example.com",
"role": "end-user",
"external_id": "crm-88213"
}
}Updates are a PUT to /api/v2/users/{id}.json, partial, same wrapper. Nothing surprising.
The surprising part is what happens when the email already exists. Zendesk will reject the create, because email addresses are unique across the account. So most integrations shouldn't be calling create at all.
create_or_update
There's an upsert endpoint, and it is the one you want. It matches on email address or on external_id, updates the user if it finds a match and creates them if it doesn't. One call, no lookup first, no race between two workers processing the same person.
The catch worth knowing: matching is exact. ada@example.com and ada.bell@example.com are two people as far as Zendesk is concerned, and if your source system holds both you'll get both. Normalise upstream, because you cannot fix it here.
Identities, or why one user has four emails
A Zendesk user is not one email address. It's a person with a set of identities, each of which can be an email, a phone number, or a social or messaging handle. One of them is primary.
They live under the user: /api/v2/users/{id}/identities.json lists them, and there are endpoints for adding one, making one primary and verifying one. This matters more than it sounds.
When a customer emails from their work address on Monday and their personal address on Tuesday, Zendesk sees two users unless one of those addresses is registered as a secondary identity on the other. Add the alternate address as an identity and the second email attaches to the person you already know about.
Verification is the other half. An unverified identity exists but isn't trusted for authentication, and adding one over the API generally sends a verification email unless you explicitly skip it. During a bulk import, that flag is the difference between a quiet job and several thousand confused customers.
Roles, and the trap in promoting people
The three built-in roles are end-user, agent and admin. Higher plans add custom agent roles with fine-grained permissions, referenced on the user by a role ID, so check what your account has before you build around them.
Two practical notes.
Changing someone from end user to agent consumes an agent seat, which has a billing consequence. An integration that promotes users based on a field in your CRM can quietly cost real money. Guard it.
And going the other way is not symmetric. Downgrading an agent to an end user is possible but their history, assignments and group memberships don't simply evaporate, so plan the tidy-up rather than assuming a role change is the whole job. Light agents, where available, are worth knowing about as the cheaper middle ground.
Searching for people
Two routes, and they behave differently.
The user search endpoint takes a query and matches across name, email and other attributes. Convenient for a "find me anyone called Bell" search box, less good for exact lookups, because it runs against the search index and returns matches rather than a single answer.
The other route is direct lookup by email address or by external_id, which is what most integrations actually need and what almost everybody reaches for search to do instead. It's a different call with different behaviour, and it's the one you'll end up making thousands of times a day.
Either way, cache the result. Resolving the same customer to the same user ID forty times an hour is a waste of a rate limit that you will want later.
Frequently asked questions
How do you update a user or read their identities?
The Zendesk update user API is a PUT on the user, and identities are a sub-resource: Zendesk user identities hold every email and phone number attached to one person. The Zendesk user roles API exposes role and custom role fields on the same object.
How do I create a user with the Zendesk API?
POST to /api/v2/users.json with the payload wrapped in a user object. In practice use the create_or_update endpoint instead, since email addresses must be unique.
Can one Zendesk user have several email addresses?
Yes. A user has identities, one of which is primary. Add alternate addresses as secondary identities so mail from either address attaches to the same person.
What roles can I set over the API?
The built-in end-user, agent and admin roles, plus custom agent roles on plans that include them, referenced by role ID.
Does creating a user send them an email?
Adding or changing an identity can trigger a verification email. There's a flag to skip verification, which you want during bulk imports.
Why did my user create return an error?
Usually a duplicate email address. Emails are unique per account, so a create against an existing address fails where create_or_update would have succeeded.
One person, two emails, two tickets
Ticket Merger merges duplicate tickets in Zendesk using requester, subject keywords and ticket fields inside a time window you define.
Start free trial14-day free trial. No credit card required.