Automations
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:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
actions | array | false | false | An object describing what the automation will do. See Actions reference |
active | boolean | false | false | Whether the automation is active |
conditions | object | false | false | An object that describes the conditions under which the automation will execute. See Conditions reference |
created_at | string | true | false | The time the automation was created |
default | boolean | true | false | If true, the automation is a default automation |
id | integer | true | false | Automatically assigned when created |
position | integer | false | false | The position of the automation which specifies the order it will be executed |
raw_title | string | true | false | The raw title of the automation |
title | string | false | false | The title of the automation |
updated_at | string | true | false | The 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:
Name | Type | Comment |
---|---|---|
active | boolean | Only active automations if true, inactive automations if false |
sort_by | string | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" |
sort_order | string | One 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.
Name | Will sideload |
---|---|
app_installation | The app installation that requires each automation, if present |
permissions | The permissions for each automation |
usage_1h | The number of times each automation has been used in the past hour |
usage_24h | The number of times each automation has been used in the past day |
usage_7d | The number of times each automation has been used in the past week |
usage_30d | The 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 requests
from 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 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/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:
Name | Type | Comment |
---|---|---|
sort_by | string | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" |
sort_order | string | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
app_installation | The app installation that requires each automation, if present |
permissions | The permissions for each automation |
usage_1h | The number of times each automation has been used in the past hour |
usage_24h | The number of times each automation has been used in the past day |
usage_7d | The number of times each automation has been used in the past week |
usage_30d | The 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 requests
from 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 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/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
Allowed For
- Agents
Sideloads
The following sideloads are supported. For more information, see Side-loading.
Name | Will sideload |
---|---|
app_installation | The app installation that requires each automation, if present |
permissions | The permissions for each automation |
usage_1h | The number of times each automation has been used in the past hour |
usage_24h | The number of times each automation has been used in the past day |
usage_7d | The number of times each automation has been used in the past week |
usage_30d | The number of times each automation has been used in the past thirty days |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
active | boolean | Query | false | Filter by active automations if true or inactive automations if false |
include | string | Query | false | A sideload to include in the response. See Sideloads |
query | string | Query | true | Query string used to find all automations with matching title |
sort_by | string | Query | false | Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the automations are sorted by relevance |
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/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 requests
from 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 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/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
Name | Type | In | Required | Description |
---|---|---|---|---|
automation_id | integer | Path | true | The 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 requests
from 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 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/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
, orrequester_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.