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 Creating views to manage ticket workflow.

JSON format

Views are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
activebooleanfalsefalseWhether the view is active
conditionsobjectfalsefalseDescribes how the view is constructed. See Conditions reference
created_atstringtruefalseThe time the view was created
defaultbooleantruefalseIf true, the view is a default view
descriptionstringfalsefalseThe description of the view
executionobjectfalsefalseDescribes how the view should be executed. See Execution
idintegertruefalseAutomatically assigned when created
positionintegerfalsefalseThe position of the view
restrictionobjectfalsefalseWho may access this account. Is null when everyone in the account can access it
titlestringfalsefalseThe title of the view
updated_atstringtruefalseThe 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.

NameTypeComment
group_by, sort_bystringSort or group the tickets by a column in the View columns table. The subject and submitter columns are not supported
group_order, sort_orderstringEither "asc" or "desc"
columnsarrayThe ticket fields to display. Custom fields have an id, title, type, and url referencing the ticket field
groupobjectWhen present, the structure indicating how the tickets are grouped
sortobjectThe 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": []  },  "default": false,  "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 <12 Hours"}

List Views

  • GET /api/v2/views

Lists shared and personal views available to the current user.

Sideloads

The following sideloads are supported:

NameWill sideload
app_installationThe app installation that requires each view, if present
permissionsThe permissions for each view

Pagination

  • Cursor pagination (recommended, but only sorts by created_at)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
accessstringQueryfalseOnly views with given access. May be "personal", "shared", or "account"
activebooleanQueryfalseOnly active views if true, inactive views if false
group_idintegerQueryfalseOnly views belonging to given group
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views.json \  -v -u {email}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views?access=&active=&group_id=&sort_by=&sort_order="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/views")		.newBuilder()		.addQueryParameter("access", "")		.addQueryParameter("active", "")		.addQueryParameter("group_id", "")		.addQueryParameter("sort_by", "")		.addQueryParameter("sort_order", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/views',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'access': '',    'active': '',    'group_id': '',    'sort_by': '',    'sort_order': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/views?access=&active=&group_id=&sort_by=&sort_order="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/views")uri.query = URI.encode_www_form("access": "", "active": "", "group_id": "", "sort_by": "", "sort_order": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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"    }  ]}

Count Views

  • GET /api/v2/views/count
  • GET /api/v2/views/count

Returns an approximate count of shared and personal views available to the current user. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates when the count was last updated.

Note: When the count exceeds 100,000, count[refreshed_at] may occasionally be null. This indicates that the count is being updated in the background, and count[value] is limited to 100,000 until the update is complete.

Allowed For

  • Agents

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views/count.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views/count"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/views/count")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/views/count',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/views/count"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/views/count")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "count": {    "refreshed_at": "2020-04-06T02:18:17Z",    "value": 16  }}

List Views By ID

  • GET /api/v2/views/show_many?ids={ids}

Allowed For

  • Agents

Sideloads

The following sideloads are supported:

NameWill sideload
app_installationThe app installation that requires each view, if present
permissionsThe permissions for each view

Parameters

NameTypeInRequiredDescription
activebooleanQueryfalseOnly active views if true, inactive views if false
idsstringQuerytrueList of view's ids separated by commas.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views/show_many.json?ids=25,23 \  -v -u {email}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views/show_many?active=&ids=1%2C2%2C3"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/views/show_many")		.newBuilder()		.addQueryParameter("active", "")		.addQueryParameter("ids", "1,2,3");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/views/show_many',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'active': '',    'ids': '1%2C2%2C3',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/views/show_many?active=&ids=1%2C2%2C3"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/views/show_many")uri.query = URI.encode_www_form("active": "", "ids": "1,2,3")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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 Active Views

  • GET /api/v2/views/active

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

Sideloads

The following sideloads are supported:

NameWill sideload
app_installationThe app installation that requires each view, if present
permissionsThe permissions for each view

Pagination

  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
accessstringQueryfalseOnly views with given access. May be "personal", "shared", or "account"
group_idintegerQueryfalseOnly views belonging to given group
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views/active.json \  -v -u {email}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views/active?access=&group_id=&sort_by=&sort_order="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/views/active")		.newBuilder()		.addQueryParameter("access", "")		.addQueryParameter("group_id", "")		.addQueryParameter("sort_by", "")		.addQueryParameter("sort_order", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/views/active',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'access': '',    'group_id': '',    'sort_by': '',    'sort_order': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/views/active?access=&group_id=&sort_by=&sort_order="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/views/active")uri.query = URI.encode_www_form("access": "", "group_id": "", "sort_by": "", "sort_order": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views/compact.json \  -v -u {email}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views/compact"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/views/compact")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/views/compact',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://example.zendesk.com/api/v2/views/compact"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://example.zendesk.com/api/v2/views/compact")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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"    }  ]}

Search Views

  • GET /api/v2/views/search?query={query}

Pagination

  • Offset pagination only

See Using Offset Pagination.

Allowed For

  • Agents

Sideloads

The following sideloads are supported. For more information, see Side-loading.

NameWill sideload
app_installationThe app installation that requires each view, if present
permissionsThe permissions for each view

Parameters

NameTypeInRequiredDescription
accessstringQueryfalseFilter views by access. May be "personal", "shared", or "account"
activebooleanQueryfalseFilter by active views if true or inactive views if false
group_idintegerQueryfalseFilter views by group
includestringQueryfalseA sideload to include in the response. See Sideloads
querystringQuerytrueQuery string used to find all views with matching title
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the views are sorted by relevance
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/views/search.json?query=unsolved \  -v -u {email}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/views/search?access=&active=&group_id=&include=permissions&query=sales%26group_id%3D25789188&sort_by=&sort_order="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))