Support API

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.

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 simple flat JSON objects which have the following keys.

Name Type Comment
id integer Automatically assigned when created
title string The title of the trigger
active boolean Whether the trigger is active
position integer Position of the trigger, determines the order they will execute in
conditions Conditions An object that describes the conditions under which the trigger will execute
actions array An array of Actions describing what the trigger will do
description string The description of the trigger
created_at date The time the trigger was created
updated_at date The time of the last update of the trigger
Example
 
{
  "trigger": {
    "id": 25,
    "title": "Notify requester of comment update",
    "active": true,
    "actions": [ ... ],
    "conditions": { ... },
    "description": "Notifies requester that a comment was updated",
    "updated_at": "2012-09-25T22:50:26Z",
    "created_at": "2012-09-25T22:50:26Z"
  }
}

Conditions

Conditions check the value of ticket fields and select the ticket if the conditions are met. Conditions are represented as a JSON object with two arrays of one or more conditions.

Example

{
   "conditions": {
     "all": [
       { "field": "status", "operator": "less_than", "value": "solved" },
       { "field": "assignee_id", "operator": "is", "value": "296220096" }
     ],
     "any": [
     ]
   }
}

The first array lists all the conditions that must be met. The second array lists any condition that must be met.

Name Type Description
all array Logical AND. Tickets must fulfill all of the conditions to be considered matching
any array Logical OR. Tickets may satisfy any of the conditions to be considered matching

Each condition in an array has the following properties:

Name Type Description
field string The name of a ticket field
operator string A comparison operator
value string The value of a ticket field

Example

{ "field": "status", "operator": "less_than", "value": "solved" }

When specifying conditions in a PUT or POST request, use the "all" and "any" arrays without the "conditions" key. Example:

{
  "all": [
    { "field": "status", "operator": "less_than", "value": "solved" },
    { "field": "assignee_id", "operator": "is", "value": "296220096" }
  ],
  "any": [
    { "field": "current_tags", "operator": "includes", "value": "hello" }
  ],
  ...
}
Conditions reference

The following tables list the fields, allowed operators, and values of the conditions used in triggers, automations, views and SLA policies.

Common conditions

The following conditions are shared by triggers, automations, views and SLA policies.

field operator value
group_id is, is_not "" (no group assigned to the ticket) or the numeric ID of the group assigned to the ticket.
assignee_id is, is_not "" (nobody assigned to the ticket), current_user, all_agents, or the numeric ID of the agent assigned to the ticket.
requester_id is, is_not "" (no requester specified), current_user or the numeric ID of the requester or assignee.
organization_id is, is_not "" (no organization added to the ticket) or the numeric ID of the organization added to the ticket.
current_tags includes, not_includes A space-delimited list of tags to compare against the ticket's tags.
via_id is, is_not The numeric ID of the channel used to create the ticket. See the Via Types table.
recipient Omit the operator property For views and automations, the account name in the email address from which the ticket was received. For triggers and SLA policies, the full email address, which can include external addresses.

The following conditions are shared by triggers, automations, and views.

field operator value
type is, is_not question, incident, problem, or task
status is,
is_not,
less_than,
greater_than		 new, open, pending, hold, solved, or closed
priority is,
is_not,
less_than,
greater_than		 "" (no priority assigned to the ticket), low, normal, high, or urgent
description_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in the ticket subject. Not available in triggers.
locale_id is, is_not The numeric ID of the locale of the person who submitted the ticket. See List locales to list the available locale IDs for the account.
satisfaction_score is,
is_not,
less_than,
greater_than		 good_with_comment, good, bad_with_comment, bad, false (offered), or true (unoffered)

Triggers have the following additional operators for some shared fields.

Fields Additional trigger operators
status,
type,
priority,
group_id,
assignee_id,
requester_id,
organization_id,
satisfaction_ score		 changed (omit value property),
value (changed to),
value_previous (changed from),
not_changed,
not_value (not changed to),
not_value_previous (not changed from)
Additional trigger conditions

Triggers have the following additional conditions.

field operator value
subject_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in the subject.
comment_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)		 Single words or strings in either the subject or body of the comment.
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
update_type Omit the operator property. Create or Change
comment_is_public Omit the operator property. true, false, not_relevant (present), or requester_can_see_comment (present and requester can see comment)
ticket_is_public Omit the operator property. public, private
reopens less_than, greater_than, or is The number of times a ticket has moved from Solved to Open or Pending.
replies less_than, greater_than, or is The number of public agent comments.
agent_stations less_than, greater_than, or is The number of different agents to which a ticket has been assigned.
group_stations less_than, greater_than, or is The number of different groups to which a ticket has been assigned.
in_business_hours Omit the operator property. true or false. Available only if an administrator enabled business hours.
requester_twitter_followers_count less_than, greater_than, or is The number of the requester's Twitter followers.
requester_twitter_statuses_count less_than, greater_than, or is The total number of the requester's tweets.
requester_twitter_verified Omit the operator property Omit the value property. The condition is true if the requester has a verified Twitter account.
Additional SLA Policies conditions

