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.
API Throttle
To ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain threshold in terms of a maximum of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a HTTP 503 response code and a text body of “Number of allowed API requests per minute exceeded”
We encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).
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.comYou 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.xmlThis 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.jsonThis 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.xmlIf 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.xmlUses 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.xmlThis 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.xmlWhere 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.xmlSets 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.xmlAdds 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.xmlThis example deletes the forum topic entry with ID 5
