Tickets

Tickets are the means through which your end users (customers) communicate with agents in Zendesk Support. Tickets can originate via a number of support channels, including email, Help Center, chat, phone call, Twitter, Facebook, or the API. All tickets have a core set of properties.

Requesters and submitters

Every ticket has a requester and submitter. The user who is asking for support through a ticket is the requester. For most businesses that use Zendesk Support, the requester is a customer, but requesters can also be agents in your Zendesk Support instance.

The submitter is the user who created a ticket. By default, the requester of a ticket is the submitter. For example, if your customer emails your support address, this creates a ticket with the customer as both the requester and submitter. The requester will also appear as the author of the ticket's first comment.

However, a support agent can also create a ticket on behalf of a customer. If an agent creates a ticket through the web interface, the agent is set as the submitter. This can be accomplished equivalently through the API by passing the agent's user ID as the submitter_id when creating a ticket. In this case, the agent, who is the submitter, becomes the author of the ticket's first comment and the ticket shows that the agent created the ticket "on behalf of" the customer.

The submitter is always the first comment author

In the description above, we see that a ticket's first comment author can differ depending on who created the ticket. In both examples, whomever is the submitter becomes the first comment author. This will hold true for all tickets created in Zendesk Support with one exception.

Exception: If the ticket is created as a follow-up ticket (i.e., if the ticket is created using via_followup_source_id), then any submitter_id attribute is ignored. The API sets whoever created the follow-up ticket (for the API, always the authenticated user) as the first comment author.

Example: Creating a ticket through a custom web form

A very common use of the Zendesk API is to create a custom means of ticket submission, either through a website or other web property. In this case, it is desirable to show the ticket as if the customer submitted it directly. This is the default API behavior and requires only passing in requester information, ticket subject and description:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-d '{"ticket": {"requester": {"name": "The Customer", "email": "thecustomer@domain.com"}, "subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example: Creating a ticket on behalf of a customer

Now suppose that we want to record the fact that an agent submitted a ticket on behalf of a customer. To change the ticket submitter, pass the agent's user_id as the ticket submitter_id.

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-d '{"ticket": {"requester": {"name": "The Customer", "email": "thecustomer@domain.com"}, "submitter_id": 410989, "subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Description and first comment

When creating a ticket, use the comment key to set the ticket description, which is also the first comment. Example:

{"ticket": {"subject": "My printer is on fire!", "comment": {"body": "The smoke is very colorful."}}}

Note: Do not use the description key to set the first comment. The key is for reading purposes only. While it's possible to use the key to set the first comment, the functionality has limitations and is provided to support existing implementations.

Groups and assignees

Tickets in Zendesk Support can be passed to a group of agents unassigned, or to a specific agent in a specific group. A ticket can only be assigned to one assignee at a time.

Collaborators

Aside from the requester, a ticket can include other people in its communication, known as collaborators or cc's. Collaborators receive email notifications when tickets are updated. Collaborators can be either end users or agents.

Status

All tickets in Zendesk Support start out as New and progress through Open, Pending, Solved, and Closed states. A ticket must have an assignee in order to be solved.

JSON Format

