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