Zendesk - Love your helpdesk.

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 such that /users/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 Authentication. Security is provided via SSL if your Zendesk account plan supports it.

Authentication and Acting on Behalf of Another User

The API supports a header that allows you to execute API calls on behalf of another user. This is in the same fashion, that Zendesk allows you to “assume” another user when logged into the backend. This can be done using the X-On-Behalf-Of header when issuing the API calls. If, for example, you would like to create a request as “Joe Enduser” but do not know his password, you can do this by setting the header like so:

The X-On-Behalf-Of header

X-On-Behalf-Of: joe.enduser@theendusers.com

You would then do the actual authentication as an agent user, and set the above header to make the actions on behalf of the end user.

REST API Reading

We recommend using curl for testing out the various features that the REST API offers. A nice online option to curl is hurl. 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

This command issues a HTTP GET request to /users.xml (replace “helpdesk” in the URL with your help desk subdomain). 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.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 – PUTS, POSTS and DESTROY via JSON are not available.

Get details for a specific user

curl -u username:password http://helpdesk.zendesk.com/users/304.xml

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

Get a list of requests for a user using X-On-Behalf-Of

curl -u agentemail:password -H "X-On-Behalf-Of: enduseremail" http://helpdesk.zendesk.com/requests.xml

Uses the agent credentials for authentication and executes the action as if done by the end user.

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”, such that 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”. 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”.

Examples

POST (create) example – create new ticket

curl -u username:password -H "Content-Type: application/xml" \
-d "<ticket><description>Test</description><requester_id>54</requester_id></ticket>" \
-X POST http://helpdesk.zendesk.com/tickets.xml

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

It may be easier to have the XML fragment in a file rather than type it into the command line, you can do this using curl also:

POST (create) example – create new ticket from file

curl -u username:password -H "Content-Type: application/xml" \
-d @sample.xml -X POST http://helpdesk.zendesk.com/tickets.xml

Where the contents of sample.xml is:

<ticket>
  <description>Test</description>
  <requester_id>54</requester_id>
</ticket>

PUT (update) example – change ticket priority

curl -u username:password -H "Content-Type: application/xml" \
-d "<ticket><priority_id>4</priority_id></ticket>" \
-X PUT http://helpdesk.zendesk.com/tickets/5.xml

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

PUT (update) example – add comment to ticket

curl -u username:password -H "Content-Type: application/xml" \
-d "<comment><value>Some comment</value></comment> \
-X PUT http://helpdesk.zendesk.com/tickets/5.xml

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.

DELETE example – removing an entry

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

This example deletes the forum topic entry with ID 5