Support API

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 Comment
id integer yes Automatically assigned when created
title string no The title of the view
active boolean no Whether the view is active
restriction object no Who may access this account. Is null when everyone in the account can access it
position integer no The position of the view
execution object no Describes how the view should be executed. See Execution
conditions object no Describes how the view is constructed. See Conditions
description string no The description of the view
created_at date yes The time the view was created
updated_at date yes The time the view was last updated
Example
 
{
  "view": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "description": "View for recent tickets",
    "active": true,
    "position": 8,
    "execution": { ... },
    "conditions": [ ... ],
    "restriction": {
      "type": "User",
      "id": 4
    }
  }
}

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" }
   }
}

Conditions

The conditions object contains the conditions to check the value of ticket fields and select the ticket if the conditions are met. Conditions are represented as a JSON object with two arrays of one or more conditions.

Example

{
   "conditions": {
     "all": [
       { "field": "status", "operator": "less_than", "value": "solved" },
       { "field": "assignee_id", "operator": "is", "value": "296220096" }
     ],
     "any": [
     ]
   }
}

The first array lists all the conditions that must be met. The second array lists any condition that must be met.

Name Type Description
all array Logical AND. Tickets must fulfill all of the conditions to be considered matching
any array Logical OR. Tickets may satisfy any of the conditions to be considered matching

Each condition in an array has the following properties:

Name Type Description
field string The name of a ticket field
operator string A comparison operator
value string The value of a ticket field

Example

{ "field": "status", "operator": "less_than", "value": "solved" }

When specifying conditions in a PUT or POST request, use the "all" and "any" arrays without the "conditions" key. Example:

{
  "all": [
    { "field": "status", "operator": "less_than", "value": "solved" },
    { "field": "assignee_id", "operator": "is", "value": "296220096" }
  ],
  "any": [
    { "field": "current_tags", "operator": "includes", "value": "hello" }
  ],
  ...
}
Conditions reference

The following tables list the fields, allowed operators, and values of the conditions used in triggers, automations, views and SLA policies.

Common conditions

The following conditions are shared by triggers, automations, views and SLA policies.

field operator value
group_id is, is_not "" (no group assigned to the ticket) or the numeric ID of the group assigned to the ticket.
assignee_id is, is_not "" (nobody assigned to the ticket), current_user, or the numeric ID of the agent assigned to the ticket.
requester_id is, is_not "" (no requester specified), current_user or the numeric ID of the requester or assignee.
organization_id is, is_not "" (no organization added to the ticket) or the numeric ID of the organization added to the ticket.
current_tags includes, not_includes A space-delimited list of tags to compare against the ticket's tags.
via_id is, is_not The numeric ID of the channel used to create the ticket. See the Via Types table.
recipient Omit the operator property For views and automations, the account name in the email address from which the ticket was received. For triggers and SLA policies, the full email address, which can include external addresses.
custom_fields_{id} is, is_not Specify the id of the custom ticket field. See Ticket fields. Possible values vary depending on the field. See Setting custom field values.

The following conditions are shared by triggers, automations, and views.

field operator value
type is, is_not question, incident, problem, or task
status is,
is_not,
less_than,
greater_than		 new, open, pending, hold, solved, or closed
priority is,
is_not,
less_than,
greater_than		 "" (no priority assigned to the ticket), low, normal, high, or urgent
description_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in the ticket subject. Not available in triggers.
locale_id is, is_not The numeric ID of the locale of the person who submitted the ticket. See List locales to list the available locale IDs for the account.
satisfaction_score is,
is_not,
less_than,
greater_than		 good_with_comment, good, bad_with_comment, bad, false (offered), or true (unoffered)

The following conditions are shared by triggers and automations.

field operator value
user.custom_fields_{key} is,
is_not,
present (omit value),
not_present (omit value),
includes (contains one word),
not_includes (contains none of the words),
includes_string (contains string),
not_includes_string (does not contain string)		 Specify the key of the custom user field. See User fields. Possible values vary depending on the field. See user_fields in the Users API.
organization.custom_fields_{key} is,
is_not,
present (omit value),
not_present (omit value),
includes (contains one word),
not_includes (contains none of the words),
includes_string (contains string),
not_includes_string (does not contain string)		 Specify the key of the custom organization field. See Organization fields. Possible values vary depending on the field. See organization_fields in the Organizations API.

