DocumentationAPI Reference

Documentation conventions

Endpoints

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

GET /api/v2/help_center{/locale}/articles

You can optionally append .json to the resource name. All curl examples use this optional format for demonstration purposes:

curl https://{subdomain}.zendesk.com/api/v2/help_center/{locale}/articles.json \  -v -u {email_address}:{password}

Appending .json doesn't change the way the endpoint works in any way.

Zendesk recommends including a Content-Type: application/json header in PUT, POST, and DELETE requests if you omit .json. If you make a GET request with a web browser, you must include .json.

Prepend your Zendesk Support URL to the path to get the full endpoint URL. If example, if your Support URL is https://example.zendesk.com, then use the following endpoint URL:

https://example.zendesk.com/api/v2/help_center/en-us/articles.json

Placeholder values

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

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

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

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

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.

API schemas

The docs provide the API schema of every resource in tables called JSON Format. Each table lists the resource's properties and contains the following columns:

  • Name - Name of the property
  • Type - JSON data type of the property
  • Read-only - Whether the property can be set when creating or updating the resource
  • Mandatory - Whether the property is required when creating or updating the resource
  • Description - Notes about the property

Query parameters

Query parameters in the text are not URL encoded. However, they should always be URL encoded when used in a HTTP request to ensure the URL is correctly transmitted.

Most if not all popular languages and HTTP clients have built-in URL encoders so that you don't need to encode the parameters yourself. Examples:

curl

curl https://support.zendesk.com/api/v2/help_center/en-us/articles \  --get --data-urlencode "page[size]=2"

JavaScript

let params = new URLSearchParams("page[size]=2");const url = "https://support.zendesk.com/api/v2/help_center/en-us/articles?" + params;const request = new Request(url);

Python requests library

params = {'page[size]': 10}url = 'https://support.zendesk.com/api/v2/help_center/en-us/articles' response = requests.get(url, params=params)

Node Axios library

let params = { "page[size]": 10 }const url = "https://support.zendesk.com/api/v2/help_center/en-us/articles"const response = await axios.get(url, { params: params })