API

Operations documentation page for Zendesk API

Note

This is an informational page for the Zendesk api. It may not reflect the way we actually manage Zendesk api (and its tokens).

If you are looking for information about maintaining api tokens (creating, editing, etc.), please see API workflow

What is the Zendesk API

The Zendesk Support API is a collection of Zendesk endpoints you can use to get various information or do various tasks. It is quite robust and something we use from time to time.

What are Zendesk API tokens

Zendesk API tokens are used in authentication for Zendesk API requests. These tokens are always at the administrator level and cannot be issued at lower permission/role levels. As such, you should always use caution in using and issuing these tokens.

How to authenticate to the Zendesk API

Basic authentication

To authenticate using basic authentication, you’ll need to know your username (email) and password for your Zendesk account. With those in hand, you can either use those directly or encode the string into base64 (and use it in the headers).

Example of using it raw:


curl https://gitlab.zendesk.com/api/v2/users.json \
  -u jcolyer@gitlab.com:my_password

Example of using it via headers


echo 'jcolyer@gitlab.com:my_password' | base64
amNvbHllckBnaXRsYWIuY29tOm15X3Bhc3N3b3JkCg==

curl https://gitlab.zendesk.com/api/v2/users.json \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tOm15X3Bhc3N3b3JkCg=="

API token authentication

To authenticate via an API token, you’ll need to know your username and the API tokenh in question. With those in hadn, you can either use those directly or encode the string into base64 (and use it in the headers). When using an API token, you must add /token after your username.


curl https://gitlab.zendesk.com/api/v2/users.json \
  -u jcolyer@gitlab.com/token:api_token

Example of using it via headers


echo 'jcolyer@gitlab.com/token:api_token' | base64
amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=

curl https://gitlab.zendesk.com/api/v2/users.json \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

If you’ve followed the recommended setup and stored your credentials in environment variables, the call will be simplified to


curl -u $ZD_USERNAME/token:$ZD_TOKEN "$ZD_URL/users.json"

Oauth access token authentication

To use an Oauth access token, you’d first need to create an Oauth app in Zendesk (see Zendesk docs for more information). With the access token in hand, you would pass this into the headers.

Example of using it via headers


curl https://gitlab.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

How to use the Zendesk API

Note

This focuses solely on the Zendesk API via curl. For more information on using a library, check out the corresponding library’s documentation.

To get started, you would need to know the endpoint you wish to use. Generally speaking, the most common ones you might use for quick actions are:

For more administrative tasks, the common ones you might use are:

Once you have determined what you wish to do, go to the corresponding API endpoint documentation and make note of:

The request type
- GET
- POST
- PUT
- DELETE
The endpoint URL
Any required parameters

From there, you will craft a curl command in the format of:


curl ZENDESK_URL/api/v2/ENDPOINT \
  -X REQUEST_TYPE \
  -H HEADER_INFO \
  -u AUTHENTICATION \
  -d DATA_TO_USE

Where:

ZENDESK_URL is the URL of the Zendesk instance
ENDPOINT is the endpoint to use
-X REQUEST_TYPE is the request type from the documentation (not needed if making a GET request)
-H HEADER_INFO is any needed header information (not always needed)
-u AUTHENTICATION is the user/pass or user/token combo (not needed if using header based authentication)
-d DATE_TO_USE is the data to send with the request (not always needed)

As an example, if you wanted to get the details for automation 12345, your curl command might look like:


curl https://gitlab.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Likewise, if you wanted to update automation 12345 to set active to false (i.e. deactivate it), your curl command might look like:


curl https://gitlab.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"automation": {"active": false}}'

If we wanted to full on delete automation 12345, your curl command might look like:


curl https://gitlab.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X DELETE

Common use cases

For all examples:

12345 refers to the items ID number

Automations

List all


curl https://gitlab.zendesk.com/api/v2/automations \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Deactivate


curl https://gitlab.zendesk.com/api/v2/automations/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"automation": {"active": false}}'

Macros

List all


curl https://gitlab.zendesk.com/api/v2/macros \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/macros/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Deactivate


curl https://gitlab.zendesk.com/api/v2/macros/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"macro": {"active": false}}'

SLA Policies

List all


curl https://gitlab.zendesk.com/api/v2/slas/policies \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/slas/policies/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Tickets

List all


curl https://gitlab.zendesk.com/api/v2/tickets \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/tickets/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Change status to closed


curl https://gitlab.zendesk.com/api/v2/tickets/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"ticket": {"status": "closed"}}'

Triggers

List all


curl https://gitlab.zendesk.com/api/v2/triggers \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/triggers/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Deactivate


curl https://gitlab.zendesk.com/api/v2/triggers/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"trigger": {"active": false}}'

Views

List all


curl https://gitlab.zendesk.com/api/v2/views \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Show details


curl https://gitlab.zendesk.com/api/v2/views/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Deactivate


curl https://gitlab.zendesk.com/api/v2/views/12345 \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo=" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"trigger": {"active": false}}'

List tickets in a view


curl https://gitlab.zendesk.com/api/v2/views/12345/tickets \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Count tickets in a view


curl https://gitlab.zendesk.com/api/v2/views/12345/count \
  -H "Authorization: Basic amNvbHllckBnaXRsYWIuY29tL3Rva2VuOmFwaV90b2tlbgo="

Creating an API token

For information on creating an API token, please see Zendesk documentation.

Deleting an API token

For information on deleting an API token, please see Zendesk documentation.

Useful links

Last modified April 3, 2025: Migrating support readiness handbook to security (9196a840)

View page source - Edit this page - please contribute.