Tickets are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating tickets
url string yes no The API url of this ticket
external_id string no no An id you can use to link Zendesk Support tickets to local records
type string no no The type of this ticket, i.e. "problem", "incident", "question" or "task"
subject string no no The value of the subject field for this ticket
raw_subject string no no The dynamic content placeholder, if present, or the "subject" value, if not. See Dynamic Content
description string yes no The first comment on the ticket
priority string no no Priority, defines the urgency with which the ticket should be addressed: "urgent", "high", "normal", "low"
status string no no The state of the ticket, "new", "open", "pending", "hold", "solved", "closed"
recipient string no no The original recipient e-mail address of the ticket
requester_id integer no yes The user who requested this ticket
submitter_id integer no no The user who submitted the ticket; The submitter always becomes the author of the first comment on the ticket.
assignee_id integer no no What agent is currently assigned to the ticket
organization_id integer no* no The organization of the requester. *Writable only when creating, not when updating
group_id integer no no The group this ticket is assigned to
collaborator_ids array no no Who are currently CC'ed on the ticket
forum_topic_id integer no no The topic this ticket originated from, if any
problem_id integer no no The problem this incident is linked to, if any
has_incidents boolean yes no Is true of this ticket has been marked as a problem, false otherwise
due_at date no no If this is a ticket of type "task" it has a due date. Due date format uses ISO 8601 format.
tags array no no The array of tags applied to this ticket
via Via yes no This object explains how the ticket was created
custom_fields array no no The custom fields of the ticket
satisfaction_rating object yes no The satisfaction rating of the ticket, if it exists, or the state of satisfaction, 'offered' or 'unoffered'
sharing_agreement_ids array yes no The ids of the sharing agreements used for this ticket
followup_ids array yes no The ids of the followups created from this ticket - only applicable for closed tickets
ticket_form_id integer no no The id of the ticket form to render for this ticket - only applicable for enterprise accounts
brand_id integer no no The id of the brand this ticket is associated with - only applicable for enterprise accounts
allow_channelback boolean yes no Is false if channelback is disabled, true otherwise - only applicable for channels framework ticket
is_public boolean yes no Is true if any comments are public, false otherwise
created_at date yes no When this record was created
updated_at date yes no When this record last got updated

You can also include a comment_count property in the JSON objects returned by GET requests by sideloading it. Example:

GET /api/v2/tickets.json?include=comment_count

Example
{
  "id":               35436,
  "url":              "https://company.zendesk.com/api/v2/tickets/35436.json",
  "external_id":      "ahg35h3jh",
  "created_at":       "2009-07-20T22:55:29Z",
  "updated_at":       "2011-05-05T10:38:52Z",
  "type":             "incident",
  "subject":          "Help, my printer is on fire!",
  "raw_subject":      "{{dc.printer_on_fire}}",
  "description":      "The fire is very colorful.",
  "priority":         "high",
  "status":           "open",
  "recipient":        "support@company.com",
  "requester_id":     20978392,
  "submitter_id":     76872,
  "assignee_id":      235323,
  "organization_id":  509974,
  "group_id":         98738,
  "collaborator_ids": [35334, 234],
  "forum_topic_id":   72648221,
  "problem_id":       9873764,
  "has_incidents":    false,
  "due_at":           null,
  "tags":             ["enterprise", "other_tag"],
  "via": {
    "channel": "web"
  },
  "custom_fields": [
    {
      "id":    27642,
      "value": "745"
    },
    {
      "id":    27648,
      "value": "yes"
    }
  ],
  "satisfaction_rating": {
    "id": 1234,
    "score": "good",
    "comment": "Great support!"
  },
  "sharing_agreement_ids": [84432]
}

List Tickets

GET /api/v2/tickets.json

Tickets are ordered chronologically by created date, from oldest to newest. The first ticket listed may not be the absolute oldest ticket in your account due to ticket archiving. To get a list of all tickets in your account, use the Incremental Ticket Export endpoint.

For more filter options, use the Search API.

You can also sideload related records with the tickets. See Side-Loading.

Allowed for
  • Admins

Note that agents have access to the following endpoints:

GET /api/v2/organizations/{organization_id}/tickets.json

GET /api/v2/users/{user_id}/tickets/requested.json

GET /api/v2/users/{user_id}/tickets/ccd.json

GET /api/v2/users/{user_id}/tickets/assigned.json

GET /api/v2/tickets/recent.json

recent.json lists tickets that the requesting agent recently viewed in the agent interface, not recently created or updated tickets (unless by the agent recently in the agent interface).

