Requests

Request format

The Zendesk API is a JSON API. You must supply a Content-Type: application/json header in PUT, POST, and DELETE 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 may 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.

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

The API responds to unsuccessful requests with HTTP status codes in the 400 range. See 400 range.

Status codes

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 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 indicates a conflict with the resource you're trying to create or update.

409 errors typically occur when two or more requests try to create or change the same resource simultaneously. While Zendesk APIs can handle concurrent requests, requests shouldn't change the same resource at the same time. To avoid 409 errors, serialize requests when possible. If you receive a 409 error, you can retry your request after resolving the conflict.

The Zendesk Ticketing API provides specific parameters to prevent conflicts when updating tickets. For more information, see Protecting against ticket update collisions.

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 Rate limits.

500 range

If you ever experience responses with status codes in the 500 range, the API may be experiencing internal issues or having a scheduled maintenance during which you might receive a 503 Service Unavailable status code.

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 Zendesk Customer Support.

If submitting a ticket to Zendesk, 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.