Introduction

This is the reference documentation for the Zendesk Support API. It also covers features shared by other Zendesk v2 APIs. The v2 APIs consist of the Support API, the Help Center API, and the Talk API. For documentation on all Zendesk APIs, see API Docs.

In addition to the Support API reference docs, the following resources are available in the Develop Help Center:

Zendesk makes changes to the API from time to time. For more information, see API Changes.

Document conventions

Endpoints are described with an HTTP method and a path. Example:

GET /api/v2/help_center/en-us/articles.json

Prepend your Zendesk Support URL to the path to get the full endpoint URL. If example, if your Support URL is https://obscura.zendesk.com, then use the following endpoint URL:

https://obscura.zendesk.com/api/v2/help_center/en-us/articles.json

Curly braces, {}, in the path indicate a placeholder value that you must replace. Example:

GET  /api/v2/users/{user_id}.json

The .json file extension can be omitted if you include a Content-Type: application/json header with your requests.

The body of requests and responses for each resource is described in a JSON format table. Each table lists a resource's properties, their data types, whether or not they're read-only, whether or not they're required, and descriptions.

Access to most endpoints is restricted by Zendesk user role. The role is specified in the Allowed For section of an endpoint. The hierarchy of Zendesk user roles is as follows: owner, admins, agents, end users, and anonymous users. When the Allowed For section lists a role, any user with a higher level role implicitly also has access to the endpoint. For example, if the Allowed For section lists "Agents", then the owner and admins can use the endpoint too.

Examples

The examples in the docs are cURL statements. You can run the statements on a command line to try out different API requests. To learn more, see Installing and using cURL. In Windows, you'll need to modify some of the examples in the docs to make them work. See Using cURL in Windows.

If you use a password to authenticate your curl requests, make sure to escape any special characters in the password. Example: pa$$word becomes pa\$\$word. See this post on StackExchange for more information.

You can also use Postman to try out different requests.

The examples use basic authentication requiring a Zendesk username and password. Make sure to enable password access in the Zendesk Support admin interface at Admin > Channels > API.

Security and authentication

You must be a verified user to make API requests. You can authorize against the API using an OAuth access token, a Zendesk API token with your email address, or your password and your email address.

Client-side CORS requests are supported if the request is authenticated with an OAuth access token. The requests are not supported if the request uses a Zendesk API token or a password. For more information and a tutorial, see Making cross-origin, browser-side API requests in the Zendesk API guide.

Topics covered in this section:

Using an OAuth access token

Using an OAuth access token is the recommended method for accessing the API. To learn how to get an access token, see Using OAuth authentication with your application in the Zendesk help center. You can also use the API (accessed using basic authentication) to create an OAuth access token. See Creating and using OAuth tokens with the API.

OAuth access tokens also permit client-side API requests. See Making cross-origin, browser-side API requests in the Zendesk API guide.

In your requests, specify the access token in an Authorization header as follows:

Authorization: Bearer {access_token}

Example:

Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo

If you use curl to test different endpoints, you can use the following format:

curl https://obscura.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
Using a Zendesk API token

While using an OAuth access token is recommended, you can also use a Zendesk API token with your email address to access the API. Zendesk API tokens are different from OAuth tokens. Zendesk API tokens are auto-generated passwords in the Support admin interface.

Warning: Zendesk API tokens are like passwords. They can be used to impersonate anyone in the account, including admins. Make sure to keep them secure. Delete any unused tokens. Delete a token at once if you suspect it's been compromised and create another one if necessary. Another option is to use OAuth tokens.

Zendesk API tokens are managed in the Support admin interface at Admin > Channels > API. The page lets you view, add, or delete tokens. More than one token can be active at the same time. Deleting a token deactivates it permanently.

Authenticating with an API token is a form of basic authentication. As described in Basic authentication, the credentials must be sent with the request in an Authorization header.

Use the following format for the credentials:

{email_address}/token:{api_token}

Example:

[email protected]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

After base64-encoding the resulting string, add it to the Authorization header as follows:

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

Most HTTP request libraries have methods that simplify basic authentication.

If you use curl to test different endpoints, you can use the following format:

curl https://obscura.zendesk.com/api/v2/users.json \
  -u [email protected]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

If authenticating over HTTP, url-encode the slash character in {email_address}/token as %2F.

Using basic authentication

While using an OAuth access token is recommended, you can also use your email address and password to access the API. The credentials must be sent in an Authorization header in the HTTP request. Credentials sent in the body or URL of the request are ignored.