Triggers have the following additional operators for some shared fields.

Fields Additional trigger operators
status,
type,
priority,
group_id,
assignee_id,
requester_id,
organization_id,
satisfaction_ score		 changed (omit value property),
value (changed to),
value_previous (changed from),
not_changed,
not_value (not changed to),
not_value_previous (not changed from)
Additional trigger conditions

Triggers have the following additional conditions.

field operator value
subject_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in the subject.
comment_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in either the subject or body of the comment.
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
update_type Omit the operator property. Create or Change
comment_is_public Omit the operator property. true, false, not_relevant (present), or requester_can_see_comment (present and requester can see comment)
ticket_is_public Omit the operator property. public, private
reopens less_than, greater_than, or is The number of times a ticket has moved from Solved to Open or Pending.
replies less_than, greater_than, or is The number of public agent comments.
agent_stations less_than, greater_than, or is The number of different agents to which a ticket has been assigned.
group_stations less_than, greater_than, or is The number of different groups to which a ticket has been assigned.
in_business_hours Omit the operator property. true or false. Available only if an administrator enabled business hours.
requester_twitter_followers_count less_than, greater_than, or is The number of the requester's Twitter followers.
requester_twitter_statuses_count less_than, greater_than, or is The total number of the requester's tweets.
requester_twitter_verified Omit the operator property Omit the value property. The condition is true if the requester has a verified Twitter account.
Additional SLA Policies conditions

SLA Policies have the following additional conditions.

field operator value
ticket_type_id is, is_not The numeric ID of the ticket type: 1 (question), 2 (incident), 3 (problem), or 4 (task)
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
exact_created_at less_than, less_than_equal, greater_than or greater_than_equal The time the ticket was created.
Additional time-based conditions for automations and views

Automations and views have the following time-based conditions. Time-based conditions can only be used in all arrays, not in any arrays.

field value
NEW Hours since the ticket was created.
OPEN Hours since the ticket was opened.
PENDING Hours since the ticket was changed to pending.
SOLVED Hours since the ticket was changed to solved.
CLOSED Hours since the ticket was closed.
assigned_at Hours since assigned.
updated_at Hours since update.
requester_updated_at Hours since requester update.
assignee_updated_at Hours since assignee update.
due_date Hours since the due date. For tickets with the type set to Task.
until_due_date Hours until the due date. For tickets with the type set to Task.

The time-based conditions all share the same operator values:

operator
is
is_business_hours
less_than
less_than_business_hours
greater_than
greater_than_business_hours
Via Types
Description via type via id
Web form web_form 0
Email mail 4
Chat chat 29
Twitter twitter 30
Twitter DM twitter_dm 26
Twitter like twitter_favorite 23
Voicemail voicemail 33
Phone call (incoming) phone_call_inbound 34
Phone call (outbound) phone_call_outbound 35
CTI* voicemail api_voicemail 44
CTI phone call (inbound) api_phone_call_inbound 45
CTI phone call (outbound) api_phone_call_outbound 46
SMS sms 57
Get Satisfaction get_satisfaction 16
Web Widget web_widget 48
Mobile SDK mobile_sdk 49
Mobile mobile 56
Help Center post helpcenter 50
Web service (API) web_service 5
Trigger, automation rule 8
Closed ticket closed_ticket 27
Ticket sharing ticket_sharing 31
Facebook post facebook_post 38
Facebook private message facebook_message 41
Satisfaction prediction satisfaction_prediction 54
Channel framework any_channel 55
LINE line 72
WeChat wechat 73
WhatsApp whatsapp 74

*CTI - Computer Telephony Integration

List Views

GET /api/v2/views.json

Lists shared and personal views available to the current user.

