Trigger a workflow execution every time a new ticket is created in Zendesk.

Retrieves an array of custom object records that have a field value that matches the value specified in the name parameter.

Pagination

• Cursor pagination only.
• Returns the first 10,000 records sorted by relevancy with page limits.

Allowed For

• Agents

Returns an array of organizations whose name starts with the value specified in the name parameter.

Pagination

• Offset pagination only

See Using Offset Pagination.

Allowed For

• Agents

Returns tickets whose type is "problem" and whose subject contains the string specified in the text parameter.

You can specify the text parameter in the request body rather than the query string. Example:

{"text": "fire"}

Allowed For

• Agents

Returns an array of registered and recent tag names that start with the characters specified in the name query parameter. You must specify at least 2 characters.

Pagination

• Offset pagination only

See Using Offset Pagination.

Allowed For

• 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

Creates a job that performs a batch operation for the given ticket trigger categories.

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

Note: You might be restricted from deleting some default automations. If included in a bulk deletion, the unrestricted automations will be deleted.

Allowed For

• Agents

Request Parameters

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

Example request

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

Deletes all the sessions for a user.

Allowed For

• Admins, Agents, End users

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

Allowed For

• Admins
• Agents with permission to delete tickets

Agent delete permissions are set in Support. See Deleting tickets in the Support Help Center.

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.

Deletes the views corresponding to the provided list of IDs.

Allowed For

• Agents

Permanently deletes up to 100 soft-deleted tickets. See Soft delete in the Zendesk GDPR docs. To soft delete tickets, use the Bulk Delete Tickets endpoint.

This endpoint accepts a comma-separated list of up to 100 ticket ids. It enqueues a ticket deletion job and returns a payload with the jobs status.

If one ticket fails to be deleted, the endpoint still attempts to delete the others. If the job succeeds, the tickets that were successfully deleted are permanently deleted. This operation can't be undone.

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 completio

Allowed For

• Agents

Adds, replaces or removes multiple attributes for up to 100 agents.

Allowed For

• Admins
• Agents in custom role with permission to manage skills

Available Parameters

The request takes a data object with the following properties:

Updates the default values for many custom ticket statuses at once.

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.

Allowed For

• Agents
• End Users

Returns a JSON object determining whether a host mapping is valid for a given subdomain.

Allowed for

• Admins

Returns a JSON object determining whether a host mapping is valid for the given brand.

Allowed for

• Admins

Allowed for

• Admins

Allowed For

• Admins

Returns an approximate count of ticket activities in the last 30 days affecting the agent making the request. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates 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

Returns an approximate count of audits for a specified ticket. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates when the count was last updated.

Note: If the total number of audits for a ticket exceeds 100,000, this endpoint returns a count of 100,000 with a count[refreshed_at] value of null. This value is cached for 24 hours, during which any requests returns the same count and timestamp. After 24 hours, the endpoint temporarily shows the same count again before providing an updated total.

Allowed for

• Agents

Returns a total count of records for a specific custom object as well as the time the count was refreshed.

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

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

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

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

Allowed For

• Admins
• Agents

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

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

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 and the value property of the count object is limited to 100,000 until the update is complete.

Allowed For

• Agents

Returns an approximate count of satisfaction ratings in the account. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates 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

• Admins

Returns the number of items matching the query rather than the items. The search string works the same as a regular search.

Allowed For

• Agents

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

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

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

Allowed For

• Agents

Returns an approximate count of the comments added to the ticket. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates 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

Returns an approximate count of system and custom ticket fields in the account. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates 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

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

ccd lists tickets that the specified user is cc'd on.

The count[refreshed_at] property is a timestamp that indicates 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

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

Returns an approximate count of shared and personal views available to the current user. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates 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

Creates an approval request that is attached to a ticket. The request must include all of the following information:

• A subject and message for the approval
• A ticket the request should be associated with
• A workflow instance id for the request
• An assignee that will act as an approver

Allowed For

• Agents

Creates an approval workflow instance attached to a ticket. The request must include a name for the workflow and a ticket id to associate with the workflow instance.

Allowed For

• Agents

Allows an attachment to be uploaded and associated with a macro at the same time.

Note: A macro can be associated with up to five attachments.

Allowed For

• Agents

Creates an attribute.

Allowed For

• Agents

Creates an attribute value.

Allowed For

