Zendesk - Love your helpdesk.

we are hiring!
  1. Home
  2. Tour
  3. Extras
  4. Buzz

API

REST API: Tickets (incl. views)

A Zendesk ticket has several properties with values that are fixed:

Ticket status

Status Status ID
New 0
Open 1
Pending 2
Solved 3
Closed 4

Ticket Type

Type Type ID
(No Type Set) 0
Question 1
Incident 2
Problem 3
Task 4

Ticket priorities

Priority Priority ID
(No priority set) 0
Low 1
Normal 2
High 3
Urgent 4

Ticket via types

Via types identifies the ticket submission type. Tickets submitted via the REST API have via type “Web service” per default.

Via type Via type ID
Web form 0
Mail 4
Web service (e.g. REST) 5

Show

GET /tickets/#{id}.xml
Returns a single ticket.

Response

Status: 200

<ticket>
  <assigned-at>2007-06-03T22:15:44Z</assigned-at>
  <assignee-id>4</assignee-id>
  <assignee-updated-at/>
  <created-at>2007-06-03T20:15:44Z</created-at>
  <subject></subject>  
  <description>My printer is not working</description>
  <external-id/>
  <group-id>2</group-id>
  <id>303</id>
  <linked-id/>
  <priority-id>3</priority-id>
  <submitter-id>3</submitter-id>
  <status-id>1</status-id>
  <status-updated-at>2007-06-03T22:15:44Z</status-updated-at>
  <requester-id>3</requester-id>
  <requester-updated-at>2007-06-03T22:15:44Z</requester-updated-at>
  <ticket-type-id>2</ticket-type-id>
  <updated-at>2007-06-03T20:15:45Z</updated-at>
  <via-id>0</via-id>
  <current-tags>printer hp</current-tags>  
  <score>28</score>    
  <comments type="array">
    <comment>
      <author-id>3</author-id>
      <created-at>2007-06-03T20:15:45Z</created-at>
      <is-public>true</is-public>      
      <value>This is a comment</value>       
      <via-id>0</via-id>
      <via-reference-id/>
    </comment>
    <comment>
      <author-id>5</author-id>
      <created-at>2007-06-04T10:07:02Z</created-at>        
      <is-public>true</is-public>        
      <value>Make sure it is plugged in</value>        
      <via-id>0</via-id>
      <via-reference-id/>
    </comment>      
  </comments>
  <ticket-field-entries type="array">
    <ticket-field-entry>
      <ticket-field-id>139</ticket-field-id>
      <value>Please contact me by phone during work hours</value>
    </ticket-field-entry>
    <ticket-field-entry>
      <ticket-field-id>141</ticket-field-id>
      <value>true</value>
    </ticket-field-entry> 	
  </ticket-field-entries>
</ticket>

The first comment for a ticket is always equivalent to the ticket description.
If you have any custom fields in your zendesk, they will show up in the <ticket-field-entries> part of the document.

List

GET /rules/#{view-id}.xml
Listing of tickets are handled through views. A view defines conditions for tickets in a collection. An example of a view is “Unassigned tickets”. The list is paginated using offsets. If 15 elements are returned (the default page limit), use ?page=2 to check for the next 15 and so on.

Response

Status: 200

<tickets count="156">
  <ticket>
    ...
  </ticket>
  <ticket>
    ...
  </ticket>
</tickets>

Create

POST /tickets.xml
Creates a new ticket.

Request

<ticket>
  <description>My printer is not working</description>
  <requester-id>3</requester-id>
  <priority-id>4</priority-id>  
  <set-tags>pr facility</set-tags> 
  <fields>
    <514>
      This is a custom field text.
    </514>		
  </fields>         
</ticket>

Custom fields are updated through a custom field ID. Submitter of the entry is set to the authenticated user

Response

Status: 201
Location: http://account.zendesk.com/tickets/#{new-ticket-id}.xml

Create a new ticket with requester