SLA Policies have the following additional conditions.

field operator value
ticket_type_id is, is_not The numeric ID of the ticket type: 1 (question), 2 (incident), 3 (problem), or 4 (task)
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
exact_created_at less_than, less_than_equal, greater_than or greater_than_equal The time the ticket was created.
Additional time-based conditions for automations and views

Automations and views have the following time-based conditions. Time-based conditions can only be used in all arrays, not in any arrays.

field value
NEW Hours since the ticket was created.
OPEN Hours since the ticket was opened.
PENDING Hours since the ticket was changed to pending.
SOLVED Hours since the ticket was changed to solved.
CLOSED Hours since the ticket was closed.
assigned_at Hours since assigned.
updated_at Hours since update.
requester_updated_at Hours since requester update.
assignee_updated_at Hours since assignee update.
due_date Hours since the due date. For tickets with the type set to Task.
until_due_date Hours until the due date. For tickets with the type set to Task.

The time-based conditions all share the same operator values:

operator
is
is_business_hours
less_than
less_than_business_hours
greater_than
greater_than_business_hours
Via Types
Description via type via id
Web form web_form 0
Email mail 4
Chat chat 29
Twitter twitter 30
Twitter DM twitter_dm 26
Twitter like twitter_favorite 23
Voicemail voicemail 33
Phone call (incoming) phone_call_inbound 34
Phone call (outbound) phone_call_outbound 35
CTI* voicemail api_voicemail 44
CTI phone call (inbound) api_phone_call_inbound 45
CTI phone call (outbound) api_phone_call_outbound 46
SMS sms 57
Get Satisfaction get_satisfaction 16
Web Widget web_widget 48
Mobile SDK mobile_sdk 49
Mobile mobile 56
Help Center post helpcenter 50
Web service (API) web_service 5
Trigger, automation rule 8
Closed ticket closed_ticket 27
Ticket sharing ticket_sharing 31
Facebook post facebook_post 38
Facebook private message facebook_message 41
Satisfaction prediction satisfaction_prediction 54
Channel framework any_channel 55

*CTI - Computer Telephony Integration

Actions

Actions consist of an array of one or more actions.

Example

{
  "actions": [
    {"field": "status", "value": "open"},
    {"field": "assignee_id", "value": "296220096"}
  ]
}

Each action in the array has the following properties:

Name Type Description
field string The name of a ticket field to modify
value string The new value of the field

Example action

{ "field": "status", "value": "solved" }
Actions reference

Triggers, automations, and macros share the following actions.

field value
status Sets the ticket status. Takes new, open, pending, hold, solved, or closed, except for macros, which don't take new or closed.
type Sets the ticket type. Takes question, incident, problem, or task.
priority Sets the ticket priority. Takes low, normal, high, or urgent.
group_id Assigns the ticket to a group. Takes a string with a group id, or an empty string ("") to unassign the group assigned to the ticket.
assignee_id Assigns the ticket to a person. Takes a string with the user id of an assignee or requester, or "current_user", or an empty string ("") to unassign the person assigned to the ticket.
set_tags A space-delimited list of tags to insert in the ticket. The action replaces the current tags.
current_tags A space-delimited list of tags to add to existing tags.
remove_tags A space-delimited list of tags to remove from existing tags.
custom_fields_<id> Sets the value of a custom ticket field.
Additional actions for triggers and automations

In addition to the shared actions, triggers and automations share the following actions.

field value
satisfaction_score Sends a survey request to the ticket requester. Takes offered as a value.
notification_user Sends an email to a user. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: current_user, all_agent (all non-restricted agents), requester_id (the current requester), assignee_id (the current assignee), or the numeric ID of an agent.
notification_group Sends an email to a group. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: group_id (the currently assigned group), or the numeric ID of a group.
notification_target Sends a message to an external target. Takes an array of two strings specifying the numeric ID of the target and the message body.
tweet_requester Responds to the twitter requester with a tweet. Takes the text of the tweet.
cc CC's somebody on the ticket. Takes current_user or the numeric ID of an agent.
locale_id Sets the requester's language to one of your supported languages. Takes the numeric ID of a supported locale. See List locales to list the available locale IDs for the account.
requester.custom_fields.<field_key> Sets the value of a custom user field. The corresponding "value" property can be any string for a text field, or the id of an option for a dropdown field. An option id must be specified as a string. For a field's key or option id values, see Show User Field in User Fields
Additional actions for macros