To use basic authentication, password access must be enabled in the Zendesk Support admin interface at Admin > Channels > API.

To authenticate a request with basic authentication

  1. Combine your email address and password with a colon. Example: [email protected]:pa$$w0rd.

  2. Base64-encode the resulting string. Example: amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==.

  3. Include the base64-encoded string in a HTTP Authorization header as follows:

    Authorization: Basic {base64-encoded-string}
    

    Example:

    Authorization: Basic amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==
    

Most HTTP request libraries have methods that simplify basic authentication.

If you use curl to test different endpoints, you can use the following format:

curl https://obscura.zendesk.com/api/v2/users.json \
  -u [email protected]:pa\$\$w0rd

If an agent or admin has enabled 2-factor authentication in their user profile, they won't be able to use basic authentication. Alternatives include using an API token or implementing an OAuth flow. Learn more.

SSL requirements

The Zendesk v2 API an SSL-only API, regardless of how your account is configured.

All connections to the Zendesk API must support the TLS 1.2 protocol. Support for TLS 1.0 and 1.1 was removed in June 2018. See Removal of support for TLS protocol versions 1.0 and 1.1.

Connections to the API must also support the SNI extension to TLS.

If you connect to Zendesk through a client library, make sure it supports both TLS 1.2 and SNI.

Rate limits

The Zendesk API is rate limited. Only allow a certain number of requests are allowed per minute depending on your plan and the endpoint. Zendesk reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients. For details, see Usage limits.

Request format

The Zendesk API is a JSON API. You must supply a Content-Type: application/json header in PUT and POST requests. You must set an Accept: application/json header on all requests. You may get a text/plain response in case of an error like a bad request. You should treat this as an error you need to fix.

The documented JSON properties for this API are case sensitive. For example, the following POST to api/v2/tickets.json won't work because body is capitalized:

{
  "ticket": {
    "subject": "My printer is on fire!",
    "comment": {
      "Body": "The smoke is very colorful."
    }
  }
}

To learn more, see Working with JSON.

Response format

The Zendesk API responds to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, the API renders the resulting JSON representation in the response body and sets a Location header pointing to the resource. Example:

Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/items/123.json

{
  "item": {
    "id": 123,
    "url": "https://{subdomain}.zendesk.com/api/v2/items/123.json",
    "name": "Wibble",
    ...
    "created_at": "2012-04-04T09:14:57Z"
  }
}

The response also includes the following headers indicating the account's current rate limit and the number of requests remaining in the current minute:

X-Rate-Limit: 700
X-Rate-Limit-Remaining: 699

Responses may have the status codes described in the following sections.

200 range

The request was successful. The status is 200 for successful GET and PUT requests, 201 for most POST requests, and 204 for DELETE requests.

400 range

The request was not successful. The content type of the response may be text/plain for API-level error messages, such as when trying to call the API without SSL. The content type is application/json for business-level error messages because the response includes a JSON object with information about the error:

{
  "details": {
    "value": [
      {
        "type": "blank",
        "description": "can't be blank"
      },
      {
        "type": "invalid",
        "description": " is not properly formatted"
      }
    ]
  },
  "description": "RecordValidation errors",
  "error": "RecordInvalid"
}

If you see a response from a known endpoint that looks like plain text, you probably made a syntax error in your request. This type of response commonly occurs when making a request to a nonexistent Zendesk Support instance.

403

A 403 response means the server has determined the user or the account doesn’t have the required permissions to use the API.

409

A 409 response can indicate a merge conflict, but it often indicates a uniqueness constraint error in our database due to the attempted simultaneous creation of a resource. Try your API call again.

In general, the Zendesk API can handle concurrent API requests but the requests shouldn't be talking about the same resources such as the same requester. Serialize requests where possible.

422 Unprocessable Entity

A 422 response means that the content type and the syntax of the request entity are correct, but the content itself is not processable by the server. This is usually due to the request entity not being relevant to the resource that it's trying to create or update. Example: Trying to close a ticket that's already closed.

429

A 429 error indicates that a usage limit has been exceeded. See Usage limits.

500 range

A 503 response with a Retry-After header indicates a database timeout or deadlock. You can retry your request after the number of seconds specified in the Retry-After header.

If the 503 response doesn't have a Retry-After header, Zendesk Support may be experiencing internal issues or undergoing scheduled maintenance. In such cases, check @zendeskops and our status page for any known issues.

