Triggers

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 Streamlining workflow with ticket updates and triggers.

JSON Format

Triggers are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
actions	array	false	true	An array of actions describing what the trigger will do. See Actions reference
active	boolean	false	false	Whether the trigger is active
conditions	object	false	true	An object that describes the conditions under which the trigger will execute. See Conditions reference
created_at	string	true	false	The time the trigger was created
description	string	false	false	The description of the trigger
id	integer	true	false	Automatically assigned when created
position	integer	false	false	Position of the trigger, determines the order they will execute in
raw_title	string	false	false	The raw format of the title of the trigger
title	string	false	true	The title of the trigger
updated_at	string	true	false	The time of the last update of the trigger
url	string	true	false	The url of the trigger

Example

{
  "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"
}

List Triggers

GET /api/v2/triggers

Lists all triggers for the current account

Allowed For

Agents

Sideloads

The following sideloads are supported. The usage sideloads are only supported on the Professional and Enterprise plans.

Name	Will sideload
app_installation	The app installation that requires each trigger, if present
permissions	The permissions for each trigger
usage_1h	The number of times each trigger has been used in the past hour
usage_24h	The number of times each trigger has been used in the past day
usage_7d	The number of times each trigger has been used in the past week
usage_30d	The number of times each trigger has been used in the past thirty days

Parameters

Name	Type	In	Required	Description
active	boolean	Query	false	Only active triggers if `true`, inactive triggers if `false`
sort_by	string	Query	false	Possible values are `alphabetical`, `created_at`, `updated_at`, `usage_1h`, `usage_24h`, or `usage_7d`. 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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers.json \
  -v -u {email}:{password}

Example Response

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"
          }
        ]
      },
      "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"
    }
  ]
}

Create Trigger

POST /api/v2/triggers

Allowed For

Agents

Using curl

curl -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers.json \
  -H "Content-Type: application/json" -X POST -d \
  '{"trigger": {"title": "Roger Wilco", "all": [{ "field": "status", \
  "operator": "is", "value": "open" }, { "field": "priority", \
  "operator": "less_than", "value": "high" }], \
  "actions": [{ "field": "group_id", "value": "20455932" }]}}'

Example Response

Status 201 Created

{
  "trigger": {
    "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"
  }
}

List Active Triggers

GET /api/v2/triggers/active

Lists all active triggers

Allowed For

Agents

Sideloads

The following sideloads are supported:

Name	Will sideload
app_installation	The app installation that requires each trigger, if present
permissions	The permissions for each trigger
usage_1h	The number of times each trigger has been used in the past hour
usage_24h	The number of times each trigger has been used in the past day
usage_7d	The number of times each trigger has been used in the past week
usage_30d	The number of times each trigger has been used in the past thirty days

Parameters

Name	Type	In	Required	Description
sort_by	string	Query	false	Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". 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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/active.json \
  -v -u {email}:{password}

Example Response

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"
    }
  ]
}

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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/definitions.json \
  -v -u {email}:{password}

Example Response

Status 200 OK

