Returns the trigger category with the specified ID.

Updates the trigger category with the specified ID.

Lists all triggers for the current account.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.

Allowed For

• Agents

Lists all active triggers.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Sideloads

The following sideloads are supported:

Returns the definitions of the actions a trigger can perform and the
definitions of the conditions under which a trigger can execute. The
definition of the action includes a title (“Status”), a type (“list”), and
possible values. The definition of the condition includes the same fields
as well as the possible operators.

For a list of supported actions, see the Actions reference
For a list of supported conditions, see the Conditions reference

Allowed For

• Agents

Deletes the triggers corresponding to the provided comma-separated list of IDs.

Allowed For

• Agents

Request Parameters

The DELETE request takes one parameter, an ids object that lists the
triggers to delete.

Example request

{
  "ids": "25,23,27,22"
}

Alters the firing order of triggers in the account. See
Reordering and sorting triggers
in the Zendesk Help Center. The firing order is set in a trigger_ids array in the request body.

You must include every trigger id in your account to reorder the triggers. If not, the endpoint will return 404 Forbidden.

Reordering triggers via the API is not permitted if you have more than one trigger category. If there is more than one
trigger category, the endpoint will return a LimitOneCategory error.

Allowed For

• Agents

Pagination

• Offset pagination only

See Using Offset Pagination.

Allowed For

• Agents

Sideloads

The following sideloads are supported. For more information, see Side-loading.

Filter

Use the filter query parameter to filter a trigger search by one or more attributes. For example, the following filter argument filters triggers by the description attribute:

{
  "json": {
    "description": "Close a ticket"
  }
}

Updates the position or the active status of multiple triggers. Any additional properties are ignored.

Allowed For

• Agents

Request Parameters

The PUT request expects a triggers object that lists the triggers to update.

Each trigger may have the following properties:

Example Request

{
  "triggers": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}

Allowed For

• Agents

Allowed For

• Agents

The Via Type value is a number instead of a text string. See Via types reference for the keys.

Allowed For

• Agents

Note

Updating a condition or action updates both the conditions and actions arrays,
clearing all existing values of both arrays. Include all your conditions
and actions when updating any condition or action.

List the revisions associated with a trigger. Trigger revision history is only available on Enterprise plans.

Allowed For

• Agents

Sideloads

The following sideloads are supported:

Pagination

This endpoint uses cursor-based pagination. The records are ordered in
descending order by the created_at timestamp, then by id on duplicate
created_at values.

The cursor parameter is a non-human-readable argument you can use to move
forward or backward in time.

Each JSON response will contain the following attributes to help you get
more results:

• after_url requests more recent results
• before_url requests older results
• after_cursor is the cursor to build the request yourself
• before_cursor is the cursor to build the request yourself

The properties are null if no more records are available.

You can request a maximum of 1000 records using the limit parameter. If
no limit parameter is supplied, it will default to 1,000.

Fetches a revision associated with a trigger. Trigger revision history is only available on Enterprise plans.

Allowed For

• Agents

Sideloads

The following sideloads are supported:

Returns a list of custom user fields in your account. Fields are returned in the order that you specify in your user fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each User Field to the values returned under the user_fields attribute on the User resource.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Creates any of the following custom field types:

• text (default when no “type” is specified)
• textarea
• checkbox
• date
• integer
• decimal
• regexp
• dropdown
• lookup

See About custom field types in Zendesk help.

Allowed For

• Admins

Allowed For

• Admins

Allowed for

• Admins

Allowed for

• Agents

Updating a Dropdown (Tagger) Field

Dropdown fields return an array of custom_field_options which specify the name, value and order of the list of dropdown options.
Understand the following behavior when updating a dropdown field:

• All options must be passed on update. Options that are not passed will be removed. As a result, these values will be removed from any organizations.
• To create a new option, pass a null id along with name and value.
• To update an existing option, pass its id along with name and value.
• To re-order an option, reposition it in the custom_field_options array relative to the other options.
• To remove an option, omit it from the list of options upon update.

Example Request

curl https://{subdomain}.zendesk.com/api/v2/user_fields/{user_field_id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"user_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 2", "value": "option_3"}]}}' \
  -v -u {email_address}:{password}

Allowed for

• Admins

Returns a list of custom user field options for the given dropdown user field.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Creates a new option or updates an existing option for the given drop-down user field.

