Zendesk Developers :: REST API Documentation

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

{
 "view": {
   "title": "Roger Wilco",
   "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, and views.

Common conditions

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

field	operator	value
`status`	`is`, `is_not`, `less_than`, `greater_than`	`new`, `open`, `pending`, `hold`, `solved`, or `closed`
`type`	`is`, `is_not`	`question`, `incident`, `problem`, or `task`
`priority`	`is`, `is_not`, `less_than`, `greater_than`	"" (no priority assigned to the ticket), `low`, `normal`, `high`, or `urgent`
`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.
`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.
`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, the full email address, which can include external addresses.
`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 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

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

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.

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

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 however that result may have been computed at any time within the last 10 minutes.

If you are looking for a method to get the latest changes to your Zendesk via the API we recommend the ticket export API which can be called as often as once a minute, and will return all the tickets changed since 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!",
      ...
    },
  ]
}

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

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