The Zendesk REST API

The Zendesk REST API allows developers to hook into Zendesk and connect it to third-party applications. Whether you're writing a plugin for an application or planning on hooking some internal application into Zendesk, the API can do it for you.

The REST API is implemented as plain XML or JSON over HTTP using all four REST commands - GET, POST, PUT and DELETE. Every resource, like Ticket, User or Tag, has their own URL and are manipulated in isolation. The API closely follows the REST principles and it's easy to use.

You can explore the GET part of the API through any browser. We recommend Firefox. Most URLs in Zendesk can be viewed in XML form by appending the URL with .xml - /tickets/4 becomes /users/4.xml if you want to see the XML version of the ticket.

Authentication

Use of the API is always through an existing user in Zendesk. There's no special API user. You get to see and work with what the user you are logging in to the API is allowed to. You're required to add user credentials via HTTP Basic Authentification. Security is provided via SSL if your Zendesk account plan supports it.

REST API Reading

We recommend using cURL for testing out the various features that the REST API offers. The REST API has two modes of actions for reading - show and list. Show returns a single record and list returns a collection. Usually, there's just a single show action for each resource, but several lists. You can easily explore REST API reading through a browser, as all these actions are done through GET.

Examples

GET a list of users - XML

curl -u username:password http://helpdesk.zendesk.com/users.xml \
-H "Accept: application/xml"

This command issues a HTTP GET request to /users.xml (replace "helpdesk" in the URL with your help desk name). If the REST API is enabled, it will return HTTP status code 200, and a XML document listing the users in your help desk - end users, agents and administrators. If nothing is found, a HTTP 404 "not found" response will be returned. This is equivalent to typing in the URL "http://helpdesk.zendesk.com/users.xml" in your browser, when logged on as the authenticated user.

GET a list of users - JSON

curl -u username:password http://helpdesk.zendesk.com/users.js  \
-H "Accept: application/json"

This is equivalent to the previous example, but returns the result as JSON instead of XML. Furthermore, you can specify a callback by appending "?callback=your_call_back_function" to the GET URL. See the Widgets section for JSON examples.
Most GET commands in Zendesk are available as JSON as well as XML.

Get details for a specific user

curl -u username:password http://helpdesk.zendesk.com/users/304.xml \
-H "Accept: application/xml"

If a user with ID 304 exists, an XML response is generated along with the status code "200 OK". The XML response contains the user data registered for the particular user. If nothing is found, the response HTTP 404 "not found" is returned.

API writing

When you're creating and updating REST resources, you'll be sending XML into Zendesk. Remember to add the header "Content-type: application/xml", so Zendesk knows that it's not regular HTML form-encoded data coming in. Then just include the XML of the resource in the body of your request, and you're done.

A succesful creation responds with the status code "201 Created". The URL of the new resource is located in the Location header (letting you know where to update your new resource in the future). Also included is the complete XML for the resource in the response. This is handy, as you can usually create a new resource with less than all its regular attributes, including attributes such as created-at.

Updating resources is done through the PUT command and against the URL of the resource you want to update. The response to a successful update is "200 OK".

Examples

POST (create) example - create new ticket

curl -u username:password -H "Accept: application/xml" -d "ticket[description]=Test" \
-d "ticket[requester_id]=54" -X POST http://helpdesk.zendesk.com/tickets

Creates a new ticket, requested by user ID 54 and with the authenticated user as submitter.

PUT (update) example - change ticket priority

curl -u username:password -H "Accept: application/xml" -d "ticket[priority_id]=4" \
-X PUT http://helpdesk.zendesk.com/tickets/5

Sets the priority of the ticket to 4 (Urgent).

PUT (update) example - add comment to ticket

curl -u username:password -H "Accept: application/xml" -d "comment[value]=My comment" \
-X PUT http://helpdesk.zendesk.com/tickets/5

Adds a comment to ticket ID 5, submitted by the authenticated user.

Deleting through the REST API

Finally, you can delete resources (if you're allowed to) using the DELETE command.

curl -u username:password -X DELETE http://helpdesk.zendesk.com/entries/5.xml

This example deletes the forum topic entry with ID 5