openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Tickets
description: Needs a description.
paths:
/api/v2/channels/twitter/tickets:
post:
operationId: CreateTicketFromTweet
tags:
- X Channel
summary: Zendesk Post Api V2 Channels Twitter Tickets
description: >
Turns a tweet into a ticket. You must provide the tweet id as well as
the id of a monitored X (formerly Twitter) handle configured for your
account.
The submitter of the ticket is set to be the user submitting the API
request.
#### Allowed For
* Agents
responses:
'201':
description: description
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
/api/v2/channels/twitter/tickets/{comment_id}/statuses:
parameters:
- $ref: '#/components/parameters/CommentId'
get:
operationId: GettingTwicketStatus
tags:
- X Channel
summary: Zendesk Get Api V2 Channels Twitter Tickets Comment_id Statuses
description: |
#### Allowed For
* Agents
parameters:
- name: ids
in: query
description: >-
Optional comment ids to retrieve tweet information for only
particular comments
schema:
type: string
example: 1,3,5
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TwitterChannelTwicketStatusResponse'
examples:
default:
$ref: >-
#/components/examples/TwitterChannelTwicketStatusResponseExample
/api/v2/channels/voice/agents/{agent_id}/tickets/{ticket_id}/display:
post:
operationId: OpenTicketInAgentBrowser
tags:
- Basics
summary: Zendesk Post Api V2 Channels Voice Agents Agent_id Tickets Ticket_id Display
description: |-
Allows you to instruct an agent's browser to open a ticket.
When the message is successfully delivered to an agent's browser:
```http
Status: 200 OK
```
When `agent_id` or `ticket_id` is invalid:
```http
Status: 404 Not Found
```
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/AgentId'
- $ref: '#/components/parameters/TicketId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: string
description: empty
example: ''
example: ''
'404':
description: When the `agent_id` or `ticket_id` is invalid
content:
application/json:
schema:
type: string
description: Invalid attribute
example: ''
example: ''
/api/v2/channels/voice/tickets:
post:
operationId: CreateTicketOrVoicemailTicket
tags:
- Basics
summary: Zendesk Post Api V2 Channels Voice Tickets
description: >-
#### Allowed For
* Agents
### Creating tickets
#### Introduction
Creating tickets using Talk Partner Edition follows the same conventions
as the Create Ticket endpoint. See [Create
Ticket](/api-reference/ticketing/tickets/tickets/#create-ticket).
#### Request parameters
The POST request takes a mandatory `ticket` object that lists the values
to set when the ticket is created.
You may also include an optional `display_to_agent` value such as the ID
of the agent that will see the newly created ticket.
The `display_to_agent` is validated before creating the ticket,
returning a 422 error if it is invalid.
Tickets created using this endpoint must have a `via_id` parameter. See
the following
section for possible values.
#### Zendesk Talk Integration Via IDs
Tickets created using this endpoint must have one of the following
`via_id` parameters:
| ID | Description
| ---------| -------------
| 44 | Voicemail
| 45 | Phone call (inbound)
| 46 | Phone call (outbound)
### Creating voicemail tickets
#### Request parameters
The POST request takes a mandatory `ticket` object that lists the values
to set when the ticket is created.
The ticket must have a `voice_comment` with the following values:
| Name | Type | Comment
| ------------------ | ----------------------| -------
| from | string | Incoming phone number
| to | string | Dialed phone number
| recording_url | string | URL of the recording
| started_at | date | [ISO
8601](http://en.wikipedia.org/wiki/ISO_8601) timestamp of the call
starting time
| call_duration | integer | Duration in seconds of
the call
| answered_by_id | integer | The agent who answered
the call
| transcription_text | string | Transcription of the call
(optional)
| location | string | Location of the caller
(optional)
parameters:
- $ref: '#/components/parameters/AgentId'
- $ref: '#/components/parameters/TicketId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCreateVoicemailTicketRequest'
examples:
default:
$ref: '#/components/examples/TicketCreateTicketViaTalkRequestExample'
responses:
'201':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketResponse'
examples:
default:
$ref: '#/components/examples/TicketResponseExample'
'404':
description: When the `ticket_id` is invalid
content:
application/json:
schema:
type: string
description: Invalid attribute
example: ''
example: ''
'422':
description: When the `agent_id` is invalid
content:
application/json:
schema:
type: string
description: Invalid attribute
example: ''
example: ''
/api/v2/imports/tickets:
post:
operationId: TicketImport
tags:
- Ticket Import
summary: Zendesk Post Api V2 Imports Tickets
description: |-
#### Allowed For
* Admins
parameters:
- $ref: '#/components/parameters/ArchiveImmediately'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketImportRequest'
examples:
default:
$ref: '#/components/examples/TicketImportRequestExample'
responses:
'201':
description: Successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/TicketResponse'
examples:
default:
$ref: '#/components/examples/TicketResponseExample'
/api/v2/imports/tickets/create_many:
post:
operationId: TicketBulkImport
tags:
- Ticket Import
summary: Zendesk Post Api V2 Imports Tickets Create_many
description: |-
Accepts an array of up to 100 ticket objects.
#### Allowed For
* Admins
parameters:
- $ref: '#/components/parameters/ArchiveImmediately'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketBulkImportRequest'
examples:
default:
$ref: '#/components/examples/TicketBulkImportRequestExample'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
examples:
default:
$ref: '#/components/examples/JobStatusResponseExample'
/api/v2/incremental/tickets:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
get:
operationId: IncrementalTicketExportTime
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Tickets
description: >
Returns the tickets that changed since the start time. For more
information,
see [Exporting
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
This endpoint supports time-based incremental exports.
For more information, see [Time-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
You can also return tickets using cursor-based pagination. See
[Incremental Ticket Export, Cursor
Based](#incremental-ticket-export-cursor-based).
The results include tickets that were updated by the system. See
[Excluding system-updated
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#excluding-system-updated-tickets-time-based-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
The endpoint can return tickets with an `updated_at` time that's earlier
than the
`start_time` time. The reason is that the API compares the `start_time`
with the ticket's
`generated_timestamp` value, not its `updated_at` value. The
`updated_at` value is
updated only if the update generates a [ticket
event](#incremental-ticket-event-export).
The `generated_timestamp` value is updated for all ticket updates,
including system
updates. If a system update occurs after a ticket event, the unchanged
`updated_at` time will become earlier relative to the updated
`generated_timestamp`
time.
#### Allowed For
* Admins
#### Sideloading
See [Tickets
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
For performance reasons,
`last_audits` sideloads aren't supported.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TimeBasedExportIncrementalTicketsResponse'
examples:
default:
$ref: >-
#/components/examples/TimeBasedExportIncrementalTicketsResponseExample
/api/v2/incremental/tickets/cursor:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalCursor'
get:
operationId: IncrementalTicketExportCursor
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Tickets Cursor
description: >
Returns the tickets that changed since the start time. For more
information,
see [Exporting
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
This endpoint supports cursor-based incremental exports.
Cursor-based exports are highly encouraged because they provide more
consistent performance and
response body sizes. For more information, see [Cursor-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#cursor-based-incremental-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
#### Allowed For
* Admins
#### Sideloading
See [Tickets
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
For performance reasons,
`last_audits` sideloads aren't supported.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: >-
#/components/schemas/CursorBasedExportIncrementalTicketsResponse
examples:
default:
$ref: >-
#/components/examples/CursorBasedExportIncrementalTicketsResponseExample
/api/v2/routing/tickets/{ticket_id}/instance_values:
parameters:
- $ref: '#/components/parameters/TicketId'
get:
operationId: ListTicketAttributeValues
tags:
- Skill Based Routing
summary: Zendesk Get Api V2 Routing Tickets Ticket_id Instance_values
description: |
Returns a list of attributes values for the ticket.
#### Allowed For
* Agents and admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
examples:
default:
$ref: >-
#/components/examples/SkillBasedRoutingTicketAttributesResponseExample
post:
operationId: SetTicketAttributeValues
tags:
- Skill Based Routing
summary: Zendesk Post Api V2 Routing Tickets Ticket_id Instance_values
description: >
Adds the specified attributes if no attributes exists, or replaces all
existing attributes with the specified attributes.
Invalid or deleted attributes are ignored.
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
examples:
default:
$ref: >-
#/components/examples/SkillBasedRoutingTicketAttributesResponseExample
/api/v2/tickets:
get:
operationId: ListTickets
tags:
- Tickets
summary: Zendesk Get Api V2 Tickets
parameters:
- name: external_id
in: query
description: >-
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.
schema:
type: string
responses:
'200':
description: List tickets
content:
application/json:
schema:
$ref: '#/components/schemas/TicketsResponse'
examples:
default:
$ref: '#/components/examples/TicketsResponseExample'
post:
operationId: CreateTicket
tags:
- Tickets
summary: Zendesk Post Api V2 Tickets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCreateRequest'
examples:
default:
$ref: '#/components/examples/TicketCreateRequestExample'
responses:
'201':
description: Create ticket
headers:
Location:
description: The URL of the created ticket
schema:
type: string
format: url
content:
application/json:
schema:
$ref: '#/components/schemas/TicketResponse'
examples:
default:
$ref: '#/components/examples/TicketResponseExample'
/api/v2/tickets/{ticket_id}:
get:
operationId: ShowTicket
tags:
- Tickets
summary: Zendesk Get Api V2 Tickets Ticket_id
description: >-
Returns a number of ticket properties though not the ticket comments. To
get the comments, use [List
Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments)
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/TicketId'
responses:
'200':
description: Ticket
content:
application/json:
schema:
$ref: '#/components/schemas/TicketResponse'
examples:
default:
$ref: '#/components/examples/TicketResponseExample'
put:
operationId: UpdateTicket
tags:
- Tickets
summary: Zendesk Put Api V2 Tickets Ticket_id
parameters:
- $ref: '#/components/parameters/TicketId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TicketUpdateRequest'
examples:
default:
$ref: '#/components/examples/TicketUpdateRequestExample'
responses:
'200':
description: Successful request
content:
application/json:
schema:
$ref: '#/components/schemas/TicketUpdateResponse'
examples:
default:
$ref: '#/components/examples/TicketUpdateResponseExample'
delete:
operationId: DeleteTicket
tags:
- Tickets
summary: Zendesk Delete Api V2 Tickets Ticket_id
description: >-
#### Allowed For
* Admins
* Agents with permission to delete tickets
Agent delete permissions are set in Support. See
[Deleting
tickets](https://support.zendesk.com/hc/en-us/articles/203690936)
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](/api-reference/introduction/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](/api-reference/ticketing/tickets/tickets/#bulk-delete-tickets).
parameters:
- $ref: '#/components/parameters/TicketId'
responses:
'204':
description: No content
/api/v2/tickets/{ticket_id}/audits:
parameters:
- $ref: '#/components/parameters/TicketId'
get:
operationId: ListAuditsForTicket
tags:
- Ticket Audits
summary: Zendesk Get Api V2 Tickets Ticket_id Audits
description: >
Lists the audits for a specified ticket.
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
**Note**: Audits for [Archived
Tickets](https://support.zendesk.com/hc/en-us/articles/4408887617050) do
not support pagination for this endpoint.
#### Allowed for
* Agents
responses:
'200':
description: OK response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketAuditsResponseNoneCursor'
examples:
default:
$ref: '#/components/examples/TicketAuditsForTicketResponseExample'
/api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}:
parameters:
- $ref: '#/components/parameters/TicketId'
- $ref: '#/components/parameters/TicketAuditId'
get:
operationId: ShowTicketAudit
tags:
- Ticket Audits
summary: Zendesk Get Api V2 Tickets Ticket_id Audits Ticket_audit_id
description: |
#### Allowed for
* Agents
responses:
'200':
description: OK response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketAuditResponse'
examples:
default:
$ref: '#/components/examples/TicketAuditResponseExample'
/api/v2/tickets/{ticket_id}/audits/{ticket_audit_id}/make_private:
parameters:
- $ref: '#/components/parameters/TicketId'
- $ref: '#/components/parameters/TicketAuditId'
put:
operationId: MakeTicketCommentPrivateFromAudits
tags:
- Ticket Audits
summary: Zendesk Put Api V2 Tickets Ticket_id Audits Ticket_audit_id Make_private
description: |
#### Allowed for
* Agents
responses:
'200':
description: description
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
/api/v2/tickets/{ticket_id}/audits/count:
parameters:
- $ref: '#/components/parameters/TicketId'
get:
operationId: CountAuditsForTicket
tags:
- Ticket Audits
summary: Zendesk Get Api V2 Tickets Ticket_id Audits Count
description: >
Returns an approximate count of audits for a specified ticket. If the
count exceeds 100,000, the count will return a cached result. This
cached result will update every 24 hours.
The `count[refreshed_at]` property is a timestamp that indicates when
the count was last updated.
**Note**: If the total number of audits for a ticket exceeds 100,000,
this endpoint returns a count of 100,000 with a `count[refreshed_at]`
value of null. This value is cached for 24 hours, during which any
requests returns the same count and timestamp. After 24 hours, the
endpoint temporarily shows the same count again before providing an
updated total.
#### Allowed for
* Agents
responses:
'200':
description: Count of audits on a ticket
content:
application/json:
schema:
$ref: '#/components/schemas/TicketAuditsCountResponse'
examples:
default:
$ref: '#/components/examples/TicketAuditsCountResponseExample'
/api/v2/tickets/{ticket_id}/collaborators:
get:
operationId: ListTicketCollaborators
tags:
- Tickets
summary: Zendesk Get Api V2 Tickets Ticket_id Collaborators
description: |-
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/TicketId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListTicketCollaboratorsResponse'
examples:
default:
$ref: '#/components/examples/ListTicketCollaboratorsResponseExample'
/api/v2/tickets/{ticket_id}/comments:
parameters:
- $ref: '#/components/parameters/TicketId'
get:
operationId: ListTicketComments
tags:
- Ticket Comments
summary: Zendesk Get Api V2 Tickets Ticket_id Comments
description: >
Returns the comments added to the ticket.
Each comment may include a `content_url` for an attachment or a
`recording_url` for a voice comment that points to a file that may be
hosted externally. For security reasons, take care not to inadvertently
send Zendesk authentication credentials to third parties when attempting
to access these files. See [Working with url
properties](/documentation/ticketing/managing-tickets/working-with-url-properties).
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Sorting
By default, comments are sorted by creation date in ascending order.
When using cursor pagination, use the following parameter to change the
sort order:
| Name | Type | Required | Comments
| ------ | ------ | -------- | --------
| `sort` | string | no | Possible values are "created_at"
(ascending order) or "-created_at" (descending order)
When using offset pagination, use the following parameters to change the
sort order:
| Name | Type | Required | Comments
| ------------ | ------ | -------- | --------
| `sort_order` | string | no | One of `asc`, `desc`. Defaults to
`asc`
#### Allowed For
* Agents
parameters:
- name: include_inline_images
in: query
description: >-
Default is false. When true, inline images are also listed as
attachments in the response
schema:
type: boolean
- name: include
in: query
description: >-
Accepts "users". Use this parameter to list email CCs by
side-loading users. Example: `?include=users`. **Note**: If the
comment source is email, a deleted user will be represented as the
CCd email address. If the comment source is anything else, a deleted
user will be represented as the user name.
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCommentsResponse'
examples:
default:
$ref: '#/components/examples/TicketCommentsResponseExample'
/api/v2/tickets/{ticket_id}/comments/{comment_id}/attachments/{attachment_id}/redact:
parameters:
- $ref: '#/components/parameters/TicketId'
- $ref: '#/components/parameters/CommentId'
- $ref: '#/components/parameters/AttachmentId'
put:
operationId: RedactCommentAttachment
tags:
- Attachments
summary: >-
Zendesk Put Api V2 Tickets Ticket_id Comments Comment_id Attachments Attachment_id Redact
description: >
Redaction allows you to permanently remove attachments from an existing
comment on a ticket. Once removed from a comment, the attachment is
replaced with an empty "redacted.txt" file.
The redaction is permanent. It is not possible to undo redaction or see
what was removed. Once a ticket is closed, redacting its attachments is
no longer possible.
Also, if you want to redact an inline attachment, you can use the
`include_inline_images` parameter in the [List
Comments](/api-reference/ticketing/tickets/ticket_comments/#list-comments)
operation to obtain the inline attachment ID, and use it in the request
URL.
#### Allowed For
* Admins
* Agents when [deleting tickets is enabled for agents on professional
accounts](https://support.zendesk.com/hc/en-us/articles/360002128107)
* Agents assigned to a custom role with permissions to redact ticket
content (Enterprise only)
responses:
'200':
description: OK response
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentResponse'
examples:
default:
$ref: '#/components/examples/AttachmentResponseExample'
/api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/make_private:
parameters:
- $ref: '#/components/parameters/TicketId'
- $ref: '#/components/parameters/TicketCommentId'
put:
operationId: MakeTicketCommentPrivate
tags:
- Ticket Comments
summary: Zendesk Put Api V2 Tickets Ticket_id Comments Ticket_comment_id Make_private
description: |
#### Allowed For
* Agents
responses:
'200':
description: description
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
/api/v2/tickets/{ticket_id}/comments/{ticket_comment_id}/redact:
parameters:
- $ref: '#/components/parameters/TicketId'
- $ref: '#/components/parameters/TicketCommentId'
put:
operationId: RedactStringInComment
tags:
- Ticket Comments
summary: Zendesk Put Api V2 Tickets Ticket_id Comments Ticket_comment_id Redact
description: >
Permanently removes words or strings from a ticket comment. Specify the
string to redact in an object with a `text` property. Example:
`'{"text": "987-65-4320"}'`. The characters of the word or string are
replaced by the ▇ symbol.
If the comment was made by email, the endpoint also attempts to redact
the string from the original email retained by Zendesk for audit
purposes.
**Note**: If you use the rich text editor, support for redacting
formatted text (bold, italics, hyperlinks) is limited.
Redaction is permanent. You can't undo the redaction or see *what* was
removed. Once a ticket is closed, you can no longer redact strings from
its comments.
To use this endpoint, the "Agents can delete tickets" option must be
enabled in the Zendesk Support admin interface at **Admin** >
**Settings** > **Agents**.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCommentResponse'
examples:
default:
$ref: >-
#/components/examples/TicketCommentStringRedactResponseExample
/api/v2/tickets/{ticket_id}/comments/count:
get:
operationId: CountTicketComments
tags:
- Ticket Comments
summary: Zendesk Get Api V2 Tickets Ticket_id Comments Count
description: >-
Returns an approximate count of the comments added to the ticket. If the
count exceeds 100,000, the count will return a cached result. This
cached result will update 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
parameters:
- $ref: '#/components/parameters/TicketId'
responses:
'200':
description: Count of ticket comments
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCommentsCountResponse'
examples:
default:
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zendesk/refs/heads/main/openapi/tickets-openapi-original.yml