{
  "definitions": {
    "actions": [
      {
        "group": "ticket",
        "nullable": false,
        "repeatable": false,
        "subject": "status",
        "title": "Status",
        "type": "list",
        "values": [
          {
            "enabled": true,
            "title": "Open",
            "value": "open"
          },
          {
            "enabled": true,
            "title": "Pending",
            "value": "pending"
          },
          {
            "enabled": true,
            "title": "Solved",
            "value": "solved"
          },
          {
            "enabled": true,
            "title": "Closed",
            "value": "closed"
          }
        ]
      }
    ],
    "conditions_all": [
      {
        "group": "ticket",
        "nullable": false,
        "operators": [
          {
            "terminal": false,
            "title": "Is",
            "value": "is"
          },
          {
            "terminal": false,
            "title": "Is not",
            "value": "is_not"
          },
          {
            "terminal": false,
            "title": "Less than",
            "value": "less_than"
          },
          {
            "terminal": false,
            "title": "Greater than",
            "value": "greater_than"
          },
          {
            "terminal": true,
            "title": "Changed",
            "value": "changed"
          },
          {
            "terminal": false,
            "title": "Changed to",
            "value": "value"
          },
          {
            "terminal": false,
            "title": "Changed from",
            "value": "value_previous"
          },
          {
            "terminal": true,
            "title": "Not changed",
            "value": "not_changed"
          },
          {
            "terminal": false,
            "title": "Not changed to",
            "value": "not_value"
          },
          {
            "terminal": false,
            "title": "Not changed from",
            "value": "not_value_previous"
          }
        ],
        "repeatable": false,
        "subject": "status",
        "title": "Status",
        "type": "list",
        "values": [
          {
            "enabled": true,
            "title": "New",
            "value": "new"
          },
          {
            "enabled": true,
            "title": "Open",
            "value": "open"
          },
          {
            "enabled": true,
            "title": "Pending",
            "value": "pending"
          },
          {
            "enabled": true,
            "title": "Solved",
            "value": "solved"
          },
          {
            "enabled": true,
            "title": "Closed",
            "value": "closed"
          }
        ]
      }
    ],
    "conditions_any": [
      {
        "group": "ticket",
        "nullable": true,
        "operators": [
          {
            "terminal": true,
            "title": "Present",
            "value": "present"
          },
          {
            "terminal": true,
            "title": "Not present",
            "value": "not_present"
          }
        ],
        "repeatable": false,
        "subject": "custom_fields_20513432",
        "title": "Happy Gilmore",
        "type": "list"
      },
      {
        "group": "ticket",
        "nullable": true,
        "operators": [
          {
            "terminal": true,
            "title": "Present",
            "value": "present"
          },
          {
            "terminal": true,
            "title": "Not present",
            "value": "not_present"
          }
        ],
        "repeatable": false,
        "subject": "custom_fields_86492341",
        "title": "total_time_field",
        "type": "list"
      }
    ]
  }
}

Bulk Delete Triggers

DELETE /api/v2/triggers/destroy_many?ids={ids}

Deletes the triggers 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 triggers to delete.

Name	Description
ids	The IDs of the triggers to delete

Example request

{
  "ids": "25,23,27,22"
}

Parameters

Name	Type	In	Required	Description
ids	string	Query	true	A comma separated list of trigger IDs

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/destroy_many.json?ids=1,2,3 \
  -v -u {email}:{password} -X DELETE

Example Response

Status 204 No Content

Reorder Triggers

PUT /api/v2/triggers/reorder

Alters the firing order of triggers in the account. See Reordering and sorting triggers in the Zendesk Help Center. The firing order is set in a trigger_ids array in the request body.

You must include every trigger id in your account to reorder the triggers. If not, the endpoint will return 404 Forbidden.

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/reorder.json \
  -d '{"trigger_ids": [324376, 564937, 164318]}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email}:{password}

Example Response

Status 200 OK

{
  "trigger": {
    "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"
  }
}

Search Triggers

GET /api/v2/triggers/search?query={query}

Allowed For

Agents

Sideloads

The following sideloads are supported:

Name	Will sideload
app_installation	The app installation that requires each trigger, if present
permissions	The permissions for each trigger
usage_1h	The number of times each trigger has been used in the past hour
usage_24h	The number of times each trigger has been used in the past day
usage_7d	The number of times each trigger has been used in the past week
usage_30d	The number of times each trigger has been used in the past thirty days

Parameters

Name	Type	In	Required	Description
active	boolean	Query	false	Filter by only active triggers if true, inactive triggers if false
query	string	Query	true	Query string used to find all triggers with matching title
sort_by	string	Query	false	Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". 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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json?query=close \
  -v -u {email}:{password}

Example Response

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"
    }
  ]
}

Update Many Triggers

GET /api/v2/triggers/update_many

Updates the position or the active status of multiple triggers. Any additional properties are ignored.

Allowed For

Agents

Request Parameters

The PUT request expects a triggers object that lists the triggers to update.

Each trigger may have the following properties:

Name	Mandatory	Description
id	yes	The ID of the trigger to update
position	no	The new position of the trigger
active	no	The active status of the trigger (true or false)

Example Request

{
  "triggers": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/update_many.json \
  -v -u {email}:{password} -H "Content-Type: application/json" \
  -X PUT -d '{"triggers": [{"id": 26, "position": 8}, {"id": 25, "position": 15}]}'

Example Response

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"
          }
        ]
      },
      "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"
    }
  ]
}

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 for the keys.