• Admins

Creates an automation.

New automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical.

The request must include the following conditions in the all array:

• At least one time-based condition
• At least one condition that checks one of the following fields: status, type, group_id, assignee_id, or requester_id.

Allowed For

• Agents

Allowed For

• Agents

Allowed for

• Admins

Creates an object describing all the properties required to create a custom object record

Allowed For

• Admins

Creates any of the following custom field types:

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

See About custom field types in Zendesk help.

Allowed For

• Admins

Creates a custom object record according to all the properties described by a custom object definition. If autoincrement_enabled is true, record names aren't allowed in the request body because they are generated automatically. If is_unique is true, record names must be unique.

Allowed For

• Agents

Availability

• Accounts on the Enterprise plan or above

Allowed for

• Administrators
• Agents with the manage_roles permission

Takes a custom_status object that specifies the custom ticket status properties to create.

Allowed For

• Admins

Creates a new deletion schedule.

Allowed For

• Admins

Create a new content item, with one or more variants in the item's variants array. See Specifying item variants.

The default_locale_id and variant locale_id values must be one of the locales the account has active. You can get the list with the List Locales endpoint.

Allowed For

• Admins, Agents

You can only create one variant for each locale id. If a locale variant already exists, the request is rejected.

Allowed For

• Admins, Agents

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage groups (Enterprise only)

Assigns an agent to a given group.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Allowed For

• Admins

Allowed For

• Agents

Allows an attachment to be uploaded that can be associated with a macro at a later time.

Note: To ensure an uploaded attachment is not lost, associate it with a macro as soon as possible. From time to time, old attachments that are not not associated with any macro are purged.

Allowed For

• Agents

Allowed For

• Admins, Agents

Accepts an array of up to 100 organization membership objects.

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
• Agents

Accepts an array of up to 100 organization objects.

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.

Allowed For

