Deletes an attribute value.

Allowed For

• Agents

Returns an attribute value.

Allowed For

• Admins

Updates an attribute value.

Allowed For

• Admins

Returns a list of ticket ids that contain attributes matching the current user’s attributes. Accepts a ticket_ids parameter for relevant tickets to check for matching attributes.

Allowed For

• Agents and admins

Returns a list of attributes values for the ticket.

Allowed For

• Agents and admins

Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.

Invalid or deleted attributes are ignored.

Allowed For

• Admins

Lists all the support addresses for the account.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins
• Agents

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 and assigning agents (Enterprise) in the Support Help Center

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

Allowed For

• Admins
• Agents

Updates an existing support address for your account.

You can’t use this endpoint to update a support address’s email property.
Instead, you can create a new address using the Create Support
Address endpoint.

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

Sends a test email to the specified support address to verify that email forwarding for the address works. An external support address won’t work in Zendesk Support until it’s verified.

Note: You don’t need to verify Zendesk system support addresses.

The endpoint takes the following body: {"type": "forwarding"}. The value of the type property defaults to “forwarding” if none is specified, but the values “spf” and “dns” are also accepted.

Use this endpoint after adding an external support address to Zendesk Support and setting up forwarding on your email server. See Forwarding incoming email to Zendesk Support.

The endpoint doesn’t return the results of the test. Instead, use the Show Support Address endpoint to check that the forwarding_status property is “verified”.

Other verification checks can also be performed using this API. These include SPF checks and DNS checks.

When calling the endpoint with type set to “spf”, it will queries the DNS records to check that the SPF records for Zendesk are present for outbound emails.

When calling the endpoint with type set to “dns”, it runs checks on your CNAME records to make sure they are set up properly in your DNS.

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

Allowed For

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

Sorting

You can sort the tickets with the sort_by and sort_order query string parameters.

Pagination

• Cursor pagination

See Pagination.

Makes copies of any attachments on a suspended ticket and returns them as attachment tokens. If the ticket is manually recovered, you can include the attachment tokens on the new ticket.

Allowed For

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

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

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 by rate limiting.

Accepts up to 100 ids (the auto-generated id, not the ticket id.) Note that suspended tickets that fail to be recovered are still included in the response.

Allowed For

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

Allowed For

• Unrestricted agents

Allowed For

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

Note: During recovery, the API sets the requester to the authenticated agent who called the API, not the original requester. This prevents the ticket from being re-suspended after recovery. To preserve the original requester, use the Recover Multiple Suspended Tickets endpoint with the single ticket.

This endpoint does not queue an asynchronous job that can be tracked from Job Statuses. Instead, it processes the request with a synchronous response.

• If all recoveries are successful, it returns a 200 with a tickets array in the response.
• If all recoveries fail, it returns a 422 with a suspended_tickets array in the response.
• If there is a mixture of successes and failures in a single call, it returns a 422 with a suspended_tickets array of the failures in the response.

Allowed For

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

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

Lists up to the 20,000 most popular tags in the last 60 days, in decreasing popularity.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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

• Admins

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

• Agents

Allowed For

• Agents

You can also add tags to multiple tickets with the Update Many
Tickets endpoint.

Safe Update

If the same ticket is updated by multiple API requests at
the same time, some tags could be lost because of ticket
update collisions. Include updated_stamp and safe_update
properties in the request body to make a safe update.

For updated_stamp, retrieve and specify the ticket’s
latest updated_at timestamp. The tag update only occurs
if the updated_stamp timestamp matches the ticket’s
actual updated_at timestamp at the time of the request.
If the timestamps don’t match (in other words, if the
ticket was updated since you retrieved the ticket’s
last updated_at timestamp), the request returns a
409 Conflict error.

Example

{
  "tags": ["customer"],
  "updated_stamp":"2019-09-12T21:45:16Z",
  "safe_update":"true"
}

For details, see Protecting against ticket update collisions.

Allowed For

• Agents

Returns the 25 most recent target failures, per target.

Stability

• Development

Allowed For

• Admins

Stability

• Development

Allowed For

• Admins

Allowed For

• Agents

Allowed For

• Admins

Allowed For

• Admins

Allowed For

• Agents

Allowed For

• Admins

Returns ticket audits. Archived tickets are not included in the response. Use the List Audits for a Ticket endpoint to
retrieve audit records for an archived ticket. To learn more about archived tickets, see About archived tickets.

This endpoint should not be used for capturing change data. When continually chasing the tail of a cursor, some records will be skipped. For this use case, use the Incremental Ticket Event Export API.

Pagination

• Cursor pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

• Admins

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

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: 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

Allowed for

• Agents

Allowed for

• Agents

Permanently removes one or more chat attachments from a chat ticket.

Note: This does not work on active chats. For chat tickets that predate March 2020, consider using Redact Ticket Comment In Agent Workspace.

Allowed For

• Agents

Agent Workspace must enabled for the account. Deleting tickets must be enabled for agents.

Request Body Properties

To get the required body properties, make a request to the Ticket Audits endpoint. Example response:

Status 200 OK
{
  "audits": [
    "events": [
      {
        "id": 1932802680168,
        "type": "ChatStartedEvent",
        "value": {
          "visitor_id": "10502823-16EkM3T6VNq7KMd",
          "chat_id": "2109.10502823.Sjuj2YrBpXwei",
          "history": [
            {
              "chat_index": 0,
              "type": "ChatFileAttachment",
              "filename": "image1.jpg"
            },
            {
              "chat_index": 1,
              "type": "ChatFileAttachment",
              "filename": "image2.jpg"
            }
          ]
        }
      }
    ]
  ]
}

Permanently removes words or strings from a chat ticket’s comment.

Wrap <redact> tags around the content in the chat comment you want redacted. Example:

{
  "text": "My ID number is <redact>847564</redact>!"
}

The characters contained in the tag will be replaced by the ▇ symbol.

Note: This does not work on active chats. For chat tickets that predate March 2020, consider using Redact Ticket Comment In Agent Workspace.

Allowed For

• Agents

Agent Workspace must enabled for the account. Deleting tickets must be enabled for agents.

Request Body Properties

To get the required body properties, make a request to the Ticket Audit endpoint. Example response:

Status 200 OK
{
  "audits": [
    "events": [
      {
        "id": 1932802680168,
        "type": "ChatStartedEvent",
        "value": {
          "visitor_id": "10502823-16EkM3T6VNq7KMd",
          "chat_id": "2109.10502823.Sjuj2YrBpXwei",
          "history": [
            {
              "chat_index": 0,
              "type": "ChatMessage",
              "message": "My ID number is 847564!"
            }
          ]
        }
      }
    ]
  ]
}

Redaction allows you to permanently remove words, strings, or attachments from a ticket comment.

In the html_body of the comment, wrap the content you want redacted in <redact> tags. Example:

{
  "html_body": "<div class=\"zd-comment\" dir=\"auto\">My ID number is <redact>847564</redact>!</div>",
  "ticket_id":100
}

The characters in the redact tag will be replaced by the ▇ symbol.

To redact HTML elements such inline images, anchor tags, and links, add the redact tag attribute to the element as well as the <redact> tag to inner text, if any. Example:

<a href="http://example.com" redact><redact>some link</redact></a>

The redact attribute only redacts the tag. Any inner text will be left behind if not enclosed in a <redact> tag.

Redaction is permanent and can not be undone. Data is permanently deleted from Zendesk servers with no way to recover it.

This endpoint provides all the same functionality that the Redact String in Comment endpoint provides, plus:

• Redaction of comments in closed tickets

• Redaction of comments in archived tickets

• Redaction of formatted text (bold, italics, hyperlinks)

Limitations: When content is redacted from an email comment, the content is also redacted from the original email through a background job. It may take a while for the changes to be completed.

Note: We recommend using this endpoint instead of the Redact String in Comment endpoint, which will eventually be deprecated.

Allowed For

• Agents

Agent Workspace must be enabled on the account. For professional accounts, deleting tickets must be enabled for agents. On Enterprise accounts, you can assign agents to a custom role with permissions to redact ticket content.

Request Body Properties

Returns the comments added to the ticket.

Each comment may include a content_url for an attachment or a recording_url for a voice comment that points to a file that may be hosted externally. For security reasons, take care not to inadvertently send Zendesk authentication credentials to third parties when attempting to access these files. See Working with url properties.

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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

• 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

Allowed For

• Agents

Permanently removes words or strings from a ticket comment. Specify the string to redact in an object with a text property. Example: '{"text": "987-65-4320"}'. The characters of the word or string are replaced by the ▇ symbol.

If the comment was made by email, the endpoint also attempts to redact the string from the original email retained by Zendesk for audit purposes.

Note: If you use the rich text editor, support for redacting formatted text (bold, italics, hyperlinks) is limited.

Redaction is permanent. You can’t undo the redaction or see what was removed. Once a ticket is closed, you can no longer redact strings from its comments.

To use this endpoint, the “Agents can delete tickets” option must be enabled in the Zendesk Support admin interface at Admin > Settings > Agents.

Allowed For

• Agents

Returns a list of all system and custom ticket fields in your account.

Cursor pagination returns a maximum of 100 records per page and fields are returned in the order specified by their id.

If the results are not paginated every field is returned in the response and fields are returned in the order specified by the position and id.

For accounts without access to multiple ticket forms, positions can be changed using the Update Ticket Field endpoint or the Ticket Forms page in Zendesk Support (Admin > Manage > Ticket Forms). The Ticket Forms page shows the fields for the account. The order of the fields is used in the different products to show the field values in the tickets.

For accounts with access to multiple ticket forms, positions can only be changed using the Update Ticket Field endpoint because products use the order defined on each form to show the field values instead of the general position of the ticket field in the account.

Consider caching this resource to use with the Tickets API.

Pagination

• Cursor pagination (recommended)
• No pagination

See Pagination.

Sideloads

The following sideloads are supported:

Allowed For

• Agents

Creates any of the following custom field types:

See About custom field types in the Zendesk Help Center.

Allowed For

• Admins

Field limits

We recommend the following best practices for ticket fields limits. Creating more than these amounts can affect performance.

• 400 ticket fields per account if your account doesn’t have ticket forms
• 400 ticket fields per ticket form if your account has ticket forms

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

Allowed for

• Admins