REST API: Tickets (incl. views)

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

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

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

Via types identifies the ticket submission type. Tickets submitted via the REST API have via type "Web service".

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

Show

GET /tickets/#{id}.xml

Returns a single ticket.

Response

Status: 200 OK

<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 OK

<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 Created
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 Created
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</assigne-id>  
  <additional-tags>presales</additional-tags>
  <fields>
    <514>
      Hello
    </514>		
  </fields>          
</ticket>


Response
Status: 200 OK

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 OK
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 OK	




REST API: Tickets for end users

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 OK

<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 OK

<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 differes from what you're used to when submitting tickets.

POST (create) example - create new request as end user
curl -u username:password -H "Accept: application/xml" -d "comment[value]=Stuff" \
-X POST http://helpdesk.zendesk.com/requests


Thus the request structure is as follows:

Request
<comment>
  <value>My printer is not working</value>
</comment>


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

Response
Status: 201 Created
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 OK

Destroy
DELETE /requests/#{id}.xml
Destroys the request with the referenced ID. Only admins can destroy tickets.
Response
Status: 200 OK

REST API: Tickets (incl. views)

Ticket status

Ticket priorities

Ticket via types

Show

GET /tickets/#{id}.xml

Response

List

GET /rules/#{view-id}.xml

Response

Create

POST /tickets.xml

Request

Response

Create a new ticket with requester

POST /tickets.xml

Request

Response

Update

PUT /tickets/#{id}.xml

Request

Response

Add comment

PUT /tickets/#{id}.xml

Request

Response

Destroy

DELETE /tickets/#{id}.xml

Response

REST API: Tickets for end users

Show

GET /requests/#{id}.xml

Response

List

GET /requests.xml

Response

Create

POST /requests.xml

POST (create) example - create new request as end user

Request

Response

Update

PUT /requests/#{id}.xml

Request

Response

Destroy

DELETE /requests/#{id}.xml

Response

Mail API

REST API

Widgets