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 simple flat JSON objects which have the following keys.

Name Type Comment
id integer Automatically assigned when created
title string The title of the view
active boolean Useful for determining if the view should be displayed
sla_id integer If the view is for an SLA this is the id
restriction object Who may access this account. Will be null when everyone in the account can access it.
execution Execute An object describing how the view should be executed
conditions Conditions An object describing how the view is constructed
created_at date The time the view was created
updated_at date The time of the last update of the view
Example
{
  "view": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "active": true,
    "sla_id": 23842,
    "execution": { ... },
    "conditions": [ ... ],
    "restriction": {
      "type": "User",
      "id": 4
    }
  }
}

Execution

View Execution is a read-only object that describes how to display a collection of tickets in a 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

Conditions 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, all_agents, 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.

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, bad, true (unoffered), or false (offered)

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
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)
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
type_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
Via type Value
Web form 0
Email 4
Chat 29
Twitter 30
Twitter DM 26
Twitter favorite 23
Voicemail 33
Phone call (incoming) 34
Phone call (outbound) 35
Get Satisfaction 16
Feedback Tab 17
Web service (API) 5
Trigger or automation 8
Forum topic 24
Closed ticket 27
Ticket sharing 31
Facebook post 38
Facebook private message 41
Zendesk widget 48

List Views

GET /api/v2/views.json

Lists shared and personal Views available to the current user

Allowed For:
  • Agents
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",
      "active": true,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    {
      "id": 23,
      "title": "Unassigned tickets",
      "active": false,
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

List Active Views

GET /api/v2/views/active.json

Lists active shared and personal Views available to the current user

Allowed For:
  • Agents
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",
      "active": true
      "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

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",
      "active": true
      "execution": { ... },
      "conditions": { ... },
      "restriction": { ... }
    },
    ...
  ],
  "count": 7,
  "next_page": null,
  "previous_page": null
}

Getting Views

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",
    "active": true
    "execution": { ... },
    "conditions": { ... },
    "restriction": { ... }
  }
}

Create View

POST /api/v2/views.json

Allowed For
  • Agents
Using curl
curl -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/views.json \
  -H "Content-Type: application/json" -X POST -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" }]}}'
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.

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.
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 the View columns table.
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 the group or user.
Example request
{
  "view": {
    "title": "Kelly's tickets",
    "active": true,
    "restriction": {
      "type": "User",
      "id": "213977756"
    },
    "all": [
      {
        "field": "status",
        "operator": "less_than",
        "value": "solved"
      },
      {
        "field": "group_id",
        "operator": "is",
        "value": "24000932"
      },
      ...
    ],
    "output": {
      "columns": ["status", "requester", "assignee"],
      "group_by": "assignee",
      "group_order": "desc",
      "sort_by": "status",
      "sort_order": "desc"
    }
  }
}
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.

View columns

For default ticket fields, specify the column values in the following table. For custom fields, specify the field's title or id. You can add a total of 10 columns.

View column Value
Assigned date assigned
Assignee assignee
Due Date due_date
Group group
ID nice_id
Latest update updated
Latest update by assignee updated_assignee
Latest update by requester updated_requester
Latest updater type (agent/end-user) updated_by_type
Organization organization
Priority priority
Request date created
Requester requester
Requester language locale_id
Satisfaction satisfaction_score
Score score
Solved date solved
Status status
Subject description
Submitter submitter
Ticket form ticket_form
Ticket type type
Brand brand
View sorting

You can group and sort items in the view by adding items to the output element:

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 -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/views/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"view": {"title": "Roger Wilco II"}}'
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.

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 the View columns table.
restriction An object that describes who can access the view.

You can also update how items are sorted and grouped. See View sorting in Create View.

Example request
{
  "view": {
    "title": "Code red tickets",
    "all": [
      {
        "field": "priority",
        "operator": "is",
        "value": "urgent"
      }
    ],
    "output": {
      "columns": ["status", "requester", "assignee", "updated"]
    }
  }
}
Note

Updating a condition updates the containing array, clearing the other conditions. Include all your conditions when updating any condition.

Delete View

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

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

Executing Views

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

You execute a view in order to get the tickets that fulfill the conditions of the view.

The view execution system is designed for periodic rather than high-frequency API usage. In particular, views that are called very frequently by an API client (more often than once every 5 minutes on average) may be cached by our software. 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.

If you're looking for a method to get the latest changes to your Zendesk, we recommend the incremental tickets API. It can be called as often as once a minute, and will return all the tickets that changed since the last poll.

View output sorting can be controlled by passing the sort_by and sort_order parameters in the format described in the table under view previewing.

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": [ ... ]
}

Getting Tickets from a view

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

Allowed For
  • Agents
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 APIs allow an API consumer to estimate how many tickets remain in a View without having to retrieve the entire View. These APIs are intended to help estimate View size; from a business perspective, accuracy becomes less relevant as your 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 its count to be cached for 60-90 minutes and may not reflect the actual number of tickets in your View.

View Counts

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

Calculates the size of the view in terms of number of tickets the view will return. Only returns values for personal and shared views accessible to the user performing the request.

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

When you retrieve view counts that are not "fresh", it's recommended to wait for a short while an poll again for only the stale view counts.

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

View Count

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

Returns the ticket count for a single view.

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

Exporting Views

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

Returns the csv attachment of the current view if possible. Enqueues 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"
  }
}

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.
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

GET /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
  }
}