Available parameters
Name Type Required Comments
sort_by string no Possible values are assignee, assignee.name, created_at, group, id, locale, requester, requester.name, status, subject, updated_at
sort_order string no One of asc, desc. Defaults to asc

The query parameter is not supported for this endpoint. Use the Search API to narrow your results with query.

Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tickets": [
    {
      "id":      35436,
      "subject": "Help I need somebody!",
      ...
    },
    {
      "id":      20057623,
      "subject": "Not just anybody!",
      ...
    },
    ...
  ]
}

Show Ticket

GET /api/v2/tickets/{id}.json

Allowed For
  • Agents
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket": {
    "id":      35436,
    "subject": "My printer is on fire!",
    ...
  }
}

Show Multiple Tickets

GET /api/v2/tickets/show_many.json?ids={ids}

Accepts a comma separated list of ticket ids to return.

This endpoint will return up to 100 tickets records.

Allowed For:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/show_many.json?ids=1,2,3 \
  -v -u {email_address}:{password}
Example Response

See Listing Tickets

Create Ticket

POST /api/v2/tickets.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}' \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json

{
  "ticket": {
    "id":      35436,
    "subject": "My printer is on fire!",
    ...
  }
}
Request parameters

The POST request takes one parameter, a ticket object that lists the values to set when the ticket is created.

Name Description
subject The subject of the ticket.
comment Required. A comment object that describes the problem, incident, question, or task. See Ticket comments in Audit Events.
requester_id The numeric ID of the user asking for support through the ticket.
submitter_id The numeric ID of the user submitting the ticket.
assignee_id The numeric ID of the agent to assign the ticket to.
group_id The numeric ID of the group to assign the ticket to.
collaborator_ids An array of the numeric IDs of agents or end-users to CC on the ticket. An email notification is sent to them when the ticket is created.
collaborators An array of numeric IDs, emails, or objects containing name and email properties. See Setting Collaborators. An email notification is sent to them when the ticket is created.
type Allowed values are problem, incident, question, or task.
priority Allowed values are urgent, high, normal, or low.
status Allowed values are new, open, pending, hold, solved or closed. Is set to new if status is not specified.
tags An array of tags to add to the ticket.
external_id An ID to link Zendesk Support tickets to local records.
forum_topic_id The numeric ID of the topic the ticket originated from, if any.
problem_id For tickets of type "incident", the numeric ID of the problem the incident is linked to, if any.
due_at For tickets of type "task", the due date of the task. Accepts the ISO 8601 date format (yyyy-mm-dd).
ticket_form_id (Enterprise only) The id of the ticket form to render for the ticket.
custom_fields An array of the custom fields of the ticket. See below for details.
via_followup_source_id The id of a closed ticket for a follow-up ticket. See Creating Follow-up Tickets.
sharing_agreement_ids An array of the numeric IDs of sharing agreements.
Example request
{
  "ticket": {
    "subject":  "My printer is on fire!",
    "comment":  { "body": "The smoke is very colorful." },
    "priority": "urgent"
  }
}

Note: Submitting a ticket with HTML data will not result in the HTML being stripped out.

Setting custom field values

To set the value of one or more custom fields in the new ticket, specify an array of objects consisting of id and value properties. For text or numeric fields, specify text or numbers for the value property:

 "custom_fields": [{"id": 25356371, "value": "I bought it at Buy More."}, ...]

For fields with values defined by tags, such as drop-down lists, specify the option's tag name for the value property, not the option text displayed in the list. For example, if the option's display text is "HD 3000 color printer" and its tag is hd_3000, set the custom field's value as follows:

  "custom_fields": [{"id": 21938362, "value": "hd_3000"}]
Creating follow-up tickets

Once a ticket is closed (as distinct from solved), it can't be reopened. However, you can create a new ticket that references the closed ticket. To create the follow-up ticket, include a via_followup_source_id parameter that specifies the closed ticket. Example:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"via_followup_source_id": 103, "comment": {"body": "My printer is still too hot!"}}}' \
  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"

