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

Ticket status

Ticket Type

Ticket priorities

Ticket via types

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

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.

Note, you can’t have an assignee and no group on a ticket – an Agent needs to belong to a Group, to be assignable. If you don’t pass a group to a ticket, but only the agent via the API, Zendesk will simply pick the first group the agent is a member of. Also, if you only have one group in the system, we automatically assign to that group.

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

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

Response

Status: 201
Location: {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 ticket is set to the authenticated user.

Response

Status: 201
Location: {new-ticket-id}.xml

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

Create a new ticket from a Twitter status

POST /tickets.xml
Creates a new ticket where the subject and description are the contents of the Twitter status message.

Requires the Twitter status message ID and a Twitter account which has been configured with the Zendesk account. The list of configured Twitter accounts is available under /account/twitter_accounts.xml:

List configured Twitter accounts

<monitored-twitter-handles type="array" count="2">
  <monitored-twitter-handle>
    <id type="integer">2</id>
    <twitter-user-id type="integer">151356708</twitter-user-id>
    <screen-name>@zendesk</screen-name>
  </monitored-twitter-handle>
  <monitored-twitter-handle>
    <id type="integer">3</id>
    <twitter-user-id type="integer">429822864</twitter-user-id>
    <screen-name>@zendeskops</screen-name>
  </monitored-twitter-handle>
</monitored-twitter-handles>

If a user profile already exists in Zendesk with the same Twitter account as the Twitter status author, the new ticket is associated with this user profile.  A new user profile will be created if no user exists with the same Twitter account.

Request

<ticket>
  <twitter-status-message-id>8605426295771136</twitter-status-message-id>
  <monitored-twitter-handle-id>4</monitored-twitter-handle-id>
</ticket>

Submitter of the ticket is set to the authenticated user.

Response

Status: 201
Location: {new-ticket-id}.xml

The monitored-twitter-handle-id must be the id of a Twitter account which has been added to your Zendesk account.  This Twitter account is used to respond to the requester from Zendesk.

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

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 https://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: {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