To update an option, include the id of the option in the custom_field_option object. Example: {"custom_field_option": {"id": 10002, "name": "Pineapples", ... }. If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created.

Response

Returns one of the following status codes:

• 200 with Location: /api/v2/user_fields/{user_field_id}/options.json if the user field option already exists in the database
• 201 with Location: /api/v2/user_fields/{user_field_id}/options.json if the user field option is new

Allowed For

• Admins

Allowed for

• Admins

Allowed for

• Agents

Returns a list of identities for the given user.

Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only list email and phone number identities.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents
• Verified end users

Adds an identity to a user’s profile. An agent can add an identity to any user profile.

Supported identity types:

To create an identity without sending out a verification email, include a "skip_verify_email": true property.

Allowed For

• Agents

Deletes the identity for a given user.
In certain cases, a phone number associated with an identity is still visible on the user profile after the identity has been deleted via API. You can remove the phone number from the user profile by updating the phone attribute of the user to an empty string. See Update User via API for details and examples.

Allowed For

• Agents

Shows the identity with the given id for a given user.

Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users can only view email or phone number identity.

Allowed For

• Agents
• Verified end users

This endpoint allows you to:

• Set the specified identity as verified (but you cannot unverify a verified identity)
• Update the value property of the specified identity

You can’t change an identity’s primary attribute with this endpoint. You must use the Make Identity Primary endpoint instead.

Allowed For

• Agents

Sets the specified identity as primary. To change other attributes, use the Update Identity endpoint. This is a collection-level operation and the correct behavior for an API client is to subsequently reload the entire collection.

The first endpoint is the preferred option if authenticating as an agent. If authenticating as an end user, you can only use the second endpoint. In addition, an end user can only make an email identity primary if the email is verified.

Allowed For

• Agents
• Verified end users

Sends the user a verification email with a link to verify ownership of the email address.

Allowed For

• Agents

Sets the specified identity as verified.

For security reasons, you can’t use this endpoint to update the email identity of the account owner. To verify the person’s identity, send a verification email. See Verifying the account owner’s email address in Zendesk help.

Allowed For

• Agents

An admin can set a user’s password only if the setting is enabled in Zendesk Support under Settings > Security > Global. The setting is off by default. Only the account owner can access and change this setting.

API token authentication is not permitted on this endpoint.

Allowed For

• Admins

You can only change your own password. Nobody can change the password of another user because it requires knowing the user’s existing password. However, an admin can set a new password for another user without knowing the existing password. See Set a User’s Password above.

API token authentication is not permitted on this endpoint.

Allowed For

• Agents
• End Users

Allowed For

• Agents
• End Users

Returns deleted users, including permanently deleted users.

If the results contains permanently deleted users, the users’ properties
that normally contain personal data, such as email and phone,
are null. The name property is “Permanently Deleted User”.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Returns an approximate count of deleted users, including permanently deleted users. If the count exceeds 100,000, it is updated every 24 hours.

The response includes a refreshed_at property in a count object that contains a timestamp indicating when the count was last updated.

Note: When the count exceeds 100,000, count[refreshed_at] may occasionally be null.
This indicates that the count is being updated in the background, and count[value] is limited to 100,000 until the update is complete.

Allowed For

• Agents

Before permanently deleting a user, you must delete the user first. See Delete User.

WARNING: Permanently deleting a user deletes all of their information. This information is not recoverable.

Permanent user deletion rate limit

You can permanently delete 700 users every 10 minutes.
The rate limiting mechanism behaves as described in
Rates Limits in the API introduction.
Zendesk recommends that you obey the Retry-After header values.

Allowed For

• Admins and agents in custom roles with permission to manage end users or team members

Returns users that have been deleted but not permanently yet. See Permanently Delete User.

Allowed For:

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins, Agents and Light Agents

Returns an array of users whose name starts with the value specified in the name parameter.
It only returns users with no foreign identities.

Allowed For

• Agents

Returns an approximate count of users. If the count exceeds 100,000, it is updated every 24 hours.

The response includes a refreshed_at property in a count object that contains a timestamp indicating when the count was last updated.

Note: When the count exceeds 100,000, the refreshed_at property may occasionally be null.
This indicates that the count is being updated in the background. The count object’s value property is limited to 100,000 until the update is complete.

Allowed For

• Admins, Agents and Light Agents

Accepts an array of up to 100 user objects.

Note: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner must contact Zendesk Customer Support to enable the imports. A 403 Forbidden
error is returned if data imports are not enabled.

Allowed For

• Admins and agents in custom roles with permission to manage end users or team members

Specifying an organization

You can assign a user to an existing organization by setting an
organization_id property in the user object.

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job’s completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Creates a user if the user does not already exist, or updates an existing user
identified by e-mail address or external ID.

If you don’t specify a role parameter, the new user is assigned the role of end user.

If you need to create users without sending out a verification email, include a "skip_verify_email": true property in the body.

External ID Case Sensitivity

When providing an external id to identify an existing user to update, the search for the user record is not case sensitive.

However, if an existing user is found, the system will update the user’s external id to match the case of the external id used to find the user.

Response Status Code

• If the user exists in Zendesk, a successful request returns a 200 status code with “Location: /api/v2/users/{user_id}.json”.
• If the user does not exist in Zendesk, a successful request returns a 201 status code with “Location: /api/v2/users/{new_user_id}.json”.

Allowed For

• Admins and agents in custom roles with permission to manage end users or team members

Accepts an array of up to 100 user objects. For each user, the user is created if it does not
already exist, or the existing user is updated.

Note: To protect the data in your Zendesk account, bulk user imports are not enabled by default in Zendesk accounts. The account owner must contact Zendesk Customer Support to enable the imports. A 403 Forbidden
error is returned if data imports are not enabled.

Each individual user object can identify an existing user by email or by external_id.

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job’s completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Allowed For

• Admins and agents in custom roles with permission to manage end users or team members

Accepts a comma-separated list of up to 100 user ids.

The request takes an ids or an external_ids query parameter.

Allowed for

• Admins and agents in custom roles with permission to manage end users or team members

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job’s completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Accepts a comma-separated list of up to 100 user ids.

Allowed For:

• Admins

The endpoint returns user information and an authenticity_token.

Allowed For

• Anonymous users

Authenticity Token

Zendesk API calls made by end users from a Zendesk help center must include authenticity_token in the X-CSRF-Token HTTP header. This helps prevent cross-site request forgery (CSRF) attacks.

For an example using an authenticity token, see the AJAX request in the Upgrading from Templating API v1 documentation.