The parameter only works with closed tickets. It has no effect with other tickets.

By default, the first comment author is the authenticated user making the API request. To set a different author, include an author_id property in the comment object.

Create ticket asynchronously

Ticket creation can sometimes take a while because of complex business rules. Asynchronous creation allows you to get the response back quickly and queues a background job to do the actual work.

To make an asynchronous request, simply add the parameter async in your request.

POST api/v2/tickets.json?async=true

As soon as the request is received, it returns a 202 Accepted. The response includes the new ticket id with a job_status JSON object. However, you may not be able to fetch the ticket until the job is done.

Note: Some ticket id numbers may get skipped if ticket creation fails.

Create Many Tickets

POST /api/v2/tickets/create_many.json

Allowed For
  • Agents
Example request
{
  "tickets": [
    {
      "subject":  "My printer is on fire!",
      "comment":  { "body": "The smoke is very colorful." },
      "priority": "urgent"
    },
    {
      "subject":  "Help",
      "comment":  { "body": "This is a comment" },
      "priority": "normal"
    }
  ]
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/create_many.json \
  -d '{"tickets": [{"subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}, {"subject": "Help!", "comment": { "body": "Help I need somebody." }}]}' \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Update Ticket

PUT /api/v2/tickets/{id}.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"status": "open", "comment": { "body": "The smoke is very colorful.", "author_id": 494820284 }}}' \
  -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK

{
  "ticket": {
     "id":      35436,
     "subject": "My printer is on fire!",
     "status":  "open",
     ...
  },
  "audit": {
     "events": [...],
     ...
  }
}
Request parameters

The PUT request takes one parameter, a ticket object that lists the values to update. All properties are optional.

Name Description
subject The subject of the ticket.
comment An object that adds a comment to the ticket. See Ticket comments in Audit Events.
requester_id The numeric ID of the user asking for support through the ticket.
assignee_id The numeric ID of the agent to assign the ticket to.
assignee_email The email address of the agent to assign the ticket to.
group_id The numeric ID of the group to assign the ticket to.
collaborator_ids An array of the numeric IDs of agents or end-users to CC. Note that this replaces any existing collaborators. An email notification is sent to them when the ticket is created.
collaborators An array of numeric IDs, emails, or objects containing name and email properties. See Setting Collaborators. An email notification is sent to them when the ticket is updated.
additional_collaborators An array of numeric IDs, emails, or objects containing name and email properties. See Setting Collaborators. An email notification is sent to them when the ticket is updated.
type Allowed values are problem, incident, question, or task.
priority Allowed values are urgent, high, normal, or low.
status Allowed values are open, pending, hold, solved or closed.
tags An array of tags to add to the ticket. Note that the tags replace any existing tags. To keep existing tags, see Updating tag lists
external_id An ID to link tickets to local records.
forum_topic_id The numeric ID of the topic the ticket originated from, if any.
problem_id For tickets of type "incident", the numeric ID of the problem the incident is linked to, if any.
due_at For tickets of type "task", the due date of the task. Accepts the ISO 8601 date format (yyyy-mm-dd).
custom_fields An array of the custom field objects consisting of ids and values. Any tags defined with the custom field replace existing tags.
updated_stamp Datetime of last update received from API. See safe_update param.
safe_update Optional boolean. Prevents updates with outdated ticket data (updated_stamp param required when true)
sharing_agreement_ids An array of the numeric IDs of sharing agreements. Note that this replaces any existing agreements.
Example request
{
  "ticket": {
    "comment": { "body": "Thanks for choosing Acme Jet Motors.", "public": true },
    "status":  "solved"
  }
}

Update Many Tickets

PUT /api/v2/tickets/update_many.json

PUT /api/v2/tickets/update_many.json?ids={ids}

Accepts an array of up to 100 ticket objects, or a comma-separated list of up to 100 ticket ids.

