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 Creating 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 |
default | boolean | true | false | If true, the view is a default view |
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 | Sort or group the tickets by a column in the View columns table. The subject and submitter columns are not supported |
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": []
},
"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:
Name | Will sideload |
---|---|
app_installation | The app installation that requires each view, if present |
permissions | The 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
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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/views.json \
-v -u {email_address}/token:{api_token}
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 "{email_address}/token:{api_token}"
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", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.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 "{email_address}/token:{api_token}"
},
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
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/views?access=&active=&group_id=&sort_by=&sort_order="
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
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")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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}/token:{api_token}
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 "{email_address}/token:{api_token}"
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();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.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 "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/views/count"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/views/count")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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:
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. |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/views/show_many.json?ids=25,23 \
-v -u {email_address}/token:{api_token}
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 "{email_address}/token:{api_token}"
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");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.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 "{email_address}/token:{api_token}"
},
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
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/views/show_many?active=&ids=1%2C2%2C3"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
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")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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:
Name | Will sideload |
---|---|
app_installation | The app installation that requires each view, if present |
permissions | The permissions for each view |
Pagination
- Offset pagination
See Pagination.
Returns a maximum of 100 records per page.
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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/views/active.json \
-v -u {email_address}/token:{api_token}
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 "{email_address}/token:{api_token}"
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", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.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 "{email_address}/token:{api_token}"
},
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
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/views/active?access=&group_id=&sort_by=&sort_order="
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
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")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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_address}/token:{api_token}
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 "{email_address}/token:{api_token}"
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();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.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 "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/views/compact"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/views/compact")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end