Zendesk Support is a customer support platform that supports more than 80,000 businesses and over 300 million end users in 150 countries around the globe. Many of these businesses use the Zendesk API to automate and enhance their customer support with Zendesk Support.


This is the documentation for the Zendesk v2 API. Read the contents of this page carefully, including the Restrictions and Responsibilities, to understand how to be a good API citizen.

We make changes to the APIs from time to time. For more information, see API Changes.

The Zendesk API consists of several different APIs. Use the dropdown menu to select one:


The API is a JSON API. XML is not supported. To learn more, see Working with JSON.

Endpoints are documented with the HTTP method for the request and a partial resource identifier. Example:

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

Prepend your Zendesk Support URL to the resource identifier to get the full endpoint URL:

Curly braces, {}, indicate values you have to supply. Example:

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

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.

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

This is an SSL-only API, regardless of how your account is configured. You must be a verified user to make API requests. You can authorize against the API using either basic authentication with your email address and password, with your email address and an API token, or with an OAuth access token.

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 basic authentication or a Zendesk API token. For more information and a tutorial, see Making cross-origin, browser-side API requests in the Zendesk API guide.

Basic authentication

Password access must be enabled in the Zendesk Support admin interface at Admin > Channels > API.

Use the following authentication format with your email address and password:


curl -u

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.

API token

API tokens are managed in the Zendesk 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.

Use the following authentication format with your email address and an API token:


curl -u

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

OAuth access token

The Zendesk API supports OAuth authorization flows. Learn more.

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}

curl -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Rate Limits

This API is rate limited. We only allow a certain number of requests per minute depending on your plan and the endpoint. We reserve the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients. As an API consumer, you should expect to be able to make the following number of requests per minute:

Plan Requests per minute
Essential 10
Team 200
Professional 400
Enterprise 700
High Volume API Add-On (Professional or Enterprise) 2500

The Add-On increases a qualifying plan's limit to 2500 requests per minute. It doesn't add an additional 2500 requests to the plan's limit.

As well, each endpoint can have its own rate limit. For example, there is a rate limit of 30 updates with a comment to the same ticket by the same agent within a 10-minute window. See Endpoint-specific rate limits below.

As of February 1, 2017, REST API calls made by Zendesk apps will also be subject to an additional rate limit of 700 requests per 5 minutes per user. See Apps - Working with requests.

You can compare your activity in the last 24 hours with the Core API against your rate limit. See Tracking API activity against your rate limit.

You can use the following response headers to confirm the account's current rate limit and monitor the number of requests remaining in the current minute:

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

Notwithstanding the limits specified in this document, the system might still limit requests if it detects an unusual spike in requests from all sources for the account, including internal product requests. This can happen in a denial-of-service attack, for example. The account-wide limit is 100,000 requests per minute.

If the rate limit is exceeded, the API responds with a HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in. The response has a Retry-After header that tells you for how many seconds to wait before retrying. You should anticipate this in your API client for the smoothest possible ride. See Best practices for avoiding rate limiting.

Endpoint-specific rate limits
Endpoint name Endpoint Rate limit
Update Ticket PUT /api/v2/tickets/{id}.json 30 per 10 mins
Incremental Exports global limit GET /api/v2/incremental/* 10 per 1 min
Incremental Exports with High Volume add-on GET /api/v2/incremental/* 30 per 1 min
Execute User View GET /api/v2/user_views/{id}/execute.json 1 per 10 mins
Exporting Views GET /api/v2/views/{id}/export.json 100000 per 1 hour
Create Or Update User POST /api/v2/users/create_or_update.json 1 per 1 sec
Job limit

Some endpoints such as the Update Many Tickets endpoint queue background jobs to do the work. You can have up to 30 queued or running jobs at once. If you exceed the limit, you will receive a "TooManyJobs" error. Example:

  "description":"Too many UserBulkUpdateJobV2 jobs are currently queued or running. Try again later.",
  "current_job_ids":["14b1939441cb2e96d0c0835ede22ce03", ...]
CPU-time limit

Zendesk also tracks the CPU time an account consumes over time. If you're fetching large volumes of records and get a 429 error even though you're within the documented rate limits, it may be due to a CPU-time limit.

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.

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}

  "item": {
    "id": 123,
    "url": "https://{subdomain}",
    "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.


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.


A 429 error indicates that the rate limit has been exceeded. See Rate 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

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.


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": "",
  "previous_page": null

Stop paging when the next_page attribute is null. For more information, see Adding pagination to your code.

Inaccuracies may be introduced in pages because of the limitations of API pagination. For more information and options, see Limitations of API 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.

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.