Documentation conventions

Endpoints

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

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

The .json extension is optional. If you omit it, you must include a Content-Type: application/json header in PUT, POST, and DELETE requests.

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

Placeholder values

In JSON samples, uppercase characters with underscore delimiters indicate a placeholder value.

{
  "name": "APP_NAME",
  "defaultLocale": "en",
  ...
}

In commands and other samples, {} in the path indicates a placeholder value that you must replace. Example:

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

Request and response body

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.

Endpoint access

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.