Allowed For
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
access string Only views with given access. May be "personal", "shared", or "account"
active boolean Only active views if true, inactive views if false
group_id integer Only views belonging to given group
sort_by string Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
sort_order string One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "views": [
    {
      "id": 25,
      "title": "Tickets updated <12 Hours",
      "raw_title": "{{dc.tickets_updated_last_12_hours}}",
      "description": "View for recent tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    {
      "id": 23,
      "title": "Unassigned tickets",
      "raw_title": "{{dc.unassigned_tickets}}",
      "description": "View for tickets that are not assigned",
      "active": false,
      "position": 7,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

List Views by ID

GET /api/v2/views/show_many.json?ids=1,2,3

Allowed For
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
ids list of id List of view's ids separated by commas.
active boolean Only active views if true, inactive views if false
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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/show_many.json?ids=1,2,3 \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "views": [
    {
      "id": 25,
      "title": "Tickets updated <12 Hours",
      "raw_title": "{{dc.tickets_updated_last_12_hours}}",
      "description": "View for recent tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    {
      "id": 23,
      "title": "Unassigned tickets",
      "raw_title": "{{dc.unassigned_tickets}}",
      "description": "View for tickets that are not assigned",
      "active": false,
      "position": 7,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

Update Many Views

PUT /api/v2/views/update_many.json

Allowed For
  • Agents
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": [
    {
      "id": 25,
      "title": "Tickets updated <12 Hours",
      "title": "{{dc.tickets_updated_last_12_hours}}",
      "description": "View for recent tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    {
      "id": 23,
      "title": "Unassigned tickets",
      "title": "{{dc.unassigned_tickets}}",
      "description": "View for tickets that are not assigned",
      "active": false,
      "position": 5,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ]
}

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}
  ]
}

List Active Views

GET /api/v2/views/active.json

Lists active shared and personal views available to the current user.

Allowed For
  • Agents
Available Parameters

You can use any combination of the following optional filters:

Name Type Comment
access string Only views with given access. May be "personal", "shared", or "account"
group_id integer Only views belonging to given group
sort_by string Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
sort_order string One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/active.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "views": [
    {
      "id": 25,
      "title": "Tickets updated <12 Hours",
      "raw_title": "{{dc.tickets_updated_last_12_hours}}",
      "description": "View for recent tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

List Views - Compact

GET /api/v2/views/compact.json

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

{
  "views": [
    {
      "id": 25,
      "title": "Tickets updated <12 Hours",
      "raw_title": "{{dc.tickets_updated_last_12_hours}}",
      "description": "View for recent tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

Show View

GET /api/v2/views/{id}.json

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/{id}.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "view": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "raw_title": "{{dc.tickets_updated_last_12_hours}}",
    "description": "View for recent tickets",
    "active": true,
    "position": 3,
    "execution": { ... },
    "conditions": { ... },
    "restriction": { ... }
  }
}

Create View

POST /api/v2/views.json

Allowed For
  • Agents
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: 201 Created
Location: /api/v2/view/{new-view-id}.json

{
  "view": {
    "id":   9873843,
    "title": "Roger Wilco",
    ...
  }
}

Request Parameters

The POST request takes one parameter, 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
any An array of one or more conditions. A ticket must meet any of them to be included in the view. See Conditions
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"

Update View

PUT /api/v2/views/{id}.json

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/{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": {
    "id":   9873843,
    "title": "Roger Wilco II",
    ...
  }
}

Request Parameters

The PUT request takes one parameter, 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
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
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"]
    }
  }
}

Delete View

DELETE /api/v2/views/{id}.json

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/{id}.json \
  -H "Content-Type: application/json" \
  -v -u {email}:{password} -X DELETE
Example Response
 
Status: 200 OK

Bulk Delete Views

DELETE /api/v2/views/destroy_many.json

Deletes the views corresponding to the provided list of IDs.

Allowed For
  • Agents
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

Request Parameters

The DELETE request takes one parameter, an ids object that lists the views to delete.

Name Description
ids The IDs of the views to delete
Example Request Body
 
{
  "ids": "25,23,27,22"
}

Execute View

GET /api/v2/views/{id}/execute.json

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 dislayed 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 Previewing Views.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/{id}/execute.json \
  -v -u {email}:{password}

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

