The Zendesk Requests API is the end-userfacing interface for support tickets, designed for customers to create, view, and update their own requests from web or mobile apps without agent credentials. It provides endpoints to submit a new request, list a users existing requests, get details for a specific request, add comments, include attachments (via upload tokens), and check request counts or status.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Requests
description: Needs a description.
paths:
/api/v2/requests:
get:
operationId: ListRequests
tags:
- Requests
summary: Zendesk Get Api V2 Requests
description: |
#### Allowed for
* End Users
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
parameters:
- name: sort_by
in: query
description: Possible values are "updated_at", "created_at"
schema:
type: string
- name: sort_order
in: query
description: One of "asc", "desc". Defaults to "asc"
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestsResponse'
examples:
default:
$ref: '#/components/examples/RequestsResponseExample'
post:
operationId: CreateRequest
tags:
- Requests
summary: Zendesk Post Api V2 Requests
description: >
Accepts a `request` object that sets one or more properties.
#### Allowed for
* End users
* Anonymous users (rate limit of 5 requests per hour for [trial
accounts](/documentation/developer-tools/getting-started/getting-a-trial-or-sponsored-account-for-development/))
#### Additional properties
In addition to the writable request properties in the [JSON Format
table](#json-format) above, you can set the following properties when
creating a request.
| Name | Type | Mandatory | Comment
| ---------------- | -------| --------- | -------
| comment | object | yes | Describes the problem,
incident, question, or task. See [Request comments](#request-comments)
| collaborators | array | no | Adds collaborators (cc's)
to the request. An email notification is sent to them when the ticket is
created. See [Setting
collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#setting-collaborators)
| requester | object | yes* | \*Required for anonymous
requests. Specifies the requester of the anonymous request. See
[Creating anonymous
requests](/documentation/ticketing/managing-tickets/creating-and-managing-requests#creating-anonymous-requests)
#### Creating follow-up requests
Once a ticket is closed (as distinct from solved), it can't be reopened.
However, you can create a new request that references the closed ticket.
To create the follow-up request, include a `via_followup_source_id`
property in the `request` object that specifies the closed ticket. The
parameter only works with closed tickets. It has no effect with other
tickets.
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestResponse'
examples:
default:
$ref: '#/components/examples/RequestCreateResponseExample'
/api/v2/requests/{request_id}:
parameters:
- $ref: '#/components/parameters/RequestId'
get:
operationId: ShowRequest
tags:
- Requests
summary: Zendesk Get Api V2 Requests Request_id
description: |
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ---------------- | -------------
| users | The email ccs for a request by side-loading users
#### Allowed For
* End Users
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestResponse'
examples:
default:
$ref: '#/components/examples/RequestResponseExample'
put:
operationId: UpdateRequest
tags:
- Requests
summary: Zendesk Put Api V2 Requests Request_id
description: >
Updates a request with a comment or collaborators (cc's). The end user
who created the request can also use it to mark the request as solved.
The endpoint can't be used to update other request attributes.
#### Writable properties
This endpoint can only update the following properties in the request.
| Name | Type | Required |
Description |
| ------------------------ | ------- | -------- |
---------------------------------------------------- |
| comment | object | no | Adds a comment to the
request. See [Request comments](#request-comments) |
| solved | boolean | no | Marks the request as
solved. Example: `{"request": {"solved": "true"}}`. End users can mark
requests as solved only if the request's `can_be_solved_by_me` property
is true. The property is true only when the ticket is assigned to an
agent and the ticket type is not a problem but a question, task, or
incident |
| additional_collaborators | array | no | Adds collaborators to
the request. An email notification is sent to them when the ticket is
updated. See [Adding
collaborators](/documentation/ticketing/managing-tickets/creating-and-managing-requests#adding-collaborators)
|
#### Allowed For
* End users
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestResponse'
examples:
default:
$ref: '#/components/examples/RequestCreateResponseExample'
/api/v2/requests/{request_id}/comments:
parameters:
- $ref: '#/components/parameters/RequestId'
get:
operationId: ListComments
tags:
- Requests
summary: Zendesk Get Api V2 Requests Request_id Comments
description: >
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
#### 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_by` | string | no | One of `created_at`, `updated_at`
| `sort_order` | string | no | One of `asc`, `desc`
#### Allowed For
* End Users
parameters:
- name: since
in: query
description: Filters the comments from the given datetime
schema:
type: string
- name: role
in: query
description: One of "agent", "end_user". If not specified it does not filter
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCommentsResponse'
examples:
default:
$ref: '#/components/examples/RequestListCommentsResponseExample'
/api/v2/requests/{request_id}/comments/{ticket_comment_id}:
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/TicketCommentId'
get:
operationId: ShowComment
tags:
- Requests
summary: Zendesk Get Api V2 Requests Request_id Comments Ticket_comment_id
description: |
#### Allowed For
* End Users
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketCommentResponse'
examples:
default:
$ref: '#/components/examples/RequestGetCommentResponseExample'
/api/v2/requests/search:
get:
operationId: SearchRequests
tags:
- Requests
summary: Zendesk Get Api V2 Requests Search
description: >
Examples:
* `GET /api/v2/requests/search.json?query=printer`
* `GET /api/v2/requests/search.json?query=printer&organization_id=1`
* `GET /api/v2/requests/search.json?query=printer&cc_id=true`
* `GET /api/v2/requests/search.json?query=printer&status=hold,open`
#### Pagination
* Offset pagination only
See [Using Offset
Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Results limit
The Search Requests endpoint returns up to 1,000 results per query, with
a maximum of 100 results per page. See
[Pagination](/api-reference/ticketing/introduction/#pagination). If you
request a page past the limit (`page=11` at 100 results per page), a 422
Insufficient Resource Error is returned.
#### Allowed For
* End Users
parameters:
- name: query
in: query
description: >-
The syntax and matching logic for the string is detailed in the
[Zendesk Support search
reference](https://support.zendesk.com/hc/en-us/articles/203663226).
See also [Query
basics](/api-reference/ticketing/ticket-management/search/#query-basics)
in the Tickets API doc.
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestsResponse'
examples:
default:
$ref: '#/components/examples/RequestsResponseExample'
components:
schemas:
RequestsResponse:
type: object
properties:
requests:
type: array
items:
$ref: '#/components/schemas/RequestObject'
RequestResponse:
type: object
properties:
request:
$ref: '#/components/schemas/RequestObject'
TicketCommentsResponse:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/TicketCommentObject'
TicketCommentResponse:
type: object
properties:
comment:
$ref: '#/components/schemas/TicketCommentObject'
tags:
- name: Requests