A trigger consists of one or more actions performed when a ticket is created or updated. The actions are performed only if certain conditions are met. For example, a trigger can notify the customer when an agent changes the status of a ticket to Solved.

Triggers also may depend on one or more conditions being met.

For more information on conditions and actions, see the following Help Center articles:

All your triggers are checked from first to last each time a ticket is created or updated. The order of triggers is important because the actions of one trigger may affect another trigger. New triggers are added in last place by default.

For more information, see Creating triggers for automatic ticket updates and notifications .

JSON format

Triggers are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
actionsarrayfalsetrueAn array of actions describing what the trigger will do. See Actions reference
activebooleanfalsefalseWhether the trigger is active
category_idstringfalsefalseThe ID of the category the trigger belongs to
conditionsobjectfalsetrueAn object that describes the conditions under which the trigger will execute. See Conditions reference
created_atstringtruefalseThe time the trigger was created
defaultbooleantruefalseIf true, the trigger is a default trigger
descriptionstringfalsefalseThe description of the trigger
idintegertruefalseAutomatically assigned when created
positionintegerfalsefalsePosition of the trigger, determines the order they will execute in
raw_titlestringfalsefalseThe raw format of the title of the trigger
titlestringfalsetrueThe title of the trigger
updated_atstringtruefalseThe time of the last update of the trigger
urlstringtruefalseThe url of the trigger

Example

{  "actions": [    {}  ],  "active": true,  "category_id": "10026",  "conditions": {},  "created_at": "2012-09-25T22:50:26Z",  "default": false,  "description": "Close and save a ticket",  "id": 25,  "position": 8,  "raw_title": "Close and Save",  "title": "Close and Save",  "updated_at": "2012-09-25T22:50:26Z",  "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"}

List Triggers

  • GET /api/v2/triggers

Lists all triggers for the current account.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents

Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.

NameWill sideload
app_installationThe app installation that requires each trigger, if present
permissionsThe permissions for each trigger
usage_1hThe number of times each trigger has been used in the past hour
usage_24hThe number of times each trigger has been used in the past day
usage_7dThe number of times each trigger has been used in the past week
usage_30dThe number of times each trigger has been used in the past thirty days

Parameters

NameTypeInRequiredDescription
activebooleanQueryfalseFilter by active triggers if true or inactive triggers if false
category_idstringQueryfalseFilter triggers by category ID
sortstringQueryfalseCursor-based pagination only. Possible values are "alphabetical", "created_at", "updated_at", or "position".
sort_bystringQueryfalseOffset pagination only. Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". 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/triggers.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/triggers?active=true&category_id=10026&sort=position&sort_by=position&sort_order=desc"	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/triggers")		.newBuilder()		.addQueryParameter("active", "true")		.addQueryParameter("category_id", "10026")		.addQueryParameter("sort", "position")		.addQueryParameter("sort_by", "position")		.addQueryParameter("sort_order", "desc");
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/triggers',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'active': 'true',    'category_id': '10026',    'sort': 'position',    'sort_by': 'position',    'sort_order': 'desc',  },};
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/triggers?active=true&category_id=10026&sort=position&sort_by=position&sort_order=desc"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/triggers")uri.query = URI.encode_www_form("active": "true", "category_id": "10026", "sort": "position", "sort_by": "position", "sort_order": "desc")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,  "triggers": [    {      "actions": [],      "active": true,      "conditions": {},      "created_at": "2012-09-25T22:50:26Z",      "description": "Close and save a ticket",      "id": 25,      "position": 8,      "raw_title": "Close and Save",      "title": "Close and Save",      "updated_at": "2012-09-25T22:50:26Z",      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"    },    {      "actions": [],      "active": false,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "custom_status_id",            "operator": "includes",            "value": [              "1",              "2"            ]          }        ]      },      "created_at": "2012-09-25T22:50:26Z",      "description": "Assign a ticket with a priority tag",      "id": 26,      "position": 9,      "raw_title": "{{dc.assign_priority_tag}}",      "title": "Assign priority tag",      "updated_at": "2012-09-25T22:50:26Z",      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json"    }  ]}

List Active Triggers

  • GET /api/v2/triggers/active

Lists all active triggers.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For

  • Agents

Sideloads

The following sideloads are supported:

NameWill sideload
app_installationThe app installation that requires each trigger, if present
permissionsThe permissions for each trigger
usage_1hThe number of times each trigger has been used in the past hour
usage_24hThe number of times each trigger has been used in the past day
usage_7dThe number of times each trigger has been used in the past week
usage_30dThe number of times each trigger has been used in the past thirty days

Parameters

