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
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": []
  },
  "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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations.json \
  -v -u {email}:{password}
Example Response
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
}

Create Automation

  • POST /api/v2/automations

Creates an automation.

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
Using curl
curl -u {email}:{password} 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" }]}}'
Example Response
Status 201 Created

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

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations/active.json \
  -v -u {email}:{password}
Example Response
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
}

Bulk Delete Automations

  • DELETE /api/v2/automations/destroy_many

Deletes the automations corresponding to the provided comma-separated list of IDs.

Allowed For
  • Agents
Request Parameters

The DELETE request takes one parameter, an ids object that lists the automations to delete.

Name Description
ids The IDs of the automations to delete
Example request
{
  "ids": "25,23,27,22"
}
Parameters
Name Type In Required Description
ids array Query false The IDs of the automations to delete
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations/destroy_many.json?ids=1,2,3 \
  -v -u {email}:{password} -X DELETE
Example Response
Status 204 No Content

Search Automations

  • GET /api/v2/automations/search
Allowed For
  • Agents
Available Parameters
Name Type Mandatory Comment
query string true Query string used to find all automations with matching title
active boolean false Only active automations if true, inactive automations if false
sort_by string false Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, the automations are sorted by relevance
sort_order string false 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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations/search.json?query=close \
  -v -u {email}:{password}
Example Response
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
}

Update Many Automations

  • PUT /api/v2/automations/update_many
Allowed For
  • Agents
Request Parameters

The PUT request expects an automations object that lists the automations to update.

Each automation may have the following properties:

Name Mandatory Description
id yes The ID of the automation to update
position no The new position of the automation
active no The active status of the automation (true or false)
Example Request
{
  "automations": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/automations/update_many.json \
  -H "Content-Type: application/json" -X PUT -d '{"automations": [{"id": 26, "position": 8}, {"id": 25, "position": 15}]}'
Example Response
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": 15,
      "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": 8,
      "raw_title": "{{dc.assign_priority_tag}}",
      "title": "Assign priority tag"
    }
  ],
  "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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations/{automation_id}.json \
  -v -u {email}:{password}
Example Response
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"
  }
}

Update Automation

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

Updates an automation.

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

Updating a condition or action updates both the conditions and actions arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action.

Allowed For
  • Agents
Parameters
Name Type In Required Description
automation_id integer Path true The ID of the automation
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/automations/{automation_id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"automation": {"title": "Roger Wilco II"}}'
Example Response
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"
  }
}

Delete Automation

  • DELETE /api/v2/automations/{automation_id}
Allowed For
  • Agents
Parameters
Name Type In Required Description
automation_id integer Path true The ID of the automation
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/automations/{automation_id}.json \
  -H "Content-Type: application/json" -X DELETE
Example Response
Status 204 No Content