Introduction

Zendesk is a customer support platform that supports more than 40,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 described below, to understand how to be a good API citizen and to understand general restrictions and concerns.

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 and 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.

When documenting a resource, we use curly braces for identifiers, like {subdomain} when talking about the URL for your Zendesk account, i.e. https://{subdomain}.zendesk.com/api/v2/users/me.json

Change Policy

Zendesk may modify the attributes and resources available to the API and our policies related to access and use of the API from time to time without advance notice. Zendesk will use commercially reasonable efforts to notify you of any modifications to the API or policies through notifications or posts on the Zendesk Developer Website. Zendesk also tracks deprecation of attributes of the API on its Changes Roadmap. Modification of the API may have an adverse effect on Zendesk Applications, including but not limited to changing the manner in which Zendesk Applications communicate with the API and display or transmit Your Data. Zendesk will not be liable to you or any third party for such modifications or any adverse effects resulting from such modifications.

Security and Authentication

This API is an SSL-only API, regardless of how you may have your account configured. You must be a verified user to make API requests. You can authorize against the API using either basic authentication with your username and password credentials, or with a username and API token. The token is configurable in your Zendesk account under Settings > Channels > API.

If using the API token, use the following authentication format:

{email_address}/token:{api_token}

Using curl

curl -u {email_address}/token:{api_token} https://{yourdomain}.zendesk.com/api/v2/...

Example:

curl -u jane@voyager.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://janeway.zendesk.com/api/v2/users.json

With HTTP authentication, the slash character in {email_address}/token must be URL-encoded as %2F.

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 in order 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 will respond with a HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in. Further, the response will have a Retry-After header that tells you for how many seconds to sleep before retrying. You should anticipate this in your API client for the smoothest possible ride. See Best practices for avoiding rate limiting.

Headers

This is a JSON-only API. You must supply a Content-Type: application/json header on PUT and POST operations. You must set a Accept: application/json header on all requests. You may get a text/plain response in case of error, e.g. in case of a bad request, you should treat this as an error you need to take action on.

Common Response Structures

We respond to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, we will render the resulting JSON representation in the response body and set a Location header pointing to the resource, e.g:

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"
  }
}

Our time stamp format follows ISO8601 and we will always be serving UTC.

We respond to unsuccessful requests with HTTP status codes in the 400 range. The response may be content type text/plain for API level error messages (e.g. when trying to call the API without SSL). The response will be content type application/json for business level error messages. The latter contains a JSON hash with elaborate error messages to supplement the HTTP status code:

{
  "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've probably made a syntax error in your REST call. This is a common response if you try to make a request to a nonexistent Zendesk instance.

If you ever experience responses with status codes in the 500 range, Zendesk may be experiencing internal issues or having a scheduled maintenance (during which we send a 503 Service Unavailable status code).

Please check @zendeskops and our status page in such cases for any known issues.

When building an API client, we advice treating any 500 status codes as a warning/temporary state, if however, the status persists and we do not have an publicly announced maintenance or service disruption, then you should contact us at support@zendesk.com to initiate an investigation.

Collections

Collections return a maximum of 100 records per page, and by default return 100 records per page. You can set this on a per request basis by passing e.g. per_page=50 in the request parameters. You iterate the collection by incrementing the page attribute, e.g. page=3. Collections also include links in the response body for easier navigation, generally they are on this structure:

{
  "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.

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

Zendesk Tutorials, Samples, and Clients

API Clients from the Zendesk Developer Community

We welcome all contributions. Please contact api@zendesk.com to add your API client to the list.

comments powered by Disqus