Tickets
Tickets are the means through which your end users (customers) communicate with agents in Zendesk Support. Tickets can originate from a number of channels, including email, Help Center, chat, phone call, Twitter, Facebook, or the API. All tickets have a core set of properties.
Tickets and Requests
Zendesk has both a Tickets API and a Requests API. A ticket is an agent's perspective on a ticket. A request is an end user's perspective on a ticket. End users can only see public comments and certain fields of a ticket. Therefore, use the Requests API to let end users view, update, and create tickets. Use the Tickets API described in the rest of this document to let agents and admins manage tickets.
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.
Description and first comment
When creating a ticket, use the comment
property 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."}}}
Important: Do not use the description
property to set the first comment. The property is for reading purposes only. While it's possible to use the property 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 with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
allow_attachments | boolean | true | false | Permission for agents to add add attachments to a comment. Defaults to true |
allow_channelback | boolean | true | false | Is false if channelback is disabled, true otherwise. Only applicable for channels framework ticket |
assignee_id | integer | false | false | The agent currently assigned to the ticket |
brand_id | integer | false | false | Enterprise only. The id of the brand this ticket is associated with |
collaborator_ids | array | false | false | The ids of users currently CC'ed on the ticket |
collaborators | array | false | false | POST requests only. Users to add as cc's when creating a ticket. See Setting Collaborators |
created_at | string | true | false | When this record was created |
custom_fields | array | false | false | Custom fields for the ticket. See Setting custom field values |
description | string | true | false | Read-only first comment on the ticket. When creating a ticket, use comment to set the description. See Description and first comment |
due_at | string | false | false | If this is a ticket of type "task" it has a due date. Due date format uses ISO 8601 format. |
email_cc_ids | array | false | false | The ids of agents or end users currently CC'ed on the ticket. See CCs and followers resources in the Support Help Center |
external_id | string | false | false | An id you can use to link Zendesk Support tickets to local records |
follower_ids | array | false | false | The ids of agents currently following the ticket. See CCs and followers resources |
followup_ids | array | true | false | The ids of the followups created from this ticket. Ids are only visible once the ticket is closed |
forum_topic_id | integer | true | false | The topic in the Zendesk Web portal this ticket originated from, if any. The Web portal is deprecated |
group_id | integer | false | false | The group this ticket is assigned to |
has_incidents | boolean | true | false | Is true if a ticket is a problem type and has one or more incidents linked to it. Otherwise, the value is false. |
id | integer | true | false | Automatically assigned when the ticket is created |
is_public | boolean | true | false | Is true if any comments are public, false otherwise |
macro_ids | array | false | false | POST requests only. List of macro IDs to be recorded in the ticket audit |
organization_id | integer | false | false | The organization of the requester. You can only specify the ID of an organization associated with the requester. See Organization Memberships |
priority | string | false | false | The urgency with which the ticket should be addressed. Allowed values are "urgent", "high", "normal", or "low". |
problem_id | integer | false | false | For tickets of type "incident", the ID of the problem the incident is linked to |
raw_subject | string | false | false | The dynamic content placeholder, if present, or the "subject" value, if not. See Dynamic Content |
recipient | string | false | false | The original recipient e-mail address of the ticket |
requester_id | integer | false | true | The user who requested this ticket |
satisfaction_rating | object | true | false | The satisfaction rating of the ticket, if it exists, or the state of satisfaction, "offered" or "unoffered" |
sharing_agreement_ids | array | true | false | The ids of the sharing agreements used for this ticket |
status | string | false | false | The state of the ticket. Allowed values are "new", "open", "pending", "hold", "solved", or "closed". |
subject | string | false | false | The value of the subject field for this ticket |
submitter_id | integer | false | false | The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket |
tags | array | false | false | The array of tags applied to this ticket |
ticket_form_id | integer | false | false | Enterprise only. The id of the ticket form to render for the ticket |
type | string | false | false | The type of this ticket. Allowed values are "problem", "incident", "question", or "task". |
updated_at | string | true | false | When this record last got updated |
url | string | true | false | The API url of this ticket |
via | object | false | false | For more information, see the Via object reference |
via_followup_source_id | integer | false | false | POST requests only. The id of a closed ticket when creating a follow-up ticket. See Creating a follow-up ticket |
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
{
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
List deleted tickets
GET /api/v2/deleted_tickets
Returns a maximum of 100 deleted tickets per page. See Pagination.
The results includes all deleted (and not yet archived) tickets that have not yet been scrubbed in the past 30 days. Archived tickets are not included in the results. See About archived tickets in the Support Help Center.
The tickets are ordered chronologically by created date, from oldest to newest. The first ticket listed may not be the oldest ticket in your account due to ticket archiving.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
sort_by | string | Query | false | Sort by. Allowed values are "id", "subject", or "deleted_at". |
sort_order | string | Query | false | Sort order. Defaults to "asc". Allowed values are "asc", or "desc". |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/deleted_tickets.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": 1,
"deleted_tickets": [
{
"actor": {
"id": 3946,
"name": "Taz Wombat"
},
"deleted_at": "20140704T15:37:04Z",
"id": 581,
"previous_state": "open",
"subject": "Wombat Party"
}
],
"next_page": null,
"previous_page": null
}
Delete multiple tickets permanently
DELETE /api/v2/deleted_tickets/destroy_many?ids={ids}
Permanently deletes up to 100 soft-deleted tickets. See Soft delete in the Zendesk GDPR docs. To soft delete tickets, use the Bulk Delete Tickets endpoint.
This endpoint accepts a comma-separated list of up to 100 ticket ids. It enqueues a ticket deletion job and returns a payload with the jobs status.
If one ticket fails to be deleted, the endpoint still attempts to delete the others. If the job succeeds, the tickets that were successfully deleted are permanently deleted. This operation can't be undone.
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.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of ticket ids |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/deleted_tickets/destroy_many.json?ids=1,2,3 \
-X DELETE -v -u {email_address}:{password}
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Restore previously deleted tickets in bulk
PUT /api/v2/deleted_tickets/restore_many?ids={ids}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of ticket ids |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/deleted_tickets/restore_many?ids={ids}.json
-X PUT -v -u {email_address}:{password}
Example Response
Status 200 OK
Delete ticket permanently
DELETE /api/v2/deleted_tickets/{ticket_id}
Permanently deletes a soft-deleted ticket. See Soft delete in the Zendesk GDPR docs. To soft delete a ticket, use the Delete Ticket endpoint.
This endpoint enqueues a ticket deletion job and returns a payload with the jobs status.
If the job succeeds, the ticket is permanently deleted. This operation can't be undone.
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.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/deleted_tickets/{id}.json \
-X DELETE -v -u {email_address}:{password}
Example Response
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Restore a previously deleted ticket
PUT /api/v2/deleted_tickets/{ticket_id}/restore
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/deleted_tickets/{id}/restore.json
-X PUT -v -u {email_address}:{password}
Example Response
Status 200 OK
List Ticket Problems
GET /api/v2/problems
The response is always ordered by updated_at
in descending order
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/problems.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"description": "The fire is very colorful.",
"id": 33,
"status": "open",
"subject": "My printer is on fire"
},
{
"description": "The fire is very colorful as well!",
"id": 34,
"status": "pending",
"subject": "The printer is on fire over here too"
}
]
}
Autocomplete Problems
POST /api/v2/problems/autocomplete
Returns tickets whose type is "problem" and whose subject contains the string specified in the text
parameter.
You can specify the text
parameter in the request body rather than the query string. Example:
{"text": "fire"}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
text | string | Query | false | The text to search for |
Example Body
{
"text": "fire"
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/problems/autocomplete.json?text=fire \
-X POST -H "Content-Type: application/json" \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"description": "The fire is very colorful.",
"id": 33,
"status": "open",
"subject": "My printer is on fire"
},
{
"description": "The fire is very colorful as well!",
"id": 34,
"status": "pending",
"subject": "The printer is on fire over here too"
}
]
}
List Tickets
GET /api/v2/tickets
GET /api/v2/organizations/{organization_id}/tickets
GET /api/v2/users/{user_id}/tickets/requested
GET /api/v2/users/{user_id}/tickets/ccd
GET /api/v2/users/{user_id}/tickets/assigned
GET /api/v2/tickets/recent
ccd
lists tickets that the specified user is cc'd on.
recent
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).
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.
Archived tickets are not included in the response. See About archived tickets in the Support Help Center.
Allowed for
- Agents
Pagination
- Cursor pagination (recommended)
- Offset pagination
See Pagination.
Returns a maximum of 100 records per page.
Sorting
By default, tickets are sorted by id from smallest to largest.
When using cursor pagination, use the following parameter to change the sort order:
Name | Type | Required | Comments |
---|---|---|---|
sort |
string | no | Possible values are "updated_at", "id" (ascending order) or "-updated_at", "-id" (descending order) |
When using offset pagination, use the following parameters to change the sort order:
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 |
When sorting by creation date, the first ticket listed may not be the absolute oldest ticket in your account due to ticket archiving.
The query
parameter is not supported for this endpoint. Use the Search API to narrow your results with query
.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
external_id | string | Query | false | Lists tickets by external id. External ids don't have to be unique for each ticket. As a result, the request may return multiple tickets with the same external id. |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
]
}
Create Ticket
POST /api/v2/tickets
Takes a ticket
object that specifies the ticket properties. The only required property is comment
. See Ticket Comments. All writable properties listed in JSON Format are optional.
Submitting a ticket with HTML data will not result in the HTML being stripped out.
An audit
object is generated and included in the response when you create or update a ticket. The audit
object has an events
array listing all the updates made to the new ticket. For more information, see Ticket Audits.
You can also add your own metadata to the audit
object. See Setting metadata.
For more information on creating tickets, see:
- Creating a follow-up ticket
- Creating a ticket asynchronously
- Setting collaborators
- Setting followers
- Setting email CCs
- Setting metadata
- Attaching files
- Creating a ticket with a new requester
- Setting custom field values
Allowed For
- Agents
Example Body
{
"ticket": {
"comment": {
"body": "The smoke is very colorful."
},
"priority": "urgent",
"subject": "My printer is on fire!"
}
}
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
{
"ticket": {
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
}
Count Tickets
GET /api/v2/tickets/count
GET /api/v2/organizations/{organization_id}/tickets/count
Returns an approximate count of tickets in the account. If the count exceeds 100,000, it is updated every 24 hours.
The count[refreshed_at]
property is a timestamp that indicates when the count was last updated.
Note: When the count exceeds 100,000, count[refreshed_at]
may occasionally be null.
This indicates that the count is being updated in the background, and count[value]
is limited to 100,000 until the update is complete.
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/count.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": {
"refreshed_at": "2020-04-06T02:18:17Z",
"value": 102
},
"links": {
"url": "https://{subdomain}.zendesk.com/api/v2/tickets/count"
}
}
Create Many Tickets
POST /api/v2/tickets/create_many
Accepts an array of up to 100 ticket objects. Note: Every ticket created with this endpoint may be affected by your business rules, which can include sending email notifications to your end users. If you are importing historical tickets or creating more than 1000 tickets, consider using the Ticket Bulk Import endpoint.
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.
Allowed For
- Agents
Example Body
{
"tickets": [
{
"comment": {
"body": "The smoke is very colorful."
},
"priority": "urgent",
"subject": "My printer is on fire!"
},
{
"comment": {
"body": "This is a comment"
},
"priority": "normal",
"subject": "Help"
}
]
}
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
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Bulk Delete Tickets
DELETE /api/v2/tickets/destroy_many?ids={ids}
Accepts a comma-separated list of up to 100 ticket ids.
Allowed For
- Admins
- Agents with permission to delete tickets
Agent delete permissions are set in Support. See Deleting tickets in the Support Help Center.
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
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of ticket ids |
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
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Bulk Mark Tickets as Spam
PUT /api/v2/tickets/mark_many_as_spam?ids={ids}
Accepts a comma-separated list of up to 100 ticket ids.
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
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of ticket ids |
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
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Show Multiple Tickets
GET /api/v2/tickets/show_many?ids={ids}
Accepts a comma-separated list of ticket ids to return.
This endpoint will return up to 100 tickets records.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | Comma-separated list of ticket ids |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/show_many.json?ids=1,2,3 \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
]
}
Update Many Tickets
PUT /api/v2/tickets/update_many
Accepts an array of up to 100 ticket objects, or a comma-separated list of up to 100 ticket ids.
To protect against collisions when updating or bulk updating tickets, see Protecting against ticket update collisions.
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" }
]
}
Batch updates are automatically safe and fail when there's another update to the same tickets after the job started. See Protecting against ticket update collisions.
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.
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.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | false | Comma-separated list of ticket ids |
Using curl
Bulk update
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"}}'
Using curl
Batch update
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
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Show Ticket
GET /api/v2/tickets/{ticket_id}
Returns a number of ticket properties though not the ticket comments. To get the comments, use List Comments
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"ticket": {
"assignee_id": 235323,
"collaborator_ids": [
35334,
234
],
"created_at": "2009-07-20T22:55:29Z",
"custom_fields": [
{
"id": 27642,
"value": "745"
},
{
"id": 27648,
"value": "yes"
}
],
"description": "The fire is very colorful.",
"due_at": null,
"external_id": "ahg35h3jh",
"follower_ids": [
35334,
234
],
"group_id": 98738,
"has_incidents": false,
"id": 35436,
"organization_id": 509974,
"priority": "high",
"problem_id": 9873764,
"raw_subject": "{{dc.printer_on_fire}}",
"recipient": "[email protected]",
"requester_id": 20978392,
"satisfaction_rating": {
"comment": "Great support!",
"id": 1234,
"score": "good"
},
"sharing_agreement_ids": [
84432
],
"status": "open",
"subject": "Help, my printer is on fire!",
"submitter_id": 76872,
"tags": [
"enterprise",
"other_tag"
],
"type": "incident",
"updated_at": "2011-05-05T10:38:52Z",
"url": "https://company.zendesk.com/api/v2/tickets/35436.json",
"via": {
"channel": "web"
}
}
}
Update Ticket
PUT /api/v2/tickets/{ticket_id}
The PUT request takes a ticket
object that lists the values to update. All properties are optional.
See also Protecting against ticket update collisions.
Name | Description |
---|---|
subject | The subject of the ticket |
comment | An object that adds a comment to the ticket. See Ticket comments. To include an attachment with the comment, see Attaching files |
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 |
organization_id | The numeric ID of the organization to assign the ticket to. The requester must be an end user and a member of the specified organization |
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 |
followers | An array of objects that represent agent followers to add or delete from the ticket. See Setting followers |
email_ccs | An array of objects that represent agent or end users email CCs to add or delete from the ticket. See Setting email CCs |
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 |
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 the safe_update property |
safe_update | Optional boolean. Prevents updates with outdated ticket data (updated_stamp property required when true) |
sharing_agreement_ids | An array of the numeric IDs of sharing agreements. Note that this replaces any existing agreements |
macro_ids | An array of macro IDs to be recorded in the ticket audit |
attribute_value_ids | An array of the IDs of attribute values to be associated with the ticket |
Audit Events
An audit
object is generated and included in the response when you update a ticket. See Audit events.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Example Body
{
"ticket": {
"comment": {
"body": "Thanks for choosing Acme Jet Motors.",
"public": true
},
"status": "solved"
}
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_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
{
"audit": {
"events": [
{
"field_name": "subject",
"id": 206091192907,
"type": "Create",
"value": "My printer is on fire!"
},
{
"body": "The smoke is very colorful.",
"id": 206091192547,
"type": "Comment"
}
]
},
"ticket": {
"id": 35436,
"requester_id": 123453,
"status": "open",
"subject": "My printer is on fire!"
}
}
Delete Ticket
DELETE /api/v2/tickets/{ticket_id}
Allowed For
- Admins
- Agents with permission to delete tickets
Agent delete permissions are set in Support. See Deleting tickets in the Support Help Center.
Ticket deletion rate limit
You can delete 400 tickets every 1 minute using this endpoint. The rate limiting mechanism behaves as described in Rate limits in the API introduction. Zendesk recommends that you obey the Retry-After header values. To delete many tickets, you may use Bulk Delete Tickets.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json \
-v -u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content
List Collaborators for a Ticket
GET /api/v2/tickets/{ticket_id}/collaborators
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/collaborators.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 223443,
"name": "Johnny Agent"
},
{
"id": 8678530,
"name": "Peter Admin"
}
]
}
List Email CCs for a Ticket
GET /api/v2/tickets/{ticket_id}/email_ccs
Returns any users cc'd on the ticket.
Availability
The CCs and Followers feature must be enabled in Zendesk Support.
If the feature is not enabled, the default CC functionality is used. In that case, use List Collaborators to list the users cc'ed on the ticket.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/email_ccs.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": "223443",
"name": "Johnny Agent"
},
{
"id": "8678530",
"name": "Peter Admin"
},
{
"id": "6748530",
"name": "Jane End User"
}
]
}
List Followers for a Ticket
GET /api/v2/tickets/{ticket_id}/followers
Returns any users who follow the ticket.
Availability
The CCs and Followers feature must be enabled in Zendesk Support.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/followers.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"users": [
{
"id": 223443,
"name": "Johnny Agent"
},
{
"id": 8678530,
"name": "Peter Admin"
}
]
}
List Ticket Incidents
GET /api/v2/tickets/{ticket_id}/incidents
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/12345/incidents.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"description": "The fire is very colorful.",
"id": 33,
"status": "open",
"subject": "My printer is on fire"
},
{
"description": "The fire is very colorful as well!",
"id": 34,
"status": "pending",
"subject": "The printer is on fire over here too"
}
]
}
Mark Ticket as Spam and Suspend Requester
PUT /api/v2/tickets/{ticket_id}/mark_as_spam
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/mark_as_spam.json \
-v -u {email_address}:{password} -X PUT -d '{}'
Example Response
Status 200 OK
Merge Tickets into Target Ticket
POST /api/v2/tickets/{ticket_id}/merge
Merges one or more tickets into the ticket with the specified id.
See Merging tickets in the Support Help Center for ticket merging rules.
Any attachment to the source ticket is copied to the target ticket.
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.
Allowed For
- Agents
Agents in the Enterprise account must have merge permissions. See Creating custom roles and assigning agents (Enterprise) in the Support Help Center.
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 |
target_comment_is_public | boolean | no | Whether comment in target ticket is public or private |
source_comment_is_public | boolean | no | Whether comment in source tickets are public or private |
The comments are optional but strongly recommended.
Comments are private and can't be modified in the following cases:
- Any of the sources or target tickets are private
- Any of the sources or target tickets were created through Twitter, Facebook or the Channel framework
In any other case, comments default to private but can be modified with the comment privacy parameters.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Example Body
{
"ids": [
123,
456,
789
],
"source_comment": "Closing in favor of #111",
"target_comment": "Combining with #123, #456, #789"
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_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
Status 200 OK
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"message": "Completed at 2018-03-08 10:07:04 +0000",
"progress": 2,
"results": [
{
"action": "update",
"id": 244,
"status": "Updated",
"success": true
},
{
"action": "update",
"id": 245,
"status": "Updated",
"success": true
}
],
"status": "completed",
"total": 2,
"url": "https://example.zendesk.com/api/v2/job_statuses/82de0b0467893ac9fe64f1a99.json"
}
}
Ticket Related Information
GET /api/v2/tickets/{ticket_id}/related
The request returns a data object with the following properties:
Name | Type | Comment |
---|---|---|
topic_id | string | Related topic in the Web portal (deprecated feature) |
followup_source_ids | array | Sources to follow up |
jira_issue_ids | array | Linked JIRA issues |
from_archive | boolean | Is true if the current ticket is archived |
incidents | integer | A count of related incident occurrences |
object | Twitter information associated with the ticket |
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/related.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"followup_source_ids": [],
"from_archive": false,
"incidents": 7,
"jira_issue_ids": [],
"topic_id": null,
"twitter": {
"direct": false,
"handle_id": 10,
"profile": {
"created_at": "2013/01/08 23:24:49 -0800",
"description": "Zendesk is the leading ..."
}
}
}