Views
A view consists of one or more conditions that define a collection of tickets to display. If the conditions are met, the ticket is included in the view. For example, a view can display all open tickets that were last updated more than 24 hours ago.
For more information, see Using views to manage ticket workflow.
JSON Format
Views are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
active | boolean | false | false | Whether the view is active |
conditions | object | false | false | Describes how the view is constructed. See Conditions reference |
created_at | string | true | false | The time the view was created |
description | string | false | false | The description of the view |
execution | object | false | false | Describes how the view should be executed. See Execution |
id | integer | true | false | Automatically assigned when created |
position | integer | false | false | The position of the view |
restriction | object | false | false | Who may access this account. Is null when everyone in the account can access it |
title | string | false | false | The title of the view |
updated_at | string | true | false | The time the view was last updated |
Execution
A view's execution
object is a read-only object that describes how to display a collection of tickets in the view.
Name | Type | Comment |
---|---|---|
group_by, sort_by | string | An item from the View columns table |
group_order, sort_order | string | Either "asc" or "desc" |
columns | array | The ticket fields to display. Custom fields have an id, title, type, and url referencing the ticket field |
group | object | When present, the structure indicating how the tickets are grouped |
sort | object | The column structure of the field used for sorting |
Example
{
"execution": {
"columns": [
{ "id": "status", "title": "Status" },
{ "id": "updated", "title": "Updated" },
{
"id": 5, "title": "Account", "type": "text",
"url": "https://example.zendesk.com/api/v2/ticket_fields/5.json"
},
...
]
"group": { "id": "status", "title": "Status", "order": "desc" },
"sort": { "id": "updated", "title": "Updated", "order": "desc" }
}
}
Example
{
"active": true,
"conditions": {
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "assignee_id",
"operator": "is",
"value": "296220096"
}
],
"any": []
},
"description": "View for recent tickets",
"execution": {
"columns": [
{
"id": "status",
"title": "Status"
},
{
"id": "updated",
"title": "Updated"
},
{
"id": 5,
"title": "Account",
"type": "text",
"url": "https://example.zendesk.com/api/v2/ticket_fields/5.json"
}
],
"group": {
"id": "status",
"order": "desc",
"title": "Status"
},
"sort": {
"id": "updated",
"order": "desc",
"title": "Updated"
}
},
"id": 25,
"position": 8,
"restriction": {
"id": 4,
"type": "User"
},
"title": "Tickets updated \u003c12 Hours"
}
List Views
GET /api/v2/views
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 |
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
access | string | Query | false | Only views with given access. May be "personal", "shared", or "account" |
active | boolean | Query | false | Only active views if true, inactive views if false |
group_id | integer | Query | false | Only views belonging to given group |
sort_by | string | Query | false | Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position" |
sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
},
{
"active": false,
"conditions": {},
"description": "View for tickets that are not assigned",
"execution": {},
"id": 23,
"position": 7,
"restriction": {},
"title": "Unassigned tickets"
}
]
}
Create View
POST /api/v2/views
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 |
any | An array of one or more conditions. A ticket must meet any of them to be included in the view. See 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 |
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
{
"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 |
Latest update by assignee | updated_assignee |
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 | status |
Subject | description |
Submitter | submitter |
Ticket form | ticket_form |
Type | type |
Brand | brand |
View sorting
You can group and sort items in the view by adding items to the output
parameter:
Attribute | Description |
---|---|
group_by , sort_by |
An item from the View columns table |
group_order , sort_order |
Either "asc" or "desc" |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views.json \
-d '{"view": {"title": "Roger Wilco", "all": [{"field": "status", "operator": "is", "value": "open"}, {"field": "priority", "operator": "less_than", "value": "high"}], "any": [{ "field": "current_tags", "operator": "includes", "value": "hello" }]}}' \
-H "Content-Type: application/json" \
-v -u {email}:{password} -X POST
Example Response
Status 200 OK
{
"view": {
"active": true,
"conditions": {
"all": [
{
"field": "status",
"operator": "is",
"value": "open"
},
{
"field": "priority",
"operator": "less_than",
"value": "high"
}
],
"any": [
{
"field": "current_tags",
"operator": "includes",
"value": "hello"
}
]
},
"id": 9873843,
"title": "Roger Wilco"
}
}
List Active Views
GET /api/v2/views/active
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 |
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
access | string | Query | false | Only views with given access. May be "personal", "shared", or "account" |
group_id | integer | Query | false | Only views belonging to given group |
sort_by | string | Query | false | Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position" |
sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/active.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
},
{
"active": true,
"conditions": {},
"description": "View for tickets that are not assigned",
"execution": {},
"id": 23,
"position": 7,
"restriction": {},
"title": "Unassigned tickets"
}
]
}
List Views - Compact
GET /api/v2/views/compact
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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/compact.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
},
{
"active": false,
"conditions": {},
"description": "View for tickets that are not assigned",
"execution": {},
"id": 23,
"position": 7,
"restriction": {},
"title": "Unassigned tickets"
}
]
}
Get View Counts
GET /api/v2/views/count_many?ids={ids}
Calculates the number of tickets each view will return. See View Counts. Accepts up to 20 view ids per request.
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 | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | List of view's ids separated by commas. |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/count_many.json?ids={view_id} \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"view_counts": [
{
"fresh": true,
"pretty": "~700",
"url": "https://company.zendesk.com/api/v2/views/25/count.json",
"value": 719,
"view_id": 25
},
{
"fresh": false,
"pretty": "...",
"url": "https://company.zendesk.com/api/v2/views/78/count.json",
"value": null,
"view_id": 78
}
]
}
Bulk Delete Views
DELETE /api/v2/views/destroy_many?ids={ids}
Deletes the views corresponding to the provided list of IDs.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | The IDs of the views to delete |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/destroy_many.json?ids=1,2,3 \
-v -u {email}:{password} -X DELETE
Example Response
Status 204 No Content
Preview Views
POST /api/v2/views/preview
Views can be previewed by constructing the conditions in the proper format and nesting them under the 'view' key. See Conditions reference. The output can also be controlled by passing in any of the following parameters and nesting them under the 'output' key.
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 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.
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/preview.json \
-v -u {email}:{password} -X POST -H "Content-Type: application/json" \
-d '{"view": {"all": [{"operator": "is", "value": "open", "field": "status"}], "output": {"columns": ["subject"]}}}'
Example Response
Status 200 OK
{
"columns": [
{
"id": "subject",
"title": "Subject"
}
],
"rows": [
{
"subject": "en-US",
"ticket": {}
}
]
}
Preview Count
POST /api/v2/views/preview/count
Returns the ticket count for a single preview.
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/preview/count.json \
-v -u {email}:{password} -X POST -H "Content-Type: application/json" \
-d '{"view": {"all": [{"operator": "is", "value": "open", "field": "status"}]}}'
Example Response
Status 200 OK
{
"view_count": {
"fresh": true,
"pretty": "~700",
"url": "https://company.zendesk.com/api/v2/views/25/count.json",
"value": 719,
"view_id": 25
}
}
Search Views
GET /api/v2/views/search
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 | Type | In | Required | Description |
---|---|---|---|---|
access | string | Path | false | Only views with given access. May be "personal", "shared", or "account" |
active | boolean | Path | false | Only active views if true, inactive views if false |
group_id | integer | Path | false | Only views belonging to given group |
query | string | Path | true | Query string used to find all views with matching title |
sort_by | string | Path | false | Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the views are sorted by relevance |
sort_order | string | Path | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/search.json?query=unsolved \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
},
{
"active": false,
"conditions": {},
"description": "View for tickets that are not assigned",
"execution": {},
"id": 23,
"position": 7,
"restriction": {},
"title": "Unassigned tickets"
}
]
}
List Views By ID
GET /api/v2/views/show_many?ids={ids}
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 | Type | In | Required | Description |
---|---|---|---|---|
active | boolean | Query | false | Only active views if true, inactive views if false |
ids | string | Query | true | List of view's ids separated by commas. |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/show_many.json?ids=25,23 \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
},
{
"active": false,
"conditions": {},
"description": "View for tickets that are not assigned",
"execution": {},
"id": 23,
"position": 7,
"restriction": {},
"title": "Unassigned tickets"
}
]
}
Update Many Views
PUT /api/v2/views/update_many
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
{
"views": [
{"id": 25, "position": 3},
{"id": 23, "position": 5},
{"id": 27, "position": 9},
{"id": 22, "position": 7}
]
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/update_many.json \
-d '{"views": [{"id": 123, "position": 8}]}' \
-H "Content-Type: application/json" \
-v -u {email}:{password} -X PUT
Example Response
Status 200 OK
{
"views": [
{
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 123,
"position": 8,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
}
]
}
Show View
GET /api/v2/views/{view_id}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"view": {
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Tickets updated less than 12 Hours"
}
}
Update View
PUT /api/v2/views/{view_id}
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 |
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 |
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 |
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 in Create View.
Example Request Body
{
"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"]
}
}
}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}.json \
-d '{"view": {"title": "Roger Wilco II"}}' \
-H "Content-Type: application/json" \
-v -u {email}:{password} -X PUT
Example Response
Status 200 OK
{
"view": {
"active": true,
"conditions": {},
"description": "View for recent tickets",
"execution": {},
"id": 25,
"position": 3,
"restriction": {},
"title": "Roger Wilco II"
}
}
Delete View
DELETE /api/v2/views/{view_id}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}.json \
-H "Content-Type: application/json" \
-v -u {email}:{password} -X DELETE
Example Response
Status 204 No Content
Get View Count
GET /api/v2/views/{view_id}/count
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, Get View Count (this endpoint) and Get View Counts, 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
{
"view_count": {
"view_id": 25,
"url": "https://company.zendesk.com/api/v2/views/25/count.json",
"value": 719,
"pretty": "~700",
"fresh": true
}
}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}/count.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"view_count": {
"fresh": true,
"pretty": "~700",
"url": "https://company.zendesk.com/api/v2/views/25/count.json",
"value": 719,
"view_id": 25
}
}
Execute View
GET /api/v2/views/{view_id}/execute
Returns the column titles and the rows of the specified view.
The columns
array lists the view's column titles.
The rows
array lists the values of each column for each ticket. 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.
This endpoint is rate limited to 5 requests per minute, per view, per agent.
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.
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.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
sort_by | string | Query | false | The ticket field used for sorting. This will either be a title or a custom field id. |
sort_order | string | Query | false | The direction the tickets are sorted. May be one of 'asc' or 'desc' |
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}/execute.json \
-v -u {email}:{password}
Using curl
With sort options
curl 'https://{subdomain}.zendesk.com/api/v2/views/{id}/execute.json?sort_by=id&sort_order=desc' \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"columns": [
{
"id": "locale",
"title": "Locale"
},
{
"id": 5,
"title": "Account"
}
],
"groups": [],
"rows": [
{
"group": 1,
"locale": "en-US",
"ticket": {}
}
],
"view": {
"id": 25
}
}
Export View
GET /api/v2/views/{view_id}/export
Returns the csv attachment of the specified view if possible. Enqueues a job to produce the csv if necessary.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}/export.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"export": {
"status": "starting",
"view_id": 25
}
}
List Tickets From a View
GET /api/v2/views/{view_id}/tickets
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
sort_by | string | Query | false | An item from the View columns table |
sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
view_id | integer | Path | true | The ID of the view |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/views/{view_id}/tickets.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"tickets": [
{
"id": 35436,
"requester_id": 20978392,
"subject": "Help I need somebody!"
},
{
"id": 20057623,
"requester_id": 20978392,
"subject": "Not just anybody!"
}
]
}