The Zendesk Triggers API lets you programmatically manage the ticket triggers that power automation in Zendesk Support. Triggers are eventbased business rules that run immediately after a ticket is created or updated; when their conditions match, they perform actions like assigning or routing tickets, adding/removing tags, setting fields or status, sending notifications, and invoking webhooks.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Triggers
description: Needs a description.
paths:
/api/v2/custom_objects/{custom_object_key}/triggers:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
get:
operationId: ListObjectTriggers
tags:
- Object Triggers
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Triggers
description: |
Lists all triggers for the specified custom object.
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/TriggerActive'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggersResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggersResponseExample'
post:
operationId: CreateObjectTrigger
tags:
- Object Triggers
summary: Zendesk Post Api V2 Custom_objects Custom_object_key Triggers
description: >
Creates a new object trigger for a specified object.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerRequest'
examples:
default:
$ref: '#/components/examples/ObjectTriggerRequestExample'
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggerResponseExample'
/api/v2/custom_objects/{custom_object_key}/triggers/{trigger_id}:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/TriggerId'
get:
operationId: GetObjectTrigger
tags:
- Object Triggers
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Triggers Trigger_id
description: |
Returns details of a specific object trigger.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggerResponseExample'
put:
operationId: UpdateObjectTrigger
tags:
- Object Triggers
summary: Zendesk Put Api V2 Custom_objects Custom_object_key Triggers Trigger_id
description: >
Updates a specified object trigger.
**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.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerRequest'
examples:
default:
$ref: '#/components/examples/ObjectTriggerRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggerResponseExample'
delete:
operationId: DeleteObjectTrigger
tags:
- Object Triggers
summary: Zendesk Delete Api V2 Custom_objects Custom_object_key Triggers Trigger_id
description: >
Deletes a specified object trigger.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
responses:
'204':
description: No Content response
/api/v2/custom_objects/{custom_object_key}/triggers/active:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
get:
operationId: ListActiveObjectTriggers
tags:
- Object Triggers
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Triggers Active
description: >
Lists all active object triggers.
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggersResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggersActiveResponseExample'
/api/v2/custom_objects/{custom_object_key}/triggers/definitions:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
get:
operationId: ListObjectTriggersDefinitions
tags:
- Object Triggers
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Triggers Definitions
description: >
Lists the conditions and actions of all triggers for the specified
custom object.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerDefinitionResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggerDefinitionResponseExample'
/api/v2/custom_objects/{custom_object_key}/triggers/destroy_many:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/TriggerIds'
delete:
operationId: DeleteManyObjectTriggers
tags:
- Object Triggers
summary: Zendesk Delete Api V2 Custom_objects Custom_object_key Triggers Destroy_many
description: >
Deletes the object triggers corresponding to the provided
comma-separated list of ids.
**Note**: You can only bulk-delete triggers associated with one object
at a time, specified by the `custom_object_key` in the request.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
#### Request Parameters
The DELETE request takes an `ids` object that lists the
object triggers to delete. All of the specified object trigger `ids`
must be associated with a single object.
| Name | Description
| ---- | -----------
| ids | The ids of the triggers to delete
#### Example request
```js
{
"ids": "25,23,27,22"
}
```
responses:
'204':
description: No content response
/api/v2/custom_objects/{custom_object_key}/triggers/search:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/TriggerSearchQuery'
- $ref: '#/components/parameters/TriggerSearchFilter'
- $ref: '#/components/parameters/TriggerActive'
- $ref: '#/components/parameters/TriggerSort'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
- $ref: '#/components/parameters/TriggerInclude'
get:
operationId: SearchObjectTriggers
tags:
- Object Triggers
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Triggers Search
description: >
Returns a list of object triggers that meet your filter or search
criteria.
#### Pagination
* Offset pagination only
See [Using Offset
Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Allowed For
* Agents
#### Filter
Use the `filter` query parameter to filter an object trigger search by
one or more attributes. For example, the following `filter` argument
filters object triggers by the `title` attribute:
```json
{
"json": {
"title": "test"
}
}
```
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggersResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggersSearchResponseExample'
/api/v2/custom_objects/{custom_object_key}/triggers/update_many:
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
put:
operationId: UpdateManyObjectTriggers
tags:
- Object Triggers
summary: Zendesk Put Api V2 Custom_objects Custom_object_key Triggers Update_many
description: >
Updates the position or the active status of multiple object triggers.
Any additional properties are ignored.
**Note**: You can only bulk-update triggers associated with one object
at a time, specified by the `custom_object_key` in the request.
#### Allowed For
* Administrators
* Agents in custom roles with the `manage_triggers` permission
(Enterprise only)
#### Request Parameters
The PUT request expects a `triggers` object that lists the object
triggers to update. All of the specified object trigger `ids` must be
associated with a single object.
You can specify the following properties for each object trigger you're
updating:
| Name | Mandatory | Description
| -------- | --------- | -----------
| id | yes | The ID of the object trigger to update
| position | no | The new position of the object trigger
| active | no | The active status of the object trigger
(true or false)
#### Example Request
```js
{
"triggers": [
{"id": 25, "position": 3},
{"id": 23, "active": true},
{"id": 27, "position": 9, "active": false},
{"id": 22, "position": 7}
]
}
```
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggerBulkUpdateRequest'
examples:
default:
$ref: '#/components/examples/ObjectTriggerBulkUpdateRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTriggersResponse'
examples:
default:
$ref: '#/components/examples/ObjectTriggersResponseExample'
/api/v2/triggers:
get:
operationId: ListTriggers
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers
description: >
Lists all ticket triggers for the current account.
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
#### 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 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:
- $ref: '#/components/parameters/TriggerActive'
- $ref: '#/components/parameters/TriggerSort'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
- $ref: '#/components/parameters/TriggerCategoryId'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggersResponse'
examples:
default:
$ref: '#/components/examples/TriggersResponseExample'
post:
operationId: CreateTrigger
tags:
- Triggers
summary: Zendesk Post Api V2 Triggers
description: |
#### Allowed For
* Agents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerWithCategoryRequest'
examples:
default:
$ref: '#/components/examples/TriggerWithCategoryRequestExample'
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
examples:
default:
$ref: '#/components/examples/TriggerResponseExample'
/api/v2/triggers/{trigger_id}:
parameters:
- $ref: '#/components/parameters/TriggerId'
get:
operationId: GetTrigger
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Trigger_id
description: >
#### Allowed For
* Agents
The Via Type value is a number instead of a text string. See [Via types
reference](/documentation/ticketing/reference-guides/via-types/) for the
keys.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
examples:
default:
$ref: '#/components/examples/TriggerResponseExample'
put:
operationId: UpdateTrigger
tags:
- Triggers
summary: Zendesk Put Api V2 Triggers Trigger_id
description: >
#### 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.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerWithCategoryRequest'
examples:
default:
$ref: '#/components/examples/TriggerWithCategoryRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
examples:
default:
$ref: '#/components/examples/TriggerResponseExample'
delete:
operationId: DeleteTrigger
tags:
- Triggers
summary: Zendesk Delete Api V2 Triggers Trigger_id
description: |
#### Allowed For
* Agents
responses:
'204':
description: No Content response
/api/v2/triggers/{trigger_id}/revisions:
parameters:
- $ref: '#/components/parameters/TriggerId'
get:
operationId: ListTriggerRevisions
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Trigger_id Revisions
description: >
List the revisions associated with a ticket trigger. Ticket trigger
revision history is only available on Enterprise plans.
#### 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.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRevisionsResponse'
examples:
default:
$ref: '#/components/examples/TriggerRevisionsResponseExample'
/api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}:
parameters:
- $ref: '#/components/parameters/TriggerId'
- $ref: '#/components/parameters/TriggerRevisionId'
get:
operationId: TriggerRevision
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Trigger_id Revisions Trigger_revision_id
description: >
Fetches a revision associated with a ticket trigger. Ticket trigger
revision history is only available on Enterprise plans.
#### Allowed For
* Agents
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ----- | -------------
| users | The user that authored each revision
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRevisionResponse'
examples:
default:
$ref: '#/components/examples/TriggerRevisionResponseExample'
/api/v2/triggers/active:
parameters:
- $ref: '#/components/parameters/TriggerSort'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
- $ref: '#/components/parameters/TriggerCategoryId'
get:
operationId: ListActiveTriggers
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Active
description: >
Lists all active ticket triggers.
#### Pagination
- Cursor pagination (recommended)
- Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
#### Sideloads
The following sideloads are supported:
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each ticket
trigger, if present
| permissions | The permissions for each trigger
| usage_1h | The number of times each ticket trigger has been
used in the past hour
| usage_24h | The number of times each ticket trigger has been
used in the past day
| usage_7d | The number of times each ticket trigger has been
used in the past week
| usage_30d | The number of times each ticket trigger has been
used in the past thirty days
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggersResponse'
examples:
default:
$ref: '#/components/examples/TriggersActiveResponseExample'
/api/v2/triggers/definitions:
get:
operationId: ListTriggerActionConditionDefinitions
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Definitions
description: >
Returns the definitions of the actions a ticket trigger can perform and
the
definitions of the conditions under which a ticket 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](/documentation/ticketing/reference-guides/actions-reference)
For a list of supported conditions, see the [Conditions
reference](/documentation/ticketing/reference-guides/conditions-reference)
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerDefinitionResponse'
examples:
default:
$ref: '#/components/examples/TriggerDefinitionResponseExample'
/api/v2/triggers/destroy_many:
parameters:
- $ref: '#/components/parameters/TriggerIds'
delete:
operationId: DeleteManyTriggers
tags:
- Triggers
summary: Zendesk Delete Api V2 Triggers Destroy_many
description: >
Deletes the ticket 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
ticket triggers to delete.
| Name | Description
| ---- | -----------
| ids | The IDs of the triggers to delete
#### Example request
```js
{
"ids": "25,23,27,22"
}
```
responses:
'204':
description: No content response
/api/v2/triggers/reorder:
put:
operationId: ReorderTriggers
tags:
- Triggers
summary: Zendesk Put Api V2 Triggers Reorder
description: >
Alters the firing order of ticket triggers in the account. See
[Reordering and sorting
triggers](https://support.zendesk.com/hc/en-us/articles/115015696088)
in the Zendesk Help Center. The firing order is set in a `trigger_ids`
array in the request body.
You must include every ticket trigger id in your account to reorder the
ticket triggers. If not, the endpoint will return 404 Forbidden.
Reordering ticket triggers via the API is not permitted if you have more
than one ticket trigger category. If there is more than one
ticket trigger category, the endpoint will return a `LimitOneCategory`
error.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
examples:
default:
$ref: '#/components/examples/TriggerResponseExample'
/api/v2/triggers/search:
parameters:
- $ref: '#/components/parameters/TriggerSearchQuery'
- $ref: '#/components/parameters/TriggerSearchFilter'
- $ref: '#/components/parameters/TriggerActive'
- $ref: '#/components/parameters/TriggerSort'
- $ref: '#/components/parameters/TriggerSortBy'
- $ref: '#/components/parameters/TriggerSortOrder'
- $ref: '#/components/parameters/TriggerInclude'
get:
operationId: SearchTriggers
tags:
- Triggers
summary: Zendesk Get Api V2 Triggers Search
description: >
#### Pagination
* Offset pagination only
See [Using Offset
Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Allowed For
* Agents
#### Sideloads
The following sideloads are supported. For more information, see
[Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/).
| Name | Will sideload
| ---------------- | -------------
| app_installation | The app installation that requires each ticket
trigger, if present
| permissions | The permissions for each ticket trigger
| usage_1h | The number of times each ticket trigger has been
used in the past hour
| usage_24h | The number of times each ticket trigger has been
used in the past day
| usage_7d | The number of times each ticket trigger has been
used in the past week
| usage_30d | The number of times each ticket trigger has been
used in the past thirty days
#### Filter
Use the `filter` query parameter to filter a ticket trigger search by
one or more attributes. For example, the following `filter` argument
filters ticket triggers by the `description` attribute:
```json
{
"json": {
"description": "Close a ticket"
}
}
```
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggersResponse'
examples:
default:
$ref: '#/components/examples/TriggersSearchResponseExample'
/api/v2/triggers/update_many:
put:
operationId: UpdateManyTriggers
tags:
- Triggers
summary: Zendesk Put Api V2 Triggers Update_many
description: >
Updates the position or the active status of multiple ticket triggers.
Any additional properties are ignored.
#### Allowed For
* Agents
#### Request Parameters
The PUT request expects a `triggers` object that lists the ticket
triggers to update.
Each ticket trigger may have the following properties:
| Name | Mandatory | Description
| -------- | --------- | -----------
| id | yes | The ID of the ticket trigger to update
| position | no | The new position of the ticket trigger
| active | no | The active status of the ticket trigger
(true or false)
| category_id | no | The ID of the new category the ticket
trigger is to be moved to
#### Example Request
```js
{
"triggers": [
{"id": 25, "position": 3},
{"id": 23, "position": 5},
{"id": 27, "position": 9},
{"id": 22, "position": 7}
]
}
```
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerBulkUpdateRequest'
examples:
default:
$ref: '#/components/examples/TriggerBulkUpdateRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggersResponse'
examples:
default:
$ref: '#/components/examples/TriggersResponseExample'
components:
schemas:
ObjectTriggersResponse:
type: object
properties:
count:
type: integer
next_page:
type: string
nullable: true
previous_page:
type: string
nullable: true
triggers:
type: array
items:
$ref: '#/components/schemas/ObjectTriggerObject'
ObjectTriggerResponse:
type: object
properties:
trigger:
$ref: '#/components/schemas/ObjectTriggerObject'
ObjectTriggerDefinitionResponse:
type: object
properties:
definitions:
$ref: '#/components/schemas/ObjectTriggerDefinitionObject'
TriggersResponse:
type: object
properties:
count:
type: integer
next_page:
type: string
nullable: true
previous_page:
type: string
nullable: true
triggers:
type: array
items:
$ref: '#/components/schemas/TriggerObject'
TriggerResponse:
type: object
properties:
trigger:
$ref: '#/components/schemas/TriggerObject'
TriggerRevisionsResponse:
type: object
properties:
after_cursor:
type: string
after_url:
type: string
before_cursor:
type: string
before_url:
type: string
count:
type: integer
trigger_revisions:
type: array
items:
type: object
properties:
author_id:
type: integer
created_at:
type: string
diff:
type: object
properties:
actions:
type: array
description: An array that contain [action diff objects](#Action Diffs)
items:
$ref: '#/components/schemas/TriggerActionDiffObject'
active:
type: array
description: An array of [change](#change) objects
items:
$ref: '#/components/schemas/TriggerChangeObject'
conditions:
$ref: '#/components/schemas/TriggerConditionDiffObject'
description:
type: array
description: An array of [change](#change) objects
items:
$ref: '#/components/schemas/TriggerChangeObject'
source_id:
type: integer
description: ID of the source revision
target_id:
type: integer
description: ID of the target revision
title:
type: array
description: An array of [change](#change) objects
items:
$ref: '#/components/schemas/TriggerChangeObject'
id:
type: integer
snapshot:
$ref: '#/components/schemas/TriggerSnapshotObject'
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zendesk/refs/heads/main/openapi/triggers-openapi-original.yml