Parameters

Name	Type	In	Required	Description
trigger_id	integer	Path	true	The ID of the trigger

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
  -v -u {email}:{password}

Example Response

Status 200 OK

{
  "trigger": {
    "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"
  }
}

Update Trigger

PUT /api/v2/triggers/{trigger_id}

Allowed For

Agents

Note

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.

Parameters

Name	Type	In	Required	Description
trigger_id	integer	Path	true	The ID of the trigger

Using curl

curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"trigger": {"title": "Roger Wilco II"}}'

Example Response

Status 200 OK

{
  "trigger": {
    "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"
  }
}

Delete Trigger

DELETE /api/v2/triggers/{trigger_id}

Allowed For

Agents

Parameters

Name	Type	In	Required	Description
trigger_id	integer	Path	true	The ID of the trigger

Using curl

curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
  -H "Content-Type: application/json" -X DELETE

Example Response

Status 204 No Content

List Trigger Revisions

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

List the revisions associated with a trigger.

Allowed For

Agents

Sideloads

The following sideloads are supported:

Name	Will sideload
users	The user that authored each revision

Pagination

This endpoint uses cursor-based pagination. The records are ordered in descending order by the created_at timestamp, then by id on duplicate created_at values.

The cursor parameter is a non-human-readable argument you can use to move forward or backward in time.

Each JSON response will contain the following attributes to help you get more results:

after_url requests more recent results
before_url requests older results
after_cursor is the cursor to build the request yourself
before_cursor is the cursor to build the request yourself

The properties are null if no more records are available.

You can request a maximum of 1000 records using the limit parameter. If no limit parameter is supplied, it will default to 1,000.

Parameters

Name	Type	In	Required	Description
trigger_id	integer	Path	true	The ID of the trigger

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?limit=20 \
  -v -u {email}:{password}

Example Response

Status 200 OK

{
  "after_cursor": "MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA==",
  "after_url": "https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?cursor=MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA%3D%3D\u0026limit=20",
  "before_cursor": "fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ==",
  "before_url": "https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?cursor=fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ%3D%3D\u0026limit=20",
  "count": 1,
  "trigger_revisions": [
    {
      "author_id": 2,
      "created_at": "2016-08-15T16:04:06Z",
      "diff": {
        "actions": [],
        "active": [],
        "conditions": {},
        "description": [],
        "source_id": 1,
        "target_id": 2,
        "title": []
      },
      "id": 100,
      "snapshot": {
        "actions": [
          {
            "field": "notification_target",
            "value": [
              "510312",
              "{}"
            ]
          }
        ],
        "active": true,
        "conditions": {
          "all": [],
          "any": [
            {
              "field": "current_tags",
              "operator": "includes",
              "value": "fire_bulk_1"
            }
          ]
        },
        "description": "Notifies requester that a comment was updated",
        "title": "Notify requester of comment update"
      },
      "url": "https://{subdomain}.zendesk.com/api/v2/trigger/123/revisions/100.json"
    }
  ]
}

Show Trigger Revision

GET /api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}

Fetches a revision associated with a trigger.

Allowed For

Agents

Sideloads

The following sideloads are supported:

Name	Will sideload
users	The user that authored each revision

Parameters

Name	Type	In	Required	Description
trigger_id	integer	Path	true	The ID of the trigger
trigger_revision_id	integer	Path	false	The ID of the revision for a particular trigger

Using curl

curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}.json \
  -v -u {email}:{password}

Example Response

Status 200 OK

{
  "trigger_revision": {
    "author_id": 3343,
    "created_at": "2020-05-28T06:41:43Z",
    "id": 1,
    "snapshot": {
      "actions": [
        {
          "field": "notification_target",
          "value": [
            "510312",
            "{}"
          ]
        }
      ],
      "active": true,
      "conditions": {
        "all": [],
        "any": [
          {
            "field": "current_tags",
            "operator": "includes",
            "value": "fire_bulk_1"
          }
        ]
      },
      "description": null,
      "title": "bulk_test_trigger_1"
    },
    "url": "https://example.zendesk.com/api/v2/triggers/261303831/revisions/1.json"
  }
}