In addition to the shared actions, macros have the following actions.

field value
subject Replaces the subject of a ticket. Takes the subject text.
comment_value Adds a comment to a ticket. Takes the comment text or an array of two strings specifying the comment channel and comment text. Possible comment channels : 'channel:all', 'channel:web' and 'channel:chat'
comment_value_html Adds a rich-text comment to a ticket.
comment_mode_is_public Makes a ticket comment public or private. Takes true (public) or false (private).
Notification emails

Notification emails are represented by an array of three strings specifying the email recipient, subject, and body.

Example

["293741756", "Leaking radiator", "Open the steam valve."]

The array is used for the value property of email notification actions. See "Additional actions for triggers and automations" above.

Example action

{
  "actions": [
    {"field": "notification_user", "value": ["293741756", "Leaking radiator", "Open the steam valve."]}
  ]
}

You can use dynamic content placeholders in the email subject and body. See Zendesk Support data object (placeholders) reference.

You can also use return (\r) and newline (\n) characters in the message body.

Example

["current_user","{{ticket.id}}: Leaking radiator","Open the steam valve.\r \nHope this helps."]

List Triggers

GET /api/v2/triggers.json

Lists all triggers 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 triggers if true, inactive triggers 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:

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

{
  "triggers": [
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json",
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 8,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json",
      "id": 26,
      "title": "Assign priority tag",
      "raw_title": "{{dc.assign_priority_tag}}",
      "position": 9,
      "active": false,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Assign a ticket with a priority tag",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}

Getting Triggers

GET /api/v2/triggers/{id}.json

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "trigger": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "raw_title": "{{dc.tickets_updated_last_12_hours}}"
    "position": 8,
    "active": true,
    "conditions": [ ... ],
    "actions": [ ... ],
    "description": "12 hours since the last ticket update",
    "updated_at": "2012-09-25T22:50:26Z",
    "created_at": "2012-09-25T22:50:26Z"
  }
}

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

List Active Triggers

GET /api/v2/triggers/active.json

Lists all active triggers

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

{
  "triggers": [
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 8,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and redirect a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}

Create Trigger

POST /api/v2/triggers.json

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
Location: /api/v2/trigger/{new-trigger-id}.json

{
  "trigger": {
    "id":   9873843,
    "title": "Roger Wilco",
    ...
  }
}

Update Trigger

PUT /api/v2/triggers/{id}.json

Allowed For
  • Agents
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"trigger": {"title": "Roger Wilco II"}}'
Example Response
 
Status: 200 OK

{
  "trigger": {
    "id":   9873843,
    "title": "Roger Wilco II",
    ...
  }
}
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.

Update Many Triggers

PUT /api/v2/triggers/update_many.json

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

Allowed For
  • Agents
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

{
  "triggers": [
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json",
      "id": 26,
      "title": "Assign priority tag",
      "raw_title": "{{dc.assign_priority_tag}}",
      "position": 8,
      "active": false,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Assign a ticket with a priority tag",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json",
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 15,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    ...
  ]
}
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}
  ]
}

Delete Trigger

DELETE /api/v2/triggers/{id}.json

Allowed For
  • Agents
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -H "Content-Type: application/json" -X DELETE
Example Response
 
Status: 200 OK

Bulk Delete Triggers

DELETE /api/v2/triggers/destroy_many.json

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

Allowed For
  • Agents
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
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"
}

Reorder Triggers

PUT /api/v2/triggers/reorder.json

Allowed For
  • Agents
Using curl
 
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/reorder.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"trigger_ids": [6, 7, 18]}'
Example Response
 
Status: 200 OK

Search Triggers

GET /api/v2/triggers/search.json

Allowed For
  • Agents
Search Parameters

Required

Name Type Comment
query string Query string used to find all triggers with matching title

Optional

You can use any combination of the following optional parameters:

Name Type Comment
active boolean Only active triggers if true, inactive triggers if false
sort_by string Possible values are alphabetical, created_at, updated_at, and position. If unspecified, the triggers are sorted by relevance
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 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
Using curl:
 
curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json?query=close \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "triggers": [
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}

List Trigger Action and Condition Definitions

