The Zendesk Views API lets you programmatically manage and use ticket viewsthe saved sets of filtering, sorting, and column rules that define agent queues. With it, you can list and fetch views (personal or shared), create, update, delete, and reorder them, and execute a view to retrieve the current tickets that match its conditions along with counts.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Views
description: Needs a description.
paths:
/api/v2/views:
get:
operationId: ListViews
tags:
- Views
summary: Zendesk Get Api V2 Views
description: >
Lists shared and personal views available to the current user.
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each view, if
present
| permissions | The permissions for each view
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
parameters:
- name: access
in: query
description: >-
Only views with given access. May be "personal", "shared", or
"account"
schema:
type: string
- name: active
in: query
description: Only active views if true, inactive views if false
schema:
type: boolean
- name: group_id
in: query
description: Only views belonging to given group
schema:
type: integer
- name: sort
in: query
description: >-
The sort parameter used with cursor pagination. Defaults to
"created_at". Prefix with '-' for descending order
schema:
type: string
- name: sort_by
in: query
description: >-
The sort_by parameter used with offset pagination. Possible values
are "alphabetical", "created_at", or "updated_at". Defaults to
"position"
schema:
type: string
- name: sort_order
in: query
description: >-
The sort_order parameter used with offset pagination. One of "asc"
or "desc". Defaults to "asc" for alphabetical and position sort,
"desc" for all others
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsResponse'
examples:
default:
$ref: '#/components/examples/ViewsResponseExample'
post:
operationId: CreateView
tags:
- Views
summary: Zendesk Post Api V2 Views
description: >
#### Allowed For
* Agents
#### JSON Format
The JSON format consists of one property, a `view` object that lists the
values to set when the view is created.
**Note**: The request must include at least one condition in the `all`
array that checks one of the following fields: `status`, `type`,
`group_id`, `assignee_id`, or `requester_id`.
| Name | Description
| ----------- | -----------
| title | Required. The title of the view
| all | Required. An array of one or more conditions. A ticket
must meet all of them to be included in the view. See [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference)
| any | An array of one or more conditions. A ticket must meet
any of them to be included in the view. See [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference)
| description | The description of the view
| active | Allowed values are true or false. Determines if the view
is displayed or not
| output | An object that specifies the columns to display.
Example: `"output": {"columns": ["status", "description", "priority"]}`.
See [View columns](#view-columns)
| restriction | An object that describes who can access the view. To
give all agents access to the view, omit this property
The `restriction` object has the following properties.
| Name | Comment
| ---- | -------
| type | Allowed values are "Group" or "User"
| id | The numeric ID of a single group or user
| ids | The numeric IDs of a single or more groups. Recommended for
"Group" `type`
If `type` is "Group", the `ids` property is the preferred method of
specifying the group id or ids.
#### Example Request Body
```js
{
"view": {
"title": "Kelly's tickets",
"raw_title": "{{dc.tickets_assigned_to_kelly}}",
"description": "Tickets that are assigned to Kelly",
"active": true,
"position": 3,
"restriction": {
"type": "User",
"id": "213977756"
},
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "group_id",
"operator": "is",
"value": "24000932"
},
{
"field": "custom_fields_360011872073",
"operator": "is",
"value": "Canada"
},
...
],
"output": {
"columns": ["status", "requester", "assignee"],
"group_by": "assignee",
"group_order": "desc",
"sort_by": "status",
"sort_order": "desc"
}
}
}
```
#### View columns
The `output` request parameter lets you specify what columns to include
in the view in the agent interface. Example: `"output": {"columns":
["status", "description", "priority"]}`. The following table lists
possible columns for views in the agent UI and the corresponding values
in the `columns` array.
For custom fields, specify the id of the custom field in the `columns`
array.
You can specify a total of 10 columns to a view.
| View column title in UI | Value |
|---------------------------- | -------------------- |
| Assigned | `assigned` |
| Assignee | `assignee` |
| Due Date | `due_date` |
| Group | `group` |
| ID | `nice_id` |
| Updated | `updated` |
| Assignee updated | `updated_assignee` |
| Requester updated | `updated_requester` |
| Updater | `updated_by_type` |
| Organization | `organization` |
| Priority | `priority` |
| Requested | `created` |
| Requester | `requester` |
| Requester language | `locale_id` |
| Satisfaction | `satisfaction_score` |
| Solved | `solved` |
| Status category | `status` |
| Subject | `description` |
| Submitter | `submitter` |
| Ticket form | `ticket_form` |
| Type | `type` |
| Brand | `brand` |
| Ticket status | `custom_status_id` |
#### View sorting
You can group and sort items in the view by adding items to the `output`
parameter:
| Attribute | Description
|-----------------------------| -----------
| `group_by`, `sort_by` | Sort or group the tickets by a column in
the [View columns](#view-columns) table. The `description`, `submitter`
and `custom_status_id` columns are not supported
| `group_order`, `sort_order` | Either "asc" or "desc"
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewResponse'
examples:
default:
$ref: '#/components/examples/ViewCreateResponseExample'
/api/v2/views/{view_id}:
parameters:
- $ref: '#/components/parameters/ViewId'
get:
operationId: ShowView
tags:
- Views
summary: Zendesk Get Api V2 Views View_id
description: |
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewResponse'
examples:
default:
$ref: '#/components/examples/ViewResponseExample'
put:
operationId: UpdateView
tags:
- Views
summary: Zendesk Put Api V2 Views View_id
description: >
#### Allowed For
* Agents
#### JSON Format
The PUT request takes one property, a `view` object that lists the values to update. All properties are optional.
**Note**: Updating a condition updates the containing array, clearing
the other conditions. Include all your conditions when updating any
condition.
| Name | Description
| ----------- | -----------
| title | The title of the view
| all | An array of one or more conditions. A ticket must meet
all the conditions to be included in the view. The PUT request replaces
all existing conditions. See [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference)
| any | An array of one or more conditions. A ticket must meet
any of them to be included in the view. At least one `all` condition
must be defined with the `any` conditions. The PUT request replaces all
existing `any` conditions. See [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference)
| active | Allowed values are true or false. Determines if the view
is displayed or not
| output | An object that specifies the columns to display.
Example: `"output": {"columns": ["status", "description," "priority"]}`.
See [View columns](#view-columns)
| restriction | An object that describes who can access the view. To
give all agents access to the view, omit this property
The `restriction` object has the following properties.
| Name | Comment
| ---- | -------
| type | Allowed values are "Group" or "User"
| id | The numeric ID of a single group or user
| ids | The numeric IDs of a single or more groups. Recommended for
"Group" `type`
If `type` is "Group", the `ids` property is the preferred method of
specifying the group id or ids.
You can also update how items are sorted and grouped. See [View
sorting](#view-sorting) in Create View.
#### Example Request Body
```js
{
"view": {
"title": "Code red tickets",
"restriction": {
"type": "Group",
"ids": [10052, 10057, 10062, 10002]
},
"all": [
{
"field": "priority",
"operator": "is",
"value": "urgent"
}
],
"output": {
"columns": ["status", "requester", "assignee", "updated"]
}
}
}
```
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewResponse'
examples:
default:
$ref: '#/components/examples/ViewUpdateResponseExample'
delete:
operationId: DeleteView
tags:
- Views
summary: Zendesk Delete Api V2 Views View_id
description: |
#### Allowed For
* Agents
responses:
'204':
description: No Content response
/api/v2/views/{view_id}/count:
parameters:
- $ref: '#/components/parameters/ViewId'
get:
operationId: GetViewCount
tags:
- Views
summary: Zendesk Get Api V2 Views View_id Count
description: >
Returns the ticket count for a single view.
This endpoint is rate limited to 5 requests per minute, per view, per
agent.
#### View Counts
The view count endpoints, Count Tickets in View (this endpoint) and
[Count Tickets in Views](#count-tickets-in-views), let you estimate how
many tickets remain in a view without having to retrieve the entire
view. They're designed to help estimate view size. From a business
perspective, accuracy becomes less relevant as view size increases.
To ensure quality of service, these counts are cached more heavily as
the number of tickets in a view grows. For a view with thousands of
tickets, you can expect the count to be cached for 60-90 minutes. As a
result, the count may not reflect the actual number of tickets in your
view.
View counts are represented as JSON objects with the following
attributes:
| Name | Type | Comment
| --------------- | ------------| -------
| view_id | integer | The id of the view
| url | string | The API url of the count
| value | integer | The cached number of tickets in the
view. Can also be null if the system is loading and caching new data.
Not to be confused with 0 tickets
| pretty | string | A pretty-printed text approximation of
the view count
| fresh | boolean | false if the cached data is stale and
the system is still loading and caching new data
| active | boolean | Only active views if true, inactive
views if false, all views if null.
#### Example
```js
{
"view_count": {
"view_id": 25,
"url": "https://company.zendesk.com/api/v2/views/25/count.json",
"value": 719,
"pretty": "~700",
"fresh": true
}
}
```
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewCountResponse'
examples:
default:
$ref: '#/components/examples/ViewCountResponseExample'
/api/v2/views/{view_id}/execute:
parameters:
- $ref: '#/components/parameters/ViewId'
get:
operationId: ExecuteView
tags:
- Views
summary: Zendesk Get Api V2 Views View_id Execute
description: >
Returns the column titles and the rows of the specified view.
The `columns` array lists the view's column titles and includes only
views parameters.
The `rows` array lists the values of each column for each ticket and
includes parameters from both views and tickets. Though not displayed in
the view, a partial ticket object is included with each row object.
**Note**: To get the full ticket objects for a specified view, use [List
Tickets from a View](#list-tickets-from-a-view).
This endpoint is rate limited to 5 requests per minute, per view, per
agent. This rate limit includes activity in Zendesk Support. An API
script is more likely to encounter rate limit errors if the
authenticating agent or admin is concurrently active in Zendesk Support.
The view execution system is designed for periodic rather than
high-frequency API usage. In particular, views called very frequently
may be cached by Zendesk. This means that the API client will still
receive a result, but that result may have been computed at any time
within the last 10 minutes.
Zendesk recommends using the Incremental Ticket Export endpoint to get
the latest changes. You can call it more often, and it returns all the
tickets that changed since the last poll. For details and rate limits,
see [Incremental
Exports](/api-reference/ticketing/ticket-management/incremental_exports/).
View output sorting can be controlled by passing the `sort_by` and
`sort_order` parameters in the format described in the table in [Preview
Views](#preview-views).
#### Allowed For
* Agents
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
parameters:
- name: sort_by
in: query
description: >-
The ticket field used for sorting. This will either be a title or a
custom field id.
schema:
type: string
- name: sort_order
in: query
description: The direction the tickets are sorted. May be one of 'asc' or 'desc'
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewResponse'
examples:
default:
$ref: '#/components/examples/ViewExecuteResponseExample'
/api/v2/views/{view_id}/export:
parameters:
- $ref: '#/components/parameters/ViewId'
get:
operationId: ExportView
tags:
- Views
summary: Zendesk Get Api V2 Views View_id Export
description: >
Returns the csv attachment of the specified view if possible. Enqueues a
job to produce the csv if necessary.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewExportResponse'
examples:
default:
$ref: '#/components/examples/ViewExportResponseExample'
/api/v2/views/{view_id}/tickets:
parameters:
- $ref: '#/components/parameters/ViewId'
get:
operationId: ListTicketsFromView
tags:
- Views
summary: Zendesk Get Api V2 Views View_id Tickets
description: |
#### Allowed For
* Agents
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
parameters:
- name: sort_by
in: query
description: >-
Sort or group the tickets by a column in the [View
columns](#view-columns) table. The `subject` and `submitter` columns
are not supported
schema:
type: string
- name: sort_order
in: query
description: >-
One of "asc" or "desc". Defaults to "asc" for alphabetical and
position sort, "desc" for all others
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketsResponse'
examples:
default:
$ref: '#/components/examples/ViewListTicketsResponseEXample'
/api/v2/views/active:
get:
operationId: ListActiveViews
tags:
- Views
summary: Zendesk Get Api V2 Views Active
description: >
Lists active shared and personal views available to the current user.
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each view, if
present
| permissions | The permissions for each view
#### Pagination
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
parameters:
- name: access
in: query
description: >-
Only views with given access. May be "personal", "shared", or
"account"
schema:
type: string
- name: group_id
in: query
description: Only views belonging to given group
schema:
type: integer
- name: sort_by
in: query
description: >-
Possible values are "alphabetical", "created_at", or "updated_at".
Defaults to "position"
schema:
type: string
- name: sort_order
in: query
description: >-
One of "asc" or "desc". Defaults to "asc" for alphabetical and
position sort, "desc" for all others
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsResponse'
examples:
default:
$ref: '#/components/examples/ViewsActiveResponseExample'
/api/v2/views/compact:
get:
operationId: ListCompactViews
tags:
- Views
summary: Zendesk Get Api V2 Views Compact
description: >
A compacted list of shared and personal views available to the current
user. This endpoint never returns more than 32 records and does not
respect the "per_page" option.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsResponse'
examples:
default:
$ref: '#/components/examples/ViewsResponseExample'
/api/v2/views/count:
get:
operationId: CountViews
tags:
- Views
summary: Zendesk Get Api V2 Views Count
description: >-
Returns an approximate count of shared and personal views available to
the current user. 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
responses:
'200':
description: Count of views
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsCountResponse'
examples:
default:
$ref: '#/components/examples/ViewsCountResponseExample'
/api/v2/views/count_many:
get:
operationId: GetViewCounts
tags:
- Views
summary: Zendesk Get Api V2 Views Count_many
description: >
Returns the ticket count of each view in a list of views. Accepts up to
20 view ids per request. For the ticket count of a single view, see
[Count Tickets in View](#count-tickets-in-view).
Only returns values for personal and shared views accessible to the user
performing the request.
This endpoint is rate limited to 6 requests every 5 minutes.
#### Allowed For
* Agents
parameters:
- name: ids
in: query
description: List of view's ids separated by commas.
required: true
schema:
type: string
example: 1,2,3
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewCountsResponse'
examples:
default:
$ref: '#/components/examples/ViewCountsResponseExample'
/api/v2/views/destroy_many:
delete:
operationId: BulkDeleteViews
tags:
- Views
summary: Zendesk Delete Api V2 Views Destroy_many
description: |
Deletes the views corresponding to the provided list of IDs.
#### Allowed For
* Agents
parameters:
- name: ids
in: query
description: The IDs of the views to delete
required: true
schema:
type: string
example: 1,2,3
responses:
'204':
description: No Content response
/api/v2/views/preview:
post:
operationId: PreviewViews
tags:
- Views
summary: Zendesk Post Api V2 Views Preview
description: >
You can preview views by constructing the conditions in the proper
format and nesting them under the `view` property. See [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference/).
The output can also be controlled by passing in any of the following
parameters and nesting them under the `output` property.
| Name | Type | Comment
| --------------- | ------- | -------
| columns | Array | The ticket fields to display. System
fields are looked up by name, custom fields by title or id. See the
[View columns](#view-columns) table
| group_by | String | When present, the field by which the
tickets are grouped
| group_order | String | The direction the tickets are grouped. May
be one of "asc" or "desc"
| sort_order | String | The direction the tickets are sorted. May
be one of "asc" or "desc"
| sort_by | String | The ticket field used for sorting. This
will either be a title or a custom field id.
This endpoint is rate limited to 5 requests per minute, per view, per
agent.
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewResponse'
examples:
default:
$ref: '#/components/examples/ViewPreviewResponseExample'
/api/v2/views/preview/count:
post:
operationId: PreviewCount
tags:
- Views
summary: Zendesk Post Api V2 Views Preview Count
description: |
Returns the ticket count for a single preview.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewCountResponse'
examples:
default:
$ref: '#/components/examples/ViewCountResponseExample'
/api/v2/views/search:
get:
operationId: SearchViews
tags:
- Views
summary: Zendesk Get Api V2 Views Search
description: >
#### Pagination
* Offset pagination only
See [Using Offset
Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Allowed For
* Agents
#### Sideloads
The following sideloads are supported. For more information, see
[Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/).
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each view, if
present
| permissions | The permissions for each view
parameters:
- name: query
in: query
description: Query string used to find all views with matching title
required: true
schema:
type: string
example: sales&group_id=25789188
- name: access
in: query
description: Filter views by access. May be "personal", "shared", or "account"
schema:
type: string
- name: active
in: query
description: Filter by active views if true or inactive views if false
schema:
type: boolean
- name: group_id
in: query
description: Filter views by group
schema:
type: integer
- name: sort_by
in: query
description: >-
Possible values are "alphabetical", "created_at", "updated_at", and
"position". If unspecified, the views are sorted by relevance
schema:
type: string
- name: sort_order
in: query
description: >-
One of "asc" or "desc". Defaults to "asc" for alphabetical and
position sort, "desc" for all others
schema:
type: string
- name: include
in: query
description: A sideload to include in the response. See [Sideloads](#sideloads-3)
schema:
type: string
example: permissions
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsResponse'
examples:
default:
$ref: '#/components/examples/ViewsResponseExample'
/api/v2/views/show_many:
get:
operationId: ListViewsById
tags:
- Views
summary: Zendesk Get Api V2 Views Show_many
description: >
#### Allowed For
* Agents
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each view, if
present
| permissions | The permissions for each view
parameters:
- name: ids
in: query
description: List of view's ids separated by commas.
required: true
schema:
type: string
example: 1,2,3
- name: active
in: query
description: Only active views if true, inactive views if false
schema:
type: boolean
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsResponse'
examples:
default:
$ref: '#/components/examples/ViewsResponseExample'
/api/v2/views/update_many:
put:
operationId: UpdateManyViews
tags:
- Views
summary: Zendesk Put Api V2 Views Update_many
description: |
#### Allowed For
* Agents
#### Request Parameters
The PUT request expects a `views` object that lists
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zendesk/refs/heads/main/openapi/views-openapi-original.yml