The Tickets API in Zendesk Support allows developers to create, update, delete, and manage support tickets. This guide covers the essential operations and properties of tickets, providing developers with the necessary information to effectively integrate and utilize the Tickets API.
The most common operations people perform on tickets using the Zendesk Support API.
| Action | HTTP Method | Endpoint |
|---|---|---|
|
Create a Ticket
|
POST
|
/api/v2/tickets
|
|
Retrieve a Ticket
|
GET
|
/api/v2/tickets/{ticket_id}
|
|
Update a Ticket
|
PUT
|
/api/v2/tickets/{ticket_id}
|
|
Delete a Ticket
|
DELETE
|
/api/v2/tickets/{ticket_id}
|
|
List Tickets
|
GET
|
/api/v2/tickets
|
Tickets are the core entity in Zendesk Support, representing customer inquiries, issues, or requests that need to be addressed by support agents.
Tickets are identified by a unique integer ID assigned upon creation.
To create a ticket, you must provide a comment object with the ticket's initial description. Other fields like priority, subject, and requester_id are also commonly included.
Tickets can be searched using various query parameters such as external_id, status, and priority. For example, to find tickets by external ID, use the query parameter 'external_id'.
The properties section provides detailed information about the fields available in a Ticket object. These fields are crucial for managing and interacting with tickets. Show all properties Only show essential properties
| Field Name | Type | Short Description |
|---|---|---|
| id | integer | Automatically assigned when the ticket is created |
| subject | string | The value of the subject field for this ticket |
| status | string | The state of the ticket. Possible values: new, open, pending, hold, solved, closed |
| priority | string | The urgency with which the ticket should be addressed. Possible values: urgent, high, normal, low |
| created_at | datetime | When this record was created |
| updated_at | datetime | When this record last got updated |
| requester_id | integer | The user who requested this ticket |
| assignee_id | integer | The agent currently assigned to the ticket |
| group_id | integer | The group this ticket is assigned to |
| tags | array | The array of tags applied to this ticket |
| custom_fields | array | Custom fields for the ticket |
| description | string | Read-only first comment on the ticket |
| allow_attachments | boolean | Permission for agents to add attachments to a comment. Defaults to true |
| allow_channelback | boolean | Is false if channelback is disabled, true otherwise. Only applicable for channels framework ticket |
| assignee_email | string | Write only. The email address of the agent to assign the ticket to |
| attribute_value_ids | array | Write only. An array of the IDs of attribute values to be associated with the ticket |
| brand_id | integer | The id of the brand this ticket is associated with |
| collaborator_ids | array | The ids of users currently CC'ed on the ticket |
| collaborators | array | POST requests only. Users to add as cc's when creating a ticket |
| comment | object | Write only. An object that adds a comment to the ticket |
| custom_status_id | integer | The custom ticket status id of the ticket |
| due_at | datetime | If this is a ticket of type 'task' it has a due date |
| email_cc_ids | array | The ids of agents or end users currently CC'ed on the ticket |
| email_ccs | object | Write only. An array of objects that represents agent or end users email CCs to add or delete from the ticket |
| external_id | string | An id you can use to link Zendesk Support tickets to local records |
| follower_ids | array | The ids of agents currently following the ticket |
| followers | object | Write only. An array of objects that represents agent followers to add or delete from the ticket |
| followup_ids | array | The ids of the followups created from this ticket |
| forum_topic_id | integer | The topic in the Zendesk Web portal this ticket originated from, if any |
| from_messaging_channel | boolean | If true, the ticket's via type is a messaging channel |
| generated_timestamp | integer | A Unix timestamp that represents the most accurate reading of when this record was last updated |
| has_incidents | boolean | Is true if a ticket is a problem type and has one or more incidents linked to it |
| is_public | boolean | Is true if any comments are public, false otherwise |
| macro_id | integer | Write only. A macro ID to be recorded in the ticket audit |
| macro_ids | array | POST requests only. List of macro IDs to be recorded in the ticket audit |
| metadata | object | Write only. Metadata for the audit |
| organization_id | integer | The organization of the requester |
| problem_id | integer | For tickets of type 'incident', the ID of the problem the incident is linked to |
| raw_subject | string | The dynamic content placeholder, if present, or the 'subject' value, if not |
| recipient | string | The original recipient e-mail address of the ticket |
| safe_update | boolean | Write only. Optional boolean to prevent updates with outdated ticket data |
| satisfaction_rating | object | The satisfaction rating of the ticket, if it exists |
| sharing_agreement_ids | array | The ids of the sharing agreements used for this ticket |
| submitter_id | integer | The user who submitted the ticket |
| ticket_form_id | integer | Enterprise only. The id of the ticket form to render for the ticket |
| type | string | The type of this ticket |
| updated_stamp | string | Write only. Datetime of last update received from API |
| url | string | The API url of this ticket |
| via | object | Describes how the object was created |
| via_followup_source_id | integer | POST requests only. The id of a closed ticket when creating a follow-up ticket |
| via_id | integer | Write only. For more information, see the Via object reference |
| voice_comment | object | Write only. See Creating voicemail ticket |
The Tickets API supports filtering through query parameters to narrow down search results.
| Parameter | Type | Description | Example |
|---|---|---|---|
external_id
|
string | Lists tickets by external id. External ids don't have to be unique for each ticket. |
external_id=abc123
|
Here are some common pitfalls and important considerations when working with the Tickets API.
Some fields such as id and created_at are immutable and cannot be changed once set.
To prevent update collisions, use the safe_update property with updated_stamp to ensure the ticket has not been modified since it was last retrieved.
Be aware of rate limits when making requests. The API allows a certain number of requests per minute, and exceeding this limit will result in errors.
Custom fields must be predefined in your Zendesk account before they can be used in tickets. Ensure that the id and value pair for custom fields are valid.
The email_ccs and followers properties are ignored if the 'CCs and followers' feature is not enabled in your Zendesk account.
Here are some frequently asked questions about the Zendesk Support Tickets API and how to work with Tickets.
external_id query parameter in the /api/v2/tickets endpoint. For example, ?external_id=abc123.
status, priority, and assignee_id. Ensure that you use the safe_update mechanism to prevent update collisions.
custom_fields array. Each custom field must have a valid id and value pair. Ensure the custom field is defined in your Zendesk account.
/api/v2/tickets/create_many endpoint, you can create up to 100 tickets per request. For larger imports, consider using the Ticket Bulk Import endpoint.