• Agents, with restrictions applying on certain actions

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](/api-refer

Allowed For

• Admins

Returns an OAuth access token with a specified scope.

Refresh tokens aren't used. An access token doesn't expire but it can be revoked.

For a tutorial, see Creating and using OAuth tokens with the API.

Note: For OAuth authorization code, use the Create Token for Grant Type endpoint. The two APIs don't share the same path, JSON format, or request parameters. However, both APIs return access tokens that can be used to authenticate API requests.

Allowed For

• Admins

Request parameters

The POST request takes a "token" object that contains an OAuth client's resource id and scopes.

| Name | Type | Description | --------- | ------

Creates a new object trigger for a specified object.

Allowed For

• Administrators
• Agents in custom roles with the manage_triggers permission (Enterprise only)

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

Creates an organization if it doesn't already exist, or updates an existing organization. Using this method means one less call to check if an organization exists before creating it. You need to specify the id or external id when updating an organization to avoid a duplicate error response. Name is not available as a matching criteria.

Allowed For

• Agents, with restrictions on certain actions

Creates or updates an option for the given drop-down ticket 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/ticket_fields/{ticket_field_id}/options.json if the ticket field option already exists in the database
• 201 with Location: /api/v2/ticket_fields/{ticket_field_id}/options.json if the ticket field option is new

Allowed For

• Admins

Rate Limit

You can make 100 requests every 1 minute using this endpoint. The rate limiting mechanism behaves as described in [Monitoring your request activity](/api-reference/ticketing/account-configuration/usage_limits/#monitoring-your-request-

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/{ne

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

You must provide a unique name for each organization. Normally the system doesn't allow records to be created with identical names. However, a race condition can occur if you make two or more identical POSTs very close to each other, causing the records to have identical organization names.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Creates any of the following custom field types:

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

See About custom field types in Zendesk help.

Allowed For

• Admins

Assigns a user to a given organization. Returns an error with status 422 if the user is already assigned to the organization.

Allowed For

• Admins
• Agents when creating a new organization membership for an end user

Merges two organizations by moving all users, tickets, and domain names from the organization specified by {organization_id} to the organization specified by winner_id. After the merge:

• The "losing" organization will be deleted.
• Other organization fields and their values will not be carried over to the "winning" organization.
• The merge operation creates an Organization Merge record which contains a status indicating the progress of the merge.

Note: This operation is irreversible.

Merge Statuses

Allowed For

• Admins

Allowed For:

• Agents
• End users

End users can only subscribe to shared organizations in which they're members.

Creates a queue. Accepts a JSON queue definition as the request body.

Allowed For

• Admins

Accepts a request object that sets one or more properties.

Allowed for

• End users
• Anonymous users (rate limit of 5 requests per hour for trial accounts)

Additional properties

In addition to the writable request properties in the JSON Format table above, you can set the following properties when creating a request.

Creates a resource collection from a provided payload object. The payload object is specified the same way as the content of a requirements.json file in a Zendesk app. See Specifying Apps Requirements in the Zendesk Apps framework docs.

The response includes a job status for creation of the specified resources.

Allowed for

• Admins

Availability

• Accounts on the Support Professional or Suite Growth plan or above

Allowed For

• Admins

Allowed For

• Admins

Adds a Zendesk or external support address to your account.

To add a Zendesk address, use the following syntax: {local-part}@{accountname}.zendesk.com. Example: 'sales-team@example.zendesk.com'. The local-part can be anything you like.

To add an external email address such as help@omniwearshop.com, the email must already exist and you must set up forwarding on your email server. The exact steps depend on your mail server. See Forwarding incoming email to Zendesk Support. After setting up forwarding, run the Verify Support Address Forwarding endpoint. The address won't work in Zendesk Support until it's been verified.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in [Creating custom roles

Allowed For

• Admins

Use this tool to post create ticket

Creates any of the following custom field types:

Allowed For

• Admins

Creates one or many ticket form status associations

Allowed For

• Admins

Creates one or many tickets form status associations for a custom status.

Allowed For

• Admins

Turns a tweet into a ticket. You must provide the tweet id as well as the id of a monitored X (formerly Twitter) handle configured for your account.

The submitter of the ticket is set to be the user submitting the API request.

Allowed For

• Agents

Allowed For

• Agents

Creating tickets

Introduction

Creating tickets using Talk Partner Edition follows the same conventions as the Create Ticket endpoint. See Create Ticket.

Request parameters

The POST request takes a mandatory ticket object that lists the values to set when the ticket is created. You may also include an optional display_to_agent value such as the ID of the agent that will see the newly created ticket. The display_to_agent is validated before creating the ticket, returning a 422 error if it is invalid.

Tickets created using this endpoint must have a via_id parameter. See the following section for possible values.

Zendesk Talk Integration Via IDs

Tickets created using this endpoint must have one of the following via_id parameters:

Creates a CSAT rating for a solved ticket, or for a ticket that was previously solved and then reopened.

Only the end user listed as the ticket requester can create a satisfaction rating for the ticket.

Allowed For

• End user who requested the ticket

The end user must be a verified user.

Returns an OAuth access token in exchange for an authorization code valid for 120 seconds.

Using a Zendesk username and password to gain an OAuth access token (password grant type flow) has been deprecated and is highly discouraged.

An access token can be revoked. Use the OAuth Tokens API to list, show, or revoke tokens.

The refresh token grant type allows for refreshing an access token that has either expired or is about to expire. See Oauth Tokens for Grant Types.

Request parameters

The POST request takes the following parameters, which must be formatted as JSON:

Use this tool to post create trial account

Allowed For

• Agents

Creates a ticket trigger category.

Use this tool to post create user

Creates any of the following custom field types:

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

See About custom field types in Zendesk help.

Allowed For

• Admins

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. The "skip_verify_email": true property does not apply when updating your own agent profile. A welcome or verification email will be sent regardless of this se

Allowed For

• Agents

JSON Format

The JSON format consists of one property, a view object that lists the values to set when the view is created.

Note: The request must include at least one condition in the all array that checks one of the following fields: status, type, group_id, assignee_id, or requester_id.

Allowed For

• Admins

Create a support ticket in Zendesk. Legacy version, please use Create Ticket instead.

List the current count and the limit for a custom object's fields

Allowed For

• Agents

Queues a background job to perform bulk actions on up to 100 custom object records per single request. Takes a job object with two nested fields:

• action, one of:
  • "create"
  • "delete"
  • "delete_by_external_id"
  • "create_or_update_by_external_id"
  • "create_or_update_by_name"
  • "update"
• items
  • For a "create" action, an array of JSON objects representing the custom object records being created
  • For a "delete" action, an array of strings representing Zendesk record ids
  • For a "delete_by_external_id" action, an array of strings representing external ids
  • For a "create_or_update_by_external_id" action, an array of JSON objects representing the custom object records being created or updated by external id
  • For a "create_or_update_by_name" action, an array of JSON objects representing the custom object records being created or updated by n

List the current count and the limit for custom object records

Allowed For

• Agents

List the current count and the limit for custom objects

Allowed For

• Admins

Deletes an attribute.

Allowed For

• Admins

Deletes an attribute value.

Allowed For

• Agents

Deletes the current session. In practice, this only works when using session auth for requests, such as client-side requests made from a Zendesk app. When using OAuth or basic authentication, you don't have a current session so this endpoint has no effect.

Allowed For

• Admins, Agents, End users

Note: You might be restricted from deleting some default automations.

Allowed For

• Agents

Allowed For

• Agents (own bookmarks only)

If the bookmark already exists with a specified ticket id, the response status will be http Status: 200 OK.

Deletes a brand.

Allowed for

• Admins

Allowed for

• Admins

Permanently deletes the custom object with the specified key

Allowed For

• Admins

Deletes a field with the specified key. Note: You can't delete standard fields.

Allowed For

• Admins

Deletes a record with the specified id

Allowed For

• Agents

Deletes a record with the specified external id or name. The is_unique property on the custom object's name field must be enabled in order to delete by name. External id and name cannot be used together in the same request.

Allowed For

• Agents

Availability

• Accounts on the Enterprise plan or above

Allowed for

• Administrators
• Agents with the manage_roles permission

Deletes a deletion schedule by its id.

Allowed For

• Admins

Allowed For

• Admins, Agents

Allowed For

• Admins, Agents

Delete the essentials card for an object type.

Allowed For

• Admins and agents

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage groups (Enterprise only)

Immediately removes a user from a group and schedules a job to unassign all working tickets that are assigned to the given user and group combination.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Allowed For

• Admins

Allowed For

• Agents, with restrictions applying on certain actions

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

Allowed For

• Agents

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

Note: You can only bulk-delete triggers associated with one object at a time, specified by the custom_object_key in the request.

Allowed For

• Administrators
• Agents in custom roles with the manage_triggers permission (Enterprise only)

Request Parameters

The DELETE request takes an ids object that lists the object triggers to delete. All of the specified object trigger ids must be associated with a single object.

Example request

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

Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The organization_id of the unassigned tickets is set to null.

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.

Allowed For

• Agents

Accepts a comma-separated list of up to 100 organization ids or external ids.

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.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Deletes the ticket 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 ticket triggers to delete.

Example request

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

Deletes a specified object trigger.

Allowed For

• Administrators
• Agents in custom roles with the manage_triggers permission (Enterprise only)

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

Allowed for

• Admins

Immediately removes a user from an organization and schedules a job to unassign all working tickets currently assigned to the user and organization combination. The organization_id of the unassigned tickets is set to null.

Allowed for

• Admins
• Agents when deleting an organization membership for an end user

Allowed For:

• Agents
• End users

Deletes the queue and related records.

Allowed For

• Admins

Deletes a support address.

Allowed For

• Admins
• Agents with permission to manage channels and extensions. See the system permissions in Creating custom roles and assigning agents (Enterprise) in the Support Help Center

Deletes a specified resource collection.

The response includes a job status for deletion of the collection's resources.

Allowed for

• Admins

Availability

• Accounts on the Support Professional or Suite Growth plan or above

Allowed For

• Admins

Allowed For

• Admins, Agents, End users

Deletes a sharing agreement.

Allowed For

• Admins

Allowed For

• Unrestricted agents

Accepts up to 100 ids (the auto-generated id, not the ticket id.)

Allowed For

• Admins and agents in custom roles with permission to manage suspended tickets on Enterprise plans
• Unrestricted agents on all other plans

You can also delete tags from multiple tickets with the Update Many Tickets endpoint.

This endpoint supports safe updates. See Safe Update.

Allowed For

• Agents

Allowed For

• Admins

Allowed For

• Admins
• Agents with permission to delete tickets

Agent delete permissions are set in Support. See Deleting tickets in the Support Help Center.

Ticket deletion rate limit

You can delete 400 tickets every 1 minute using this endpoint. The rate limiting mechanism behaves as described in Rate limits in the API introduction. Zendesk recommends that you obey the Retry-After header values. To delete many tickets, you may use Bulk Delete Tickets.

Allowed for

• Admins

Allowed for

• Admins

Allowed For

• Admins

Deletes a ticket form status by id.

Allowed For

• Admins

Deletes all of of the ticket form statuses by id.

Allowed For

• Admins
• Agents

Permanently deletes a soft-deleted ticket. See Soft delete in the Zendesk GDPR docs. To soft delete a ticket, use the Delete Ticket endpoint.

This endpoint enqueues a ticket deletion job and returns a payload with the jobs status.

If the job succeeds, the ticket is permanently deleted. This operation can't be undone.

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.

Allowed For

• Agents

Allowed For

• Agents

Deletes the ticket trigger category with the specified ID.

Allowed for

• End Users

Deletes the user and associated records from the account.

Warning:

• Deleted users are not recoverable.
• Both agents and administrators can soft delete users in the agent interface in Zendesk Support. Agents with permission can delete end users, while administrators can delete all users except the account owner.

To comply with GDPR, a further step is needed. See Permanently Delete User.

Allowed For

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

Allowed for

• Admins

Allowed for

• Admins

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.

Deleting identities with type messaging could break messaging functionality. For example, an agent may stop being able to send messages via the messaging channel.

Allowed For

• Agents

Allowed For

• Agents

Allowed For

• Admins

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

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.

Allowed For

• Admins

Allowed For

• Anyone

Returns all the variants of the specified dynamic content item.

Allowed For

• Admins
• Agents who have permission to manage dynamic content

Pagination

• Cursor pagination

See Pagination.

Returns the column titles and the rows of the specified view.

The columns array lists the view's column titles and includes only views parameters.

The rows array lists the values of each column for each ticket and includes parameters from both views and tickets. Though not displayed in the view, a partial ticket object is included with each row object.

Note: To get the full ticket objects for a specified view, use List Tickets from a View.

This endpoint is rate limited to 5 requests per minute, per view, per agent. This rate limit includes activity in Zendesk Support. An API script is more likely to encounter rate limit errors if the authenticating agent or admin is concurrently active in Zendesk Support.

The view execution system is designed for periodic rather than high-frequency API usage. In particular, views called very frequently may be cached by Zendesk. This mea

Allowed For

• Admins on accounts that have audit log access

Exports a set of results. See Query syntax for the syntax of the query parameter.

Use this endpoint for search queries that will return more than 1000 results. The result set is ordered only by the created_at attribute.

The search only returns results of a single object type. The following object types are supported: ticket, organization, user, or group.

You must specify the type in the filter[type] parameter. Searches with type in the query string will result in an error.

Allowed For

• Agents

Pagination

• Cursor pagination

See Pagination.

Returns a maximum of 1000 records per page. The number of results shown in a page is determined by the page[size] parameter.

Note: You may experience a speed reduction or a timeout if you request 1000 results per page and you have many archived tickets in the results. Try reducing the

Exports a list of suspended tickets for the Zendesk Support instance. To export the list, the endpoint enqueues a job to create a CSV file with the data. When done, Zendesk sends the requester an email containing a link to the CSV file. In the CSV, tickets are sorted by the update timestamp in ascending order.

Allowed For

• Admins and agents in custom roles with permission to manage suspended tickets on Enterprise plans
• Unrestricted agents on all other plans

Rate limits

Limited to one request per minute and up to one million records in return. The rate-limiting mechanism behaves identically to the one described in Usage limits. We recommend using the Retry-After header value as described in [Catching errors caused

Returns the csv attachment of the specified view if possible. Enqueues a job to produce the csv if necessary.

Allowed For

• Agents

Returns an array of custom object records that meet the search and filter criteria.

Filters can contain either an individual comparison object or an array of comparison objects within logical namespaces.

A filter is a JSON object that has the following properties:

Examples

{
  "filter": {
    "custom_object_fields.field_key": { "$eq": "value" } // ATTRIBUTE
  }
}

// $or
{
  "filter": {
    "$or": [

Gets a deletion schedule by its id.

Allowed For

• Admins

Returns details of a specific object trigger.

Allowed For

• Agents

Returns filter definitions based on the given target type. Target types include users (zen:user), tickets (zen:ticket), organizations (zen:organization), or custom objects (zen:custom_object:CUSTOM_OBJECT_KEY). The returned filter definitions are the options that you can use to build a custom field or ticket field's relationship_filter.

Returns a list of source objects whose values are populated with the id of a related target object. For example, if you have a lookup field called "Success Manager" on a ticket, this endpoint can answer the question, "What tickets (sources) is this user (found by target_type and target_id) assigned as the 'Success Manager' (field referenced by field_id)?"

Allowed For

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

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
• End Users

Returns the ticket count for a single view.

This endpoint is rate limited to 5 requests per minute, per view, per agent.

View Counts

The view count endpoints, Count Tickets in View (this endpoint) and Count Tickets in Views, let you estimate how many tickets remain in a view without having to retrieve the entire view. They're designed to help estimate view size. From a business perspective, accuracy becomes less relevant as view size increases.

To ensure quality of service, these counts are cached more heavily as the number of tickets in a view grows. For a view with thousands of tickets, you can expect the count to be cached for 60-90 minutes. As a result, the count may not reflect the actual number of tickets in your view.

View counts are represented as JSON objects with the following attributes:

| Name | Type | Comment | --------------- | ------------|

Returns the ticket count of each view in a list of views. Accepts up to 20 view ids per request. For the ticket count of a single view, see Count Tickets in View.

Only returns values for personal and shared views accessible to the user performing the request.

This endpoint is rate limited to 6 requests every 5 minutes.

Allowed For

• Agents

Allowed For

• Agents

Assigns up to 100 agents to given groups.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

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.

Immediately removes users from groups and schedules a job to unassign all working tickets that are assigned to the given user and group combinations.

Allowed For

• Admins
• Agents assigned to a custom role with permissions to manage group memberships (Enterprise only)

Allowed For:

• Agents

Allowed For

• Admins

Sideloading

See Organizations sideloads.

Use this endpoint to test the incremental export format. It's more strict in terms of rate limiting, at 10 requests per 20 minutes instead of 10 requests per minute. It also returns only up to 50 results per request. Otherwise, it's identical to the above APIs.

Use the incremental_resource parameter to specify the resource. Possible values are "tickets", "ticket_events", "users", or "organizations".

Returns a stream of changes that occurred on routing attribute values.

Allowed For

• Admins

Parameters

Optional

Returns a stream of changes that occurred on routing attributes.

Allowed For

• Admins

Parameters

Optional

Returns a stream of changes that occurred on routing instance values. Changes are grouped by attribute_value_id, with associate type events listed alongside unassociate type events based on the unassociate event's timestamp.

Allowed For

• Admins

Parameters

Optional

Returns a stream of changes that occurred on tickets, excluding events occuring within one minute of the request. Each event is tied to an update on a ticket and contains all the fields that were updated in that change. For more information, see:

• Exporting ticket events in Using the Incremental Exports API
• Time-based incremental exports in Using the Incremental Exports API

You can include comments in the event stream by using the comment_events sideload. See Sideloading below. If you don't specify the sideload, any comment present in the ticke

Returns the tickets that changed since the start time. For more information, see Exporting tickets in Using the Incremental Exports API.

This endpoint supports cursor-based incremental exports. Cursor-based exports are highly encouraged because they provide more consistent performance and response body sizes. For more information, see Cursor-based incremental exports in Using the Incremental Exports API.

Allowed For

• Admins

Sideloading

See [Tickets sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoin

Returns the tickets that were created or changed since a start time.

Allowed For

• Admins

Sideloading

See Users sideloads.

Allowed For

• Admins

Sideloading

See Users sideloads.

Returns an attribute value.

Allowed For

• Agents and admins

Returns a list of attributes for the account.

Sideloads

The following sideloads are supported:

Allowed For

• Agents and admins

Lists all active automations.

Allowed For

• Agents

Available Parameters

You can pass in any combination of the following optional filters:

Sideloads

The following sideloads are supported:

Lists all active shared and personal macros available to the current user.

Allowed For

• Agents

Lists all active object triggers.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Administrators
• Agents in custom roles with the manage_triggers permission (Enterprise only)

Lists all active ticket 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:

Lists active shared and personal views available to the current user.

Sideloads

The following sideloads are supported:

Pagination

• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Lists ticket activities in the last 30 days affecting the agent making the request. Also sideloads the following arrays of user records:

• actors - All actors involved in the listed activities
• users - All users involved in the listed activities

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Returns a maximum of 100 group memberships per page.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For:

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents

List assignable agents from a group on the AssigneeField

Allowed For

• Agents

List assignable groups on the AssigneeField

Allowed For

• Agents

List assignable groups and agents based on query matched against name

Allowed For

• Agents

Returns a list of attribute values for a provided attribute.

Allowed For

• Agents

Allowed For

• Admins on accounts that have audit log access

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Lists the audits for a specified ticket.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Note: Audits for Archived Tickets do not support pagination for this endpoint.

Allowed for

• Agents

Lists all automations for the current account.

Allowed For

• Agents

Available Parameters

You can pass in any combination of the following optional filters:

Sideloads

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

Lists the translation locales that are available to all accounts.

Allowed For

• Anyone

Allowed For

• Agents

Returns a list of all brand agent memberships for your account.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For:

• Admins

Returns a list of all brands for your account sorted by name.

Allowed for

• Admins
• Agents with the assign_tickets_to_any_brand permission can list all brands for the account
• Agents without the assign_tickets_to_any_brand permission can only list brands they are members of

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Sorting

By default, comments are sorted by creation date in ascending order.

When using cursor pagination, use the following parameter to change the sort order:

When using offset pagination, use the following parameters to change the sort order:

Allowed For

• End Users

A compacted list of shared and personal views available to the current user. This endpoint never returns more than 32 records and does not respect the "per_page" option.

Allowed For

• Agents

Lists all undeleted custom fields for the specified object.

Allowed For

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Lists all undeleted custom object records for the specified object

Pagination

• Cursor pagination only.

Allowed For

• Agents

Lists all undeleted custom objects for the account

Allowed For

• Agents

Availability

• Accounts on the Enterprise plan or above

Allowed For

• Agents

Lists all undeleted custom ticket statuses for the account. No pagination is provided.

Allowed For

• End Users

Returns a maximum of 100 deleted tickets per page. See Pagination.

The results includes all deleted (and not yet archived) tickets that have not yet been scrubbed in the past 30 days. Archived tickets are not included in the results. See About archived tickets in the Support Help Center.

The tickets are ordered chronologically by created date, from oldest to newest. The first ticket listed may not be the oldest ticket in your account due to ticket archiving.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Rate Li

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

Lists all deletion schedules for the account. Deletion schedules are used to automatically delete data from the account after a certain period of time.

Allowed For

• Admins

Returns a list of all dynamic content items for your account if accessed as an admin or agents who have permission to manage dynamic content.

Allowed For

• Admins, Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Allowed For

• Agents

Filters

• By notification: api/v2/email_notifications.json?filter[notification_id]=7824075373693
• By comment: api/v2/email_notifications.json?filter[comment_id]=7824075373565
• By ticket: api/v2/email_notifications.json?filter[ticket_id]=623

Pagination

By default, a maximum of 100 email notifications are included per page. Use cursor-based pagination parameters (page[after] and page[before]) to navigate the records (can't be used together in the same request). See Pagination for more details.

• Limit items per-page: api/v2/email_notifications.json?page[size]=25
• Retrieve next page: api/v2/email_notifications.json?page[size]=25&page[after]=xxx
• Retrieve previous page: api/v2/email_notifications.json?page[size]=25&page[before]=yyy

The values xxx and yyy are placeholder values that represent cursors.

Returns all the global OAuth clients that users on your account have authorized.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For:

• Agents

Allowed For

• Admins

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents

Shows the statuses for background jobs. Statuses are sorted first by completion date and then by creation date in descending order.

Allowed For:

• Agents

Pagination

• Cursor pagination

See Pagination.

Lists the translation locales available for the account.

Note: You can alter the list by passing an updated locale_ids array to the Update Account Settings endpoint.

Allowed For

• Anyone

Lists the translation locales that have been localized for agents on a specific account.

Allowed For

• Anyone

Returns the definitions of the actions a macro can perform. For example, one action can set the status of a ticket. The definition of the action includes a title ("Status"), a type ("list"), and possible values. For a list of support actions, see Actions reference.

Allowed For

• Agents

Lists the attachments associated with a macro.

Allowed For

• Agents

Lists all macro categories available to the current user.

Allowed For

• Agents

Lists all shared and personal macros available to the current user. For admins, the API returns all macros for the account, including the personal macros of agents and other admins.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Agents

Allowed For

• Agents