Allowed For
  • Agents
Bulk updates

To make the same change to multiple tickets, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/tickets/update_many.json?ids=1,2,3

{
  "ticket": {
    "status": "solved"
  }
}
Batch updates

To make different changes to multiple tickets, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/tickets/update_many.json

{
  "tickets": [
    { "id": 1, "status": "solved" },
    { "id": 2, "status": "pending" }
  ]
}
Updating tag lists

You can use the bulk update format to add or remove tags to the tag list of each ticket without overwriting the existing tags. To do so, include the additional_tags or remove_tags property in the ticket object. Example:

curl https://{subdomain}.zendesk.com/api/v2/tickets/update_many.json?ids=1,2,3 \
  -d '{"ticket": {"additional_tags":["a_new_tag"]}}' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X PUT

The additional_tags or remove_tags properties only work with bulk updates, not batch updates.

Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/update_many.json?ids=1,2,3 \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X PUT \
  -d '{"ticket": {"status": "solved"}}'
curl https://{subdomain}.zendesk.com/api/v2/tickets/update_many.json \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X PUT \
  -d '{"tickets": [{"id": 1, "status": "solved"}, {"id": 2, "status": "pending"}]}'
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Protect against ticket update collisions

When updating or bulk updating tickets, the updated_stamp and safe_update properties can be used to ensure updates only occur for tickets with matching updated_at datetime values.

When the safe_update property has a value of true, the updated_stamp property is required, and only if the updated_at datetime value on the ticket matches the updated_stamp value will the ticket be updated.

When updating a single ticket, the response code will indicate if the ticket was successfully updated.

Example request
{
  "ticket": {
    "subject":"Updated Subject",
    "updated_stamp":"2015-10-14T16:53:51Z",
    "safe_update":"true",
    ...
  }
}
Example safe update error response

If the updated_stamp property does not match the updated_at datetime value for the ticket the update operation will fail and an UpdateConflict error response will be sent

Status: 409 Conflict
{
   "description": "Safe Update prevented the update due to outdated ticket data.
                   Please fetch the latest ticket data and try again.",
   "error": "UpdateConflict"
}

When bulk updating tickets, individual ticket objects can also make use of the safe_update and updated_stamp properties.

If any of the tickets in the bulk operation fail to update due to the updated_stamp property not matching the ticket's updated_at datetime value an UpdateConflict error response will be returned in the Job Status.

Example request
{
  "tickets": [
    {
      "id":"9999",
      "subject":"Ticket 9999 Subject Update",
      "updated_stamp":"2015-10-14T16:58:42Z",
      "safe_update":"true"
    },
    {
      "id":"10",
      "subject":"Ticket 10 Subject Update",
      "updated_stamp":"2015-09-24T21:52:46Z",
      "safe_update":"true"
    }
  ]
}
Example Job Status safe update error response
{
  "job_status": {
    "results": [
      {
        "index": 0
        "error": "UpdateConflict",
        "id": 9999,
        "details":"Safe Update prevented the update due to outdated ticket data. Please fetch the latest ticket data and try again."
      }
    ],
    ...
  }
}

Mark Ticket as Spam and Suspend Requester

PUT /api/v2/tickets/{id}/mark_as_spam.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/mark_as_spam.json \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response
Status: 200 OK

Bulk Mark Tickets as Spam

PUT /api/v2/tickets/mark_many_as_spam.json?ids={ids}

Accepts a comma-separated list of up to 100 ticket ids.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/mark_many_as_spam.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X PUT -d '{}' -H "Content-Type: application/json"
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Merge Tickets into Target Ticket

POST /api/v2/tickets/{id}/merge.json

Merges one or more tickets into the {id} target ticket.

See Merging Tickets for ticket merging rules. Note that any attachment to the source ticket is copied to the target ticket.

Allowed For
  • Agents

