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