POST /tickets.xml
Creates a new ticket AND creates a new user as the tickets requester, IF the user does not already exist (based on the requester email). If the requester exists, no user is created and the ticket is created with the existing user as requester.

Request

<ticket>
  <description>My printer is not always working</description>
  <priority-id>4</priority-id>  
  <requester-name>Mike Newson</requester-name>   
  <requester-email>mike@nowhere.com</requester-email>   
</ticket>

Submitter of the entry is set to the authenticated user.

Response

Status: 201
Location: http://account.zendesk.com/tickets/#{new-ticket-id}.xml

You can omit requester-name, if you want to set an existing user as requester through an email address

Update

PUT /tickets/#{id}.xml
Updates an existing ticket with new details from the submitted XML. In this example the assignee, tags and custom field with ID 514 are all updated.

Request

<ticket>
  <assignee-id>5</assignee-id>  
  <additional-tags>presales</additional-tags>
  <fields>
    <514>
      Hello
    </514>		
  </fields>          
</ticket>

You can remove tags with remove-tags and set tags with set-tags.
Note, the ID of a custom field is displayed on the page where you edit the custom field. Look for it in right hand sidebar.

Response

Status: 200

Add comment

PUT /tickets/#{id}.xml
Adds a comment to an existing ticket.

Request

<comment>
  <is-public>false</is-public>
  <value>Joe, you know the drill</value>
</comment>

Response

Status: 200

Comment is added to ticket. You can combine this action with a ticket update.

Destroy

DELETE /tickets/#{id}.xml
Destroys the ticket with the referenced ID.

Response

Status: 200

REST API: Tickets for end users

For authentication on behalf of an end user, as an agent, please refer to the section on REST authentication.

If you want to check tickets as an end user, or update one, this is perfectly possible. End users do not see as much information as agents, so the API is similar in approach to the above examples, with a few differences elaborated here. Most notably, you must use requests rather than tickets in the URL, but the result will still be XML formatted in the same way as tickets. The following sections give concrete examples.

Show

GET /requests/#{id}.xml
Returns a single request.

Response

Status: 200

<ticket>
  <created-at>2008-07-07T14:16:16Z</created-at>
  <description>All is broken!</description>
  <nice-id>575</nice-id>
  <organization-id nil="true"></organization-id>
  <via-id>0</via-id>
  <comments type="array">
    <comment>
      <author-id>328</author-id>
      <created-at>2008-07-07T14:16:16Z</created-at>
      <value>All is broken!</value>
    </comment>
  </comments>
</ticket>

The first comment for a request is always equivalent to the request description.

List

GET /requests.xml

This lists all the open requests for the end user. The list is paginated using offsets. If 15 elements are returned (the page limit), use ?page=2 to check for the next 15 and so on.

Response

Status: 200

<tickets>
  <ticket>
    ...
  </ticket>
  <ticket>
    ...
  </ticket>
</tickets>

Create

POST /requests.xml
Creates a new ticket. Be aware that the attribute you set when creating a ticket as an end user differs from what you’re used to when submitting tickets.

POST (create) example – create new request as end user:

curl -u username:password -H "Content-Type: application/xml" \
-d "<ticket><subject>Hello</subject><description>My message</description></ticket>" \
-X POST http://helpdesk.zendesk.com/requests

Thus the request structure is as follows:

Request

<ticket>
  <subject>Hello</subject>
  <description>My message</description>
</ticket>

Submitter and requester of the entry is set to the authenticated end user

Response

Status: 201
Location: http://account.zendesk.com/requests/#{new-ticket-id}.xml

Update

PUT /requests/#{id}.xml
Updates an existing request with another comment from the submitted XML.

Request

<comment>
  <value>All is good again</value>      
</comment>

Response

Status: 200

Destroy

DELETE /requests/#{id}.xml

Destroys the request with the referenced ID. Only admins can destroy tickets.

Response

Status: 200

Examples

Ruby script to create ticket with attachments using http and https and add comments
PHP script to create ticket with attachments and add comments

Mail API

REST API

Widgets

Remote Authentication

Targets