Introduction

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

The API

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.

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

image

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

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

GET /api/v2/help_center/articles.json

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

https://obscura.zendesk.com/api/v2/help_center/articles.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.

When documenting a resource, we use curly braces, {}, for identifiers. Example: https://{subdomain}.zendesk.com/api/v2/users/me.json.

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.

CORS requests are supported only for endpoints such as Help Center Search that don't require authentication. CORS requests are not supported for any endpoint that requires authentication.

Basic authentication

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

{email_address}:{password}

Example
curl -u jdoe@example.com:hdtR9Ve6 https://obscura.zendesk.com/api/v2/users.json

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

{email_address}/token:{api_token}

Example
curl -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://obscura.zendesk.com/api/v2/users.json

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. In your requests, specify the access token in an Authorization header as follows:

Authorization: Bearer {access_token}

Example
curl -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo" https://obscura.zendesk.com/api/v2/users.json

Rate Limiting

This API is rate limited. We only allow a certain number of requests per minute. 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 at least 200 requests per minute.

If the rate limit is exceeded, Zendesk 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.

Request Format

The Zendesk API is a JSON-only 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

Zendesk responds to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, Zendesk renders the resulting JSON representation in the response body and set 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"
  }
}

Time stamps use UTC time and their format is ISO 8601.

Zendesk responds to unsuccessful requests with HTTP status codes in the 400 range. 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 is a common response if you try to make a request to a nonexistent Zendesk instance.

If you experience responses with status codes in the 500 range, Zendesk may be experiencing internal issues or undergoing scheduled maintenance, during which we send a 503 Service Unavailable status code. 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 support@zendesk.com.

Pagination

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 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 Terms of Service 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.