{
  "view": {
    "id": 25,
    "url": ...
  },
  "rows": [
    {
      "ticket": { ... },
      "locale": "en-US",
      "group": 1,
      ...
    },
    ...
  ],
  "columns": [
    {
      "id": "locale",
      "title": "Locale"
    },
    {
      "id": 5,
      "title": "Account",
      "url": ...
    },
    ...
  ],
 "groups": [ ... ]
}

List Tickets from a View

GET /api/v2/views/{id}/tickets.json

Allowed For
  • Agents
Available Parameters

You can pass in any combination of the following optional filters, which will override the view settings.

Name Type Comment
sort_by string An item from the View columns table
sort_order string 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/{id}/tickets.json \
  -v -u {email}:{password}
Example Responses
 
Status: 200 OK

{
  "tickets": [
    {
      "id":      35436,
      "subject": "Help I need somebody!",
      ...
    },
    {
      "id":      20057623,
      "subject": "Not just anybody!",
      ...
    },
  ]
}

View Counts and Caching

The view count endpoints lets 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
  }
}

If the response indicates that the cached data is not fresh ("fresh": false), then the system is loading and caching new data. During this time, the count will be null ("value": null) and the text approximation will be "..." ("pretty": "..."). Make the request again after a short wait.

Get View Counts

GET /api/v2/views/count_many.json?ids={view_id},{view_id}

Calculates the number of tickets each view will return. 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
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": [
    {
      "view_id": 25,
      "url":     "https://company.zendesk.com/api/v2/views/25/count.json",
      "value":   719,
      "pretty":  "~700",
      "fresh":   true
    },
    {
      "view_id": 78,
      "url":     "https://company.zendesk.com/api/v2/views/78/count.json",
      "value":   null,
      "pretty":  "...",
      "fresh":   false

Get View Count

GET /api/v2/views/{id}/count.json

Returns the ticket count for a single view.

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/{id}/count.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "view_count": {
    "view_id": 25,
    "url":     "https://company.zendesk.com/api/v2/views/25/count.json",
    "value":   719,
    "pretty":  "~700",
    "fresh":   true

Export View

GET /api/v2/views/{id}/export.json

Returns the csv attachment of the specified view if possible. Enqueues a job to produce the csv if necessary.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/views/{id}/export.json \
  -v -u {email}:{password}
Example Response
 
Status: 200

{
  "export": {
    "view_id": 25,
    "status": "starting"
  }
}

Search Views

GET /api/v2/views/search.json

Allowed For
  • Agents
Available Parameters

Required

Name Type Comment
query string Query string used to find all views with matching title

Optional

You can use any combination of the following optional parameters:

Name Type Comment
access string Only views with given access. May be "personal", "shared", or "account"
active boolean Only active views if true, inactive views if false
group_id integer Only views belonging to given group
sort_by string Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the views are sorted by relevance
sort_order string One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Example queries

  • /api/v2/views/search.json?query=unassigned
  • /api/v2/views/search.json?query=sales&group_id=25789188
  • /api/v2/views/search.json?query=dev&access=shared
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
Using curl:
 
curl https://{subdomain}.zendesk.com/api/v2/views/search.json?query=unsolved \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "views": [
    {
      "id": 25,
      "title": "Your unsolved tickets",
      "active": true,
      "position": 3,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    {
      "id": 23,
      "title": "All unsolved tickets",
      "active": true,
      "position": 7,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    }
  ],
  "count": 2,
  "next_page": null,
  "previous_page": null
}

Previewing Views

POST /api/v2/views/preview.json

Views can be previewed by constructing the conditions in the proper format and nesting them under the 'view' key. 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

{
  "rows": [
    {
      "ticket": { ... },
      "subject": "en-US",
      ...
    },
    ...
  ],
  "columns": [
    {
      "id": "subject",
      "title": "Subject"
    },
    ...
  ]
}

Preview Count

POST /api/v2/views/preview/count.json

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": {
    "view_id": null,
    "url":     null,
    "value":   719,
    "pretty":  "~700",
    "fresh":   true
  }
}