NameTypeInRequiredDescription
category_idstringQueryfalseFilter triggers by category ID
sortstringQueryfalseCursor-based pagination only. Possible values are "alphabetical", "created_at", "updated_at", or "position".
sort_bystringQueryfalseOffset pagination only. Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". 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/triggers/active.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/triggers/active?category_id=10026&sort=position&sort_by=position&sort_order=desc"	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/triggers/active")		.newBuilder()		.addQueryParameter("category_id", "10026")		.addQueryParameter("sort", "position")		.addQueryParameter("sort_by", "position")		.addQueryParameter("sort_order", "desc");
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/triggers/active',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'category_id': '10026',    'sort': 'position',    'sort_by': 'position',    'sort_order': 'desc',  },};
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/triggers/active?category_id=10026&sort=position&sort_by=position&sort_order=desc"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/triggers/active")uri.query = URI.encode_www_form("category_id": "10026", "sort": "position", "sort_by": "position", "sort_order": "desc")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,  "triggers": [    {      "actions": [],      "active": true,      "conditions": {},      "created_at": "2012-09-25T22:50:26Z",      "description": "Close and save a ticket",      "id": 25,      "position": 8,      "raw_title": "Close and Save",      "title": "Close and Save",      "updated_at": "2012-09-25T22:50:26Z",      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"    },    {      "actions": [],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          }        ]      },      "created_at": "2012-09-25T22:50:26Z",      "description": "Assign a ticket with a priority tag",      "id": 26,      "position": 9,      "raw_title": "{{dc.assign_priority_tag}}",      "title": "Assign priority tag",      "updated_at": "2012-09-25T22:50:26Z",      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json"    }  ]}

Search Triggers

  • GET /api/v2/triggers/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 trigger, if present
permissionsThe permissions for each trigger
usage_1hThe number of times each trigger has been used in the past hour
usage_24hThe number of times each trigger has been used in the past day
usage_7dThe number of times each trigger has been used in the past week
usage_30dThe number of times each trigger has been used in the past thirty days

Filter

Use the filter query parameter to filter a trigger search by one or more attributes. For example, the following filter argument filters triggers by the description attribute:

{  "json": {    "description": "Close a ticket"  }}

Parameters

NameTypeInRequiredDescription
activebooleanQueryfalseFilter by active triggers if true or inactive triggers if false
filterobjectQueryfalseTrigger attribute filters for the search. See Filter
includestringQueryfalseA sideload to include in the response. See Sideloads
querystringQuerytrueQuery string used to find all triggers with matching title
sortstringQueryfalseCursor-based pagination only. Possible values are "alphabetical", "created_at", "updated_at", or "position".
sort_bystringQueryfalseOffset pagination only. Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position"
sort_orderstringQueryfalseOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Code Samples

curl
# With `query`:curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json?query=close \  -v -u {email_address}/token:{api_token}
# With `filter`:curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json \  -G --data-urlencode 'filter={"json":{"description":"Close a ticket"}}' \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/triggers/search?active=true&filter=&include=usage_24h&query=important_trigger&sort=position&sort_by=position&sort_order=desc"	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/triggers/search")		.newBuilder()		.addQueryParameter("active", "true")		.addQueryParameter("filter", "")		.addQueryParameter("include", "usage_24h")		.addQueryParameter("query", "important_trigger")		.addQueryParameter("sort", "position")		.addQueryParameter("sort_by", "position")		.addQueryParameter("sort_order", "desc");
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/triggers/search',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'active': 'true',    'filter': '',    'include': 'usage_24h',    'query': 'important_trigger',    'sort': 'position',    'sort_by': 'position',    'sort_order': 'desc',  },};
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/triggers/search?active=true&filter=&include=usage_24h&query=important_trigger&sort=position&sort_by=position&sort_order=desc"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/triggers/search")uri.query = URI.encode_www_form("active": "true", "filter": "", "include": "usage_24h", "query": "important_trigger", "sort": "position", "sort_by": "position", "sort_order": "desc")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,  "triggers": [    {      "actions": [],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          }        ]      },      "created_at": "2012-09-25T22:50:26Z",      "description": "Close and save a ticket",      "id": 25,      "position": 9,      "raw_title": "Close and Save",      "title": "Close and Save",      "updated_at": "2012-09-25T22:50:26Z"    },    {      "actions": [],      "active": true,      "conditions": {},      "created_at": "2012-09-25T22:50:26Z",      "id": 28,      "position": 9,      "raw_title": "{{dc.close_and_redirect}}",      "title": "Close and redirect to topics",      "updated_at": "2012-09-25T22:50:26Z"    }  ]}

Show Trigger

  • GET /api/v2/triggers/{trigger_id}

Allowed For

  • Agents

The Via Type value is a number instead of a text string. See Via types reference for the keys.

Parameters

NameTypeInRequiredDescription
trigger_idintegerPathtrueThe ID of the trigger

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/triggers/198"	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/triggers/198")		.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/triggers/198',  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/triggers/198"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/triggers/198")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
{  "trigger": {    "actions": [],    "active": true,    "category_id": "10026",    "conditions": {},    "created_at": "2012-09-25T22:50:26Z",    "description": "Close and save a ticket",    "id": 25,    "position": 8,    "raw_title": "Close and Save",    "title": "Close and Save",    "updated_at": "2012-09-25T22:50:26Z",    "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"  }}

List Trigger Action and Condition Definitions

  • GET /api/v2/triggers/definitions

Returns the definitions of the actions a trigger can perform and the definitions of the conditions under which a trigger can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators.

For a list of supported actions, see the Actions reference For a list of supported conditions, see the Conditions reference

Allowed For

  • Agents

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/definitions.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/triggers/definitions"	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/triggers/definitions")		.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/triggers/definitions',  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/triggers/definitions"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/triggers/definitions")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
{  "definitions": {    "actions": [      {        "group": "ticket",        "nullable": false,        "repeatable": false,        "subject": "status",        "title": "Status",        "type": "list",        "values":