Agents in the Enterprise account must have merge permissions. See Creating custom roles and assigning agents (Enterprise).

Available parameters

The request takes a data object with the following properties:

Name Type Required Comments
ids array yes Ids of tickets to merge into the target ticket
target_comment string no Private comment to add to the target ticket
source_comment string no Private comment to add to the source ticket

The comments are optional but strongly recommended.

Example

{
  "ids": [123, 234, 789]
  "target_comment": "Combining with #123, #456, #789",
  "source_comment": "Closing in favor of #111"
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/merge.json \
  -v -u {email_address}:{password} -X POST \
  -d '{"ids": [123, 456, 789], "source_comment": "Closing in favor of #111", "target_comment": "Combining with #123, #456, #789"}' \
  -H "Content-Type: application/json"
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Ticket Related Information

GET /api/v2/tickets/{id}/related.json

Allowed For
  • Agents
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/related.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "topic_id": null,
  "jira_issue_ids": [],
  "followup_source_ids": [],
  "from_archive": false,
  "incidents": 7,
  "twitter": {
    "handle_id": 10,
    "profile": {
      "created_at": "2013/01/08 23:24:49 -0800",
      "description": "Zendesk is the leading ...",
      ...
    },
    "direct": false
  }
}

Setting collaborators

When creating or updating a ticket, you can set collaborators on a ticket using one of three parameters: collaborator_ids, collaborators or additional_collaborators. The collaborators parameter provides more flexibility, as outlined below.

An email notification is sent to the collaborators when the ticket is created or updated.

Note: Setting collaborators or collaborator_ids when updating a ticket replaces existing collaborators. Make sure to include existing collaborators in the update request if you want to retain them on the ticket. Use additional_collaborators instead if you only want to add more collaborators.

The collaborator_ids parameter is a basic option that takes an array of user ids.

Example request
{
  "ticket": {
    "collaborator_ids": [562624, 624562, 243642]
  }
}

The collaborators parameter is a more flexible option. It takes an array consisting of a combination of user ids, email addresses, or objects containing a name and email property.

  • 562562562
  • "someone@example.com"
  • { "name": "Someone Special", "email": "someone@example.com" }

Use an object to create the user on the fly with the appropriate name in Zendesk Support.

Example request
{
  "ticket": {
    "collaborators": [ 562, "someone@example.com", { "name": "Someone Else", "email": "else@example.com" } ]
  }
}

The additional_collaborators parameter is used to add additional collaborators. It preserves the existing collaborators, and adds new collaborators to the ticket. It takes an array consisting of a combination of user ids, email addresses, or objects containing a name and email property.

Example request
{
  "ticket": {
    "additional_collaborators": [ 562, "someone@example.com", { "name": "Someone Else", "email": "else@example.com" } ]
  }
}

Even if you use the collaborators parameter, the JSON response will specify the new or updated collaborators as an array of user ids in the collaborator_ids property. The response doesn't have a collaborators property.

Setting metadata

When you create or update a ticket, an Audit gets generated if the ticket properties have changed. On each such audit, you can add up to 1 kilobyte of custom metadata. You can use this to build your own integrations or apps. Note: If your update does not change the ticket, this will not create an Audit and will not save your metadata.

Example request
{
  "ticket": {
    "metadata": { "time_spent": "4m12s", "account": "integrations" },
    "comment":  { "body": "Please press play on tape now" },
    "status":   "pending"
  }
}

Note that metadata can only be set as part of other regular ticket updates as they are associated to a such rather than just the ticket. Zendesk Support also adds metadata on each ticket update, and the resulting audit JSON structure looks like this:

