openapi: 3.1.0 info: 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 the views to update. Each view may have the following properties: | Name | Mandatory | Description | -------- | --------- | ----------- | id | yes | The ID of the view to update | position | no | The new position of the view | active | no | The active status of the view (true or false) #### Example Request Body ```js { "views": [ {"id": 25, "position": 3}, {"id": 23, "position": 5}, {"id": 27, "position": 9}, {"id": 22, "position": 7} ] } ``` responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/ViewsResponse' examples: default: $ref: '#/components/examples/ViewsUpdateManyResponseExample' components: schemas: ViewsResponse: type: object properties: count: type: integer readOnly: true next_page: type: string nullable: true readOnly: true previous_page: type: string nullable: true readOnly: true views: type: array items: $ref: '#/components/schemas/ViewObject' ViewResponse: type: object properties: columns: type: array items: type: object additionalProperties: true groups: type: array items: type: object additionalProperties: true rows: type: array items: type: object additionalProperties: true view: $ref: '#/components/schemas/ViewObject' ViewCountResponse: type: object properties: view_count: $ref: '#/components/schemas/ViewCountObject' ViewExportResponse: type: object properties: export: type: object properties: status: type: string readOnly: true view_id: type: integer readOnly: true TicketsResponse: type: object properties: tickets: type: array items: $ref: '#/components/schemas/TicketObject' ViewsCountResponse: type: object properties: count: type: object properties: refreshed_at: type: string format: date-time value: type: integer ViewCountsResponse: type: object properties: view_counts: type: array items: $ref: '#/components/schemas/ViewCountObject' tags: - name: Views