An automation consists of one or more actions that are performed if certain conditions are met after a period of time. The conditions are checked every hour. For example, an automation can notify an agent when a ticket remains unresolved after 24 hours.

Even if the actions are performed once, they'll be performed again later if the conditions still apply. To ensure the actions are performed only once, include an action in the automation that cancels one of the conditions.

For more information, see Creating and managing automations for time-based events.

JSON format

Automations are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
actionsarrayfalsefalseAn object describing what the automation will do. See Actions reference
activebooleanfalsefalseWhether the automation is active
conditionsobjectfalsefalseAn object that describes the conditions under which the automation will execute. See Conditions reference
created_atstringtruefalseThe time the automation was created
defaultbooleantruefalseIf true, the automation is a default automation
idintegertruefalseAutomatically assigned when created
positionintegerfalsefalseThe position of the automation which specifies the order it will be executed
raw_titlestringtruefalseThe raw title of the automation
titlestringfalsefalseThe title of the automation
updated_atstringtruefalseThe time of the last update of the automation

Example

{  "actions": [    {      "field": "priority",      "value": "high"    }  ],  "active": true,  "conditions": {    "all": [      {        "field": "status",        "operator": "is",        "value": "open"      },      {        "field": "priority",        "operator": "less_than",        "value": "high"      }    ],    "any": []  },  "default": false,  "id": 9873843,  "position": 8,  "raw_title": "Roger Wilco",  "title": "Roger Wilco"}

List Automations

  • GET /api/v2/automations

Lists all automations for the current account.

Allowed For

  • Agents

Available Parameters

You can pass in any combination of the following optional filters:

NameTypeComment
activebooleanOnly active automations if true, inactive automations if false
sort_bystringPossible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position"
sort_orderstringOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

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

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/automations.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/automations"	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/automations")		.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/automations',  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 requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/automations"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = 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/automations")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
{  "automations": [    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 25,      "position": 8,      "raw_title": "Close and Save",      "title": "Close and Save"    },    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": false,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 26,      "position": 9,      "raw_title": "{{dc.assign_priority_tag}}",      "title": "Assign priority tag"    }  ],  "count": 2,  "next_page": null,  "previous_page": null}

List Active Automations

  • GET /api/v2/automations/active

Lists all active automations.

Allowed For

  • Agents

Available Parameters

You can pass in any combination of the following optional filters:

NameTypeComment
sort_bystringPossible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position"
sort_orderstringOne of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others

Sideloads

The following sideloads are supported:

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

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/automations/active.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/automations/active"	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/automations/active")		.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/automations/active',  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 requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/automations/active"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = 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/automations/active")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
{  "automations": [    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 25,      "position": 8,      "raw_title": "Close and Save",      "title": "Close and Save"    },    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": false,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 26,      "position": 9,      "raw_title": "{{dc.assign_priority_tag}}",      "title": "Assign priority tag"    }  ],  "count": 2,  "next_page": null,  "previous_page": null}

Search Automations

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

Parameters

NameTypeInRequiredDescription
activebooleanQueryfalseFilter by active automations if true or inactive automations if false
includestringQueryfalseA sideload to include in the response. See Sideloads
querystringQuerytrueQuery string used to find all automations with matching title
sort_bystringQueryfalsePossible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the automations 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/automations/search.json?query=close \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/automations/search?active=true&include=usage_24h&query=close&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 "{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/automations/search")		.newBuilder()		.addQueryParameter("active", "true")		.addQueryParameter("include", "usage_24h")		.addQueryParameter("query", "close")		.addQueryParameter("sort_by", "position")		.addQueryParameter("sort_order", "desc");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/automations/search',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'active': 'true',    'include': 'usage_24h',    'query': 'close',    '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 requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/automations/search?active=true&include=usage_24h&query=close&sort_by=position&sort_order=desc"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = 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/automations/search")uri.query = URI.encode_www_form("active": "true", "include": "usage_24h", "query": "close", "sort_by": "position", "sort_order": "desc")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
{  "automations": [    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 25,      "position": 9,      "raw_title": "Close and Save",      "title": "Close and Save"    },    {      "actions": [        {          "field": "status",          "value": "open"        },        {          "field": "assignee_id",          "value": "296220096"        }      ],      "active": true,      "conditions": {        "all": [          {            "field": "status",            "operator": "less_than",            "value": "solved"          },          {            "field": "assignee_id",            "operator": "is",            "value": "296220096"          }        ],        "any": [          {            "field": "current_tags",            "operator": "includes",            "value": "hello"          }        ]      },      "id": 28,      "position": 9,      "raw_title": "{{dc.close_and_redirect}}",      "title": "Close and redirect to topics"    }  ],  "count": 2,  "next_page": null,  "previous_page": null}

Show Automation

  • GET /api/v2/automations/{automation_id}

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
automation_idintegerPathtrueThe ID of the automation

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/automations/{automation_id}.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/automations/25"	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/automations/25")		.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/automations/25',  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 requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/automations/25"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = 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/automations/25")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
{  "automation": {    "actions": [      {        "field": "status",        "value": "open"      },      {        "field": "assignee_id",        "value": "296220096"      }    ],    "active": true,    "conditions": {      "all": [        {          "field": "status",          "operator": "less_than",          "value": "solved"        },        {          "field": "assignee_id",          "operator": "is",          "value": "296220096"        }      ],      "any": [        {          "field": "current_tags",          "operator": "includes",          "value": "hello"        }      ]    },    "id": 25,    "position": 8,    "raw_title": "Close and Save",    "title": "Close and Save"  }}

Create Automation

  • POST /api/v2/automations

Creates an automation.

New automations must be unique and have at least one condition that is true only once or an action that nullifies at least one of the conditions. Active automations can have overlapping conditions but can't be identical.

The request must include the following conditions in the all array:

  • At least one time-based condition
  • At least one condition that checks one of the following fields: status, type, group_id, assignee_id, or requester_id.

Allowed For

  • Agents

Code Samples

curl
curl -u {email_address}/token:{api_token} https://{subdomain}.zendesk.com/api/v2/automations.json \  -H "Content-Type: application/json" -X POST -d \ '{"automation": {"title": "Roger Wilco", "all": [{ "field": "status", "operator": "is", "value": "open" }, { "field": "priority", "operator": "less_than", "value": "high" }], "actions": [{ "field": "priority", "value": "high" }]}}'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/automations"	method := "POST"	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.