GET /api/v2/triggers/definitions.json

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 Action reference. For a list of supported conditions, see Condition 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": [
      {
        "title": "Status",
        "type": "list",
        "value": "status",
        "group": "ticket",
        "repeatable": false,
        "values": [
          { "value": "1", "title": "Open", "enabled": true },
          { "value": "2", "title": "Pending", "enabled": true },
          { "value": "3", "title": "Solved", "enabled": true },
          { "value": "4", "title": "Closed", "enabled": true }
        ]
      },
      ...
    ],
    "conditions_all": [
      {
        "title": "Type",
        "subject": "type",
        "type": "list",
        "group": "ticket",
        "nullable": true,
        "repeatable": false,
        "operators": [
          { "value": "is", "title": "Is", "terminal": false },
          { "value": "is_not", "title": "Is not", "terminal": false },
          { "value": "changed", "title": "Changed", "terminal": true },
          ...
        ],
        "values": [
          { "value": "__NULL__", "title": "-", "enabled": true },
          { "value": "question", "title": "Question", "enabled": true },
          { "value": "incident", "title": "Incident", "enabled": true }
          ...
        ],
      },
      ...
    ],
    "conditions_any": [...]
  }
}

Trigger revision
Name Type Description
url string The API url of this revision
id integer ID of the revision
author_id integer ID of the user who made the revision
created_at date Time the revision was created
snapshot object State of the trigger at time of revision. See Snapshot
diff object Changes introduced in this revision. See Rule Diff
Example
 
{
  "trigger_revision": {
    "url": "https://{subdomain}.zendesk.com/api/v2/trigger/123/revisions/1.json"
    "id": "1",
    "author_id": "4",
    "created_at": 2017-08-10T21:10:05Z,
    "snapshot": { ... },
    "diff": { ... }
  }
}

Snapshot
Name Type Description
title string The title of the trigger
active boolean Whether the trigger is active
conditions Conditions An object that describes the conditions under which the trigger will execute
actions array An array of Actions describing what the trigger will do
description string The description of the trigger
Example
 
{
  "title": "Notify requester of comment update",
  "active": true,
  "conditions": { ... },
  "actions": [ ... ],
  "description": "Notifies requester that a comment was updated"
}

Rule Diff
Name Type Comment
source_id integer ID of the source revision
target_id integer ID of the target revision
active array An array of change objects
title array An array of change objects
description array An array of change objects
conditions object The changes to conditions. See Condition Diffs
actions array An array that contains action diff objects
Example
 
{
  "diff": {
    "source_id": 1,
    "target_id": 2,
    "title": [
      {
        "change": "-",
        "content": "deleted title"
      },
      {
        "change": "+",
        "content": "new title"
      }
    ],
    "description": [
      {"change": "=", "content": "A thing!"}
    ],
    "active": [
      {
        "change": "-",
        "content": true
      },
      {
        "change": "+",
        "content": false
      }
    ],
    "conditions": {
      "all": [
        {
          "field": [
            {"change": "+", "content": "status"},
            {"change": "-", "content": "current_tags"}
          ],
          "operator": [
            {"change": "+", "content": "is"},
            {"change": "-", "content": "includes"}
          ],
          "value": [
            {"change": "+", "content": "open"},
            {"change": "-", "content": "tag"}
          ],
        }
      ]
    },
    "actions": [
      {
        "field": [
          {"change": "=", "content": "priority"},
        ],
        "value": [
          {"change": "+", "content": "low"},
          {"change": "-", "content": "high"}
        ]
      }
    ]
  }
}

Changes

Changes consist of an array of zero or more change objects.

Each change object in the array has the following properties:

Name Type Description
change string One of -, +, = representing the type of change
content string The value of the item it represents
Example
 
[
  { "change": "+", "content": "solved" },
  { "change": "-", "content": "open" }
]

Condition Diffs

Condition diffs are represented as a JSON object with two arrays of one or more condition diff objects.

Example

{
  "conditions": {
    "any": [{"field": [ ... ], "operator": [ ... ], "value": [ ... ]}],
    "all": [{"field": [ ... ], "operator": [ ... ], "value": [ ... ]}]
  }
}

Each condition diff has the following properties:

Name Type Description
field array An array of change objects
operator array An array of change objects
value array An array of change objects

Action Diffs

Action diffs are represented by an array of one or more diff action objects.

Example

{
  "actions": [
    {"field": [ ... ], "value": [ ... ]},
    {"field": [ ... ], "value": [ ... ]}
  ]
}

Each action diff has the following properties:

Name Type Description
field array An array of change objects
value array An array of change objects

List Trigger Revisions

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

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.

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

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

Getting Revisions

GET /api/v2/triggers/{trigger_id}/revisions/{revision_id}.json

Fetch 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
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions/{revision_id}.json \
  -v -u {email}:{password}
Example Response
 
Status: 200 OK

{
  "trigger_revision": {
    "url": "https://{subdomain}.zendesk.com/api/v2/trigger/123/revisions/100.json"
    "id": 100,
    "author_id": 2,
    "snapshot": {
      "title": "Notify requester of comment update",
      "active": true,
      "conditions": { ... },
      "actions": [ ... ],
      "description": "Notifies requester that a comment was updated"
    },
    "created_at": "2016-08-15T16:04:06Z"
  }
}