Zendesk Support API Users

The Zendesk Support API allows you to manage users within the Zendesk platform. This guide covers the core operations related to user management, including creating, updating, retrieving, and deleting users, as well as managing user identities and roles.

What can you do with Users in the Zendesk Support API?

The most common operations people perform on users using the Zendesk Support API.

Action	HTTP Method	Endpoint
List Users	`GET`	`/api/v2/users`
Create a User	`POST`	`/api/v2/users`
Retrieve a User	`GET`	`/api/v2/users/{user_id}`
Update a User	`PUT`	`/api/v2/users/{user_id}`
Delete a User	`DELETE`	`/api/v2/users/{user_id}`

Users in Zendesk Support represent individuals who interact with your support system, including agents, admins, and end-users.

Users are primarily identified by their unique ID, email address, or external ID.

To create a user, you need to provide at least a name and email address. Additional optional fields include role, organization_id, and custom fields.

Users can be searched using the `query` parameter, which supports Zendesk search syntax. You can search by name, email, notes, or phone. Example: `query="jdoe"`.

Properties of a User

The properties section outlines the key attributes of a User object in the Zendesk Support API. Understanding these properties is crucial for effectively managing users. Show all properties Only show essential properties

Field Name	Type	Short Description
id	integer	Automatically assigned when the user is created
name	string	The user's name
email	string	The user's primary email address
role	string	The user's role. Possible values are "end-user", "agent", or "admin"
created_at	datetime	The time the user was created
updated_at	datetime	The time of the last update of the user
organization_id	integer	The id of the user's organization
locale	string	The user's locale
time_zone	string	The user's time zone
active	boolean	False if the user has been deleted
alias	string	An alias displayed to end users
chat_only	boolean	Whether or not the user is a chat-only agent
custom_role_id	integer	A custom role if the user is an agent on the Enterprise plan or above
default_group_id	integer	The id of the user's default group
details	string	Any details you want to store about the user, such as an address
external_id	string	A unique identifier from another system
iana_time_zone	string	The time zone for the user
last_login_at	datetime	Last time the user signed in to Zendesk Support
locale_id	integer	The user's language identifier
moderator	boolean	Designates whether the user has forum moderation capabilities
notes	string	Any notes you want to store about the user
only_private_comments	boolean	True if the user can only create private comments
phone	string	The user's primary phone number
photo	object	The user's profile picture represented as an Attachment object
remote_photo_url	string	A URL pointing to the user's profile picture
restricted_agent	boolean	If the agent has any restrictions
role_type	integer	The user's role id
shared	boolean	If the user is shared from a different Zendesk Support instance
shared_agent	boolean	If the user is a shared agent from a different Zendesk Support instance
shared_phone_number	boolean	Whether the phone number is shared or not
signature	string	The user's signature
suspended	boolean	If the agent is suspended
tags	array	The user's tags
ticket_restriction	string	Specifies which tickets the user has access to
two_factor_auth_enabled	boolean	If two factor authentication is enabled
url	string	The user's API url
user_fields	object	Values of custom fields in the user's profile
verified	boolean	Any of the user's identities is verified

Show all properties

Filtering and Query Parameters

The Zendesk Support API provides several filtering options to refine user queries.

Parameter	Type	Description	Example
`role`	string	Filters the results by role. Possible values are "end-user", "agent", or "admin".	`role=agent`
`external_id`	string	List users by external id. External id has to be unique for each user under the same account.	`external_id=abc124`

What to watch out for

Here are some common pitfalls and important considerations when working with the Users API.

Immutable Fields

Some fields like id and created_at are immutable and cannot be changed once set.

Email Verification

When creating a user, if the primary email address is not verified, the secondary email address is used.

Role Restrictions

Certain operations are restricted based on user roles. For instance, only admins can delete users.

Rate Limits

Be mindful of API rate limits, especially when performing bulk operations like user creation or deletion.

Frequently Asked Questions

Here are some frequently asked questions about the Zendesk Support Users API and their solutions.

How do I find a user by email in the Zendesk Support API?

You can use the query parameter in the /api/v2/users/search endpoint to find a user by email. For example, query="email:user@example.com".

What happens when I update a user's email in Zendesk Support?

When updating a user's email, the new email is added as a secondary email if the primary email is not verified. To change the primary email, use the Make Identity Primary endpoint.

Can I delete a user that has tickets in Zendesk Support?

Yes, you can delete a user even if they have tickets. However, be aware that deleting a user is irreversible and will also delete their associated records.

What's the difference between 'role' and 'role_type' in Zendesk Support?

The role field specifies the user's general role (e.g., 'agent', 'admin'), while role_type provides more granular role information, such as specific agent types.

How do I handle user identity verification in Zendesk Support?

User identity verification can be managed using the /api/v2/users/{user_id}/identities endpoints. You can create, update, and verify identities using these endpoints.