{
  "audit": {
    "id":         35436,
    "ticket_id":  47,
    "created_at": "2012-04-20T22:55:29Z",
    "author_id":  35436,
    "metadata": {
      "custom": {
        "time_spent": "4m12s",
        "account": "integrations"
      },
      "system": {
        "ip_address": "184.106.40.75",
        "location": "United States",
        "longitude": -97,
        "latitude": 38,
        "client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3)"
      }
    },
    "via": {
      "channel": "web"
    },
    "events": [
      {
        "id":          1564245,
        "type":        "Comment"
        "body":        "Please press play on tape now",
        "public":      true,
        "attachments": []
      },
      ...
    ]
  }
}

Attaching files

When creating and updating tickets, you may attach files by passing in an array of the tokens received from uploading the files. For the upload attachment to succeed when updating a ticket, a comment must be included.

To get the token of an upload, see the Attachments section on uploading files.

The upload tokens are single use only. After a token is used to attach a file to a ticket comment, that token cannot be used to attach the same upload to an additional ticket comment.

Example request
{
  "ticket": {
    "comment":  { "body": "Please press play on tape now", "uploads":  ["vz7ll9ud8oofowy"] }
  }
}

Creating a ticket with a new requester

Requesters can explicitly be created handling tickets. The name, email, and locale id can be set on the new requester, with the name and email being required.

To get the locale id, see the Locales section.

Example request
{
  "ticket": {
    "subject":   "Hello",
    "comment":   { "body": "Some question" },
    "requester": { "locale_id": 8, "name": "Pablo", "email": "pablito@example.org" }
  }
}

If the requester's identity doesn't exist, we will create a new user on their behalf. This user will need to verify their identity to view their requests. Please note, if a user already exists with the given email address then we will use that user, no updates will be made to existing users during the ticket create process. In this approach, only the email attribute is required.

Setting ticket fields

When creating or updating a ticket, Ticket Fields can be set by passing in an array of objects in the format { id: {id}, value: {value} }.

Example request
{
  "ticket": {
    "subject": "Hello",
    "comment": { "body": "Some question" },
    "custom_fields": [{ "id": 34, "value": "I need help!" }]
  }
}

Delete Ticket

DELETE /api/v2/tickets/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content

Bulk Delete Tickets

DELETE /api/v2/tickets/destroy_many.json?ids={ids}

Accepts a comma-separated list of up to 100 ticket ids.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/destroy_many.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 200 OK

{ticket_pagination_count_method}/user=#{user.id}")

List Collaborators for a Ticket

GET /api/v2/tickets/{id}/collaborators.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/collaborators.json \
  -v -u {email_address}:{password}
Example Response
Status: 200

{
  "users": [
    {
      "id": 223443,
      "name": "Johnny Agent",
      ...
    },
    {
      "id": 8678530,
      "name": "Peter Admin",
      ...
    }
  ]
}

Listing Ticket Incidents

GET /api/v2/tickets/{id}/incidents.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/12345/incidents.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tickets": [
    {
      "id":          33,
      "subject":     "My printer is on fire",
      "description": "The fire is very colorful.",
      "status":      "open",
      ...
    },
    {
      "id":          34,
      "subject":     "The printer is on fire over here too",
      "description": "The fire is very colorful as well!",
      "status":      "pending",
      ...
    },
  ]
}

Listing Ticket Problems

GET /api/v2/problems.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/problems.json \
  -v -u {email_address}:{password}
Example Response

Note that the response will always be ordered by updated_at, in a descending order

Status: 200 OK

{
  "tickets": [
    {
      "id":          33,
      "subject":     "My printer is on fire",
      "description": "The fire is very colorful.",
      "status":      "open",
      ...
    },
    {
      "id":          34,
      "subject":     "The printer is on fire over here too",
      "description": "The fire is very colorful as well!",
      "status":      "pending",
      ...
    },
  ]
}

Autocomplete Problems

POST /api/v2/problems/autocomplete.json?text={name}

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/problems/autocomplete.json \
  -X POST -d '{"text": "att"}' -H "Content-Type: application/json" \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tickets": [
    { .. ticket record as in the #index method .. },
    { .. ticket record as in the #index method .. }
  ]
}