The Zendesk Support Ticketing API lets you create, update and retrieve support tickets and their related comments, attachments, and custom fields. This is the human-friendly guide to the 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.json
|
|
Update a Ticket
|
PUT
|
/api/v2/tickets/{id}.json
|
|
Retrieve a Ticket
|
GET
|
/api/v2/tickets/{id}.json
|
|
List Tickets
|
GET
|
/api/v2/tickets.json
|
|
Search for Tickets
|
GET
|
/api/v2/tickets/search.json
|
|
Delete a Ticket
|
DELETE
|
/api/v2/tickets/{id}.json
|
Tickets are identified by a unique ID. You need this ID in order to
get, update, or delete a ticket. These operations are performed using
the HTTP methods GET, PUT, and
DELETE on the same endpoint.
The ticket ID is part of the URL.
When creating a ticket, you need to provide a subject and a description. Optionally, you can set the status, priority, and assign the ticket to an agent.
If you don't have the ID of a ticket, you can search for tickets by many of the ticket properties.
The 10 most important properties a ticket can have in the Zendesk Support API. Some properties are required, some are optional, and some are read-only. Show all properties Only show essential properties
| Field Name | Type | Short Description |
|---|---|---|
| id | integer | Unique identifier for the ticket |
| subject | string | Brief description of the ticket issue |
| description | string | Detailed description of the ticket issue |
| status | string | Current state of the ticket (e.g., open, solved) |
| priority | string | Urgency level of the ticket (e.g., high, low) |
| requester_id | integer | ID of the user who requested the ticket |
| assignee_id | integer | ID of the agent assigned to the ticket |
| created_at | datetime | Timestamp when the ticket was created |
| updated_at | datetime | Timestamp when the ticket was last updated |
| tags | array | List of tags associated with the ticket |
| allow_attachments | boolean | |
| allow_channelback | boolean | |
| assignee_email | string | write-only |
| attribute_value_ids | array of integers | write-only |
| brand_id | integer | |
| collaborator_ids | array of integers | |
| collaborators | array of objects | write-only |
| comment | object | write-only; to set the ticket description as the first comment |
| custom_fields | array of objects | |
| custom_status_id | integer | |
| due_at | string | ISO 8601 date format |
| email_cc_ids | array of integers | |
| email_ccs | object | write-only; array of objects for adding/removing email CCs |
| external_id | string | Arbitrary string to associate a ticket with a record in another system. |
| follower_ids | array of integers | |
| followers | object | write-only |
| group_id | integer | |
| macro_id | integer | write-only |
| macro_ids | array of integers | POST only |
| metadata | object | write-only |
| organization_id | integer | |
| problem_id | integer | |
| raw_subject | string | |
| recipient | string | |
| requester | object | write-only |
| safe_update | boolean | optional, write-only |
| satisfaction_rating | object | read-only |
| sharing_agreement_ids | array of integers | |
| submitter_id | integer | |
| ticket_form_id | integer | |
| type | string | values: "problem", "incident", "question", "task" |
| updated_stamp | string | write-only; datetime of last update |
| via_followup_source_id | integer | POST only |
| via_id | integer | write-only |
| voice_comment | object | write-only |
Did you know you can't update the updated_at field? Or that setting tags will overwrite existing tags? Here are some common pitfalls and gotchas when working with tickets in the Zendesk Support API.
Fields like id, created_at, and updated_at are automatically set by the system and cannot be modified. Attempting to do so may result in errors.
Fields like status and priority accept only predefined values (e.g., "open," "solved" for status and "high," "low" for priority). Using unapproved values can cause validation errors.
Setting the tags field will overwrite any existing tags on the ticket. Be sure to include all desired tags in the request to avoid losing existing tags.
Fields like requester_id and assignee_id must reference existing user and agent IDs in the system. Invalid or missing references can lead to errors or incomplete data processing.
Frequent API calls may be subject to rate limiting, especially in high-traffic environments. This can throttle access, affecting response times and system performance.
Access to certain ticket information or modification actions may be restricted based on user roles or permissions, which can impact API usability for specific roles.
Fields like assignee_id can be set to null if a ticket is unassigned. Be mindful when assigning values to avoid null-pointer errors or unassigned tickets.
The API may return various error codes (e.g., 400 for bad requests, 404 for not found, 429 for too many requests).