When building an API client, we recommend treating any 500 status codes as a warning or temporary state. However, if the status persists and we don't have a publicly announced maintenance or service disruption, contact us at [email protected].

If submitting a ticket to Support, provide the X-Zendesk-Request-Id header included in the HTTP response. This helps the Support team track down the request in the logs more quickly.

Data Types

The API returns and accepts JSON values, which can be strings in double quotes, numbers, objects, arrays, true or false, or null. Most programming languages have tools to parse this data. See Working with JSON for a few languages.

ID integers

Most Zendesk Support resources such as tickets and users are identified by the integer specified by the id attribute of API responses.

The default numeric type in JavaScript, Ruby, Python, and PHP is sufficient to represent Zendesk Support ID integers.

If you use a static-typed language where integer types are declared explicitly, use a 64-bit integer type (signed is OK) for Zendesk Support ID integers. For example, in Java or C#, use the long type, not int.

Time stamps

Time stamps use UTC time and are formatted as ISO 8601 strings. Example: 2015-04-16T09:14:57Z.

Some endpoints use Unix time, also known as Epoch or POSIX time. Example: 1455821369. Learn more on Wikipedia.

Pagination

Most list endpoints support two methods of paginating through results -- cursor pagination and offset pagination. See the API documentation for an endpoint to determine which pagination methods it supports. If no pagination method is specified, the endpoint only supports offset pagination.

Zendesk recommends using cursor pagination instead of offset pagination where possible. Cursor pagination provides greatly improved performance when retrieving extremely large record sets. See Comparing Cursor Pagination and Offset Pagination for further details on the differences between the pagination methods.

Using Cursor Pagination

To use cursor pagination, include the page[size] parameter in the request parameters. This parameter is also used to specify the number of items to return per page. Most endpoints limit this to a maximum of 100. See the API documentation for the specific resource.

For example, a request to the tickets endpoint with the URL https://example.zendesk.com/api/v2/tickets.json?page[size]=100 would return a response with the following format:

"tickets": [ ... ],
"meta": {
  "has_more": true,
  "after_cursor": "xxx",
  "before_cursor": "yyy"
},
"links": {
  "next": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=xxx",
  "prev": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[before]=yyy"
}

The values xxx and yyy are example placeholder values.

Use the URL in the links[next] property to retrieve the next page of results. Using the above example, make a request to https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=xxx to retrieve the next page of results.

Repeat the above steps until the meta[has_more] property is false. This indicates there are no further records and you should stop paginating.

For more detailed instructions and code examples, see Paginating Through Lists Using Cursor Pagination

Using Offset Pagination

If you do not opt-in to cursor pagination as described above, offset pagination will be used by default.

By default, most list endpoints return a maximum of 100 records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request URL parameters. Example: per_page=50. However, you can't exceed 100 records per page on most endpoints.

When the response exceeds the per-page maximum, you can paginate through the records by incrementing the page parameter. Example: page=3. List results include next_page and previous_page URLs in the response body for easier navigation:

{
  "users": [ ... ],
  "count": 1234,
  "next_page": "https://account.zendesk.com/api/v2/users.json?page=2",
  "previous_page": null
}

Stop paging when the next_page attribute is null. For more information, see Paginating Through Lists Using Offset Pagination

Inaccuracies may be introduced in pages because of the limitations of API pagination. For example, duplicate results can occur which can be usually avoided by explicitly ordering the results. For more information and options, see Limitations of API pagination and Understanding the limitations of offset pagination.

Some lists can be ordered by transmitting a sort_order=desc or sort_order=asc parameter to the end point. Whether a specific list can be ordered is specified in the documentation for that specific resource.

Some endpoints limit the page number, or rate limit requests above a certain page number. See the documentation for the specific endpoint.

Other Pagination Methods

Certain endpoints use different pagination methods:

  • Incremental export endpoints use a variant of cursor pagination with some differences. See Pagination in the Incremental Export documentation for more information.
  • The List All Ticket Audits endpoint uses a variant of cursor pagination with some differences. See Pagination in the List All Ticket Audits documentation.

Legal notices

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our API Restrictions and Responsibilities, in our Change Policy, and in the other documentation we provide you. You must also comply with the restrictions set forth in the Zendesk Master Subscription Agreement and the Zendesk Privacy Policy, in all uses of the API. If Zendesk believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.