Zendesk Triggers API

openapi: 3.1.0
info:
  version: '1.0'
  title: Zendesk Account Account Settings Triggers API
  description: Needs a description.
tags:
- name: Triggers
paths:
  /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\n\n* Offset pagination only\n\nSee [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination).\n\n#### Allowed For\n\n* Agents\n\n#### Sideloads\n\nThe following sideloads are supported. For more information, see [Side-loading](/documentation/ticketing/using-the-zendesk-api/side_loading/).\n\n| Name             | Will sideload\n| ---------------- | -------------\n| app_installation | The app installation that requires each ticket trigger, if present\n| permissions      | The permissions for each ticket trigger\n| usage_1h         | The number of times each ticket trigger has been used in the past hour\n| usage_24h        | The number of times each ticket trigger has been used in the past day\n| usage_7d         | The number of times each ticket trigger has been used in the past week\n| usage_30d        | The number of times each ticket trigger has been used in the past thirty days\n\n#### Filter\n\nUse 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:\n\n```json\n{\n  \"json\": {\n    \"description\": \"Close a ticket\"\n  }\n}\n```\n"
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggersResponse'
              examples:
                default:
                  $ref: '#/components/examples/TriggersSearchResponseExample'
  /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.\n\n#### Allowed For\n\n * Agents\n\n#### Sideloads\n\nThe following sideloads are supported:\n\n| Name  | Will sideload\n| ----- | -------------\n| users | The user that authored each revision\n\n#### Pagination\n\nThis endpoint uses cursor-based pagination. The records are ordered in\ndescending order by the `created_at` timestamp, then by `id` on duplicate\n`created_at` values.\n\nThe `cursor` parameter is a non-human-readable argument you can use to move\nforward or backward in time.\n\nEach JSON response will contain the following attributes to help you get\nmore results:\n\n- `after_url` requests more recent results\n- `before_url` requests older results\n- `after_cursor` is the cursor to build the request yourself\n- `before_cursor` is the cursor to build the request yourself\n\nThe properties are null if no more records are available.\n\nYou can request a maximum of 1000 records using the `limit` parameter. If\nno `limit` parameter is supplied, it will default to 1,000.\n"
      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.\n\n#### Allowed For\n\n * Agents\n\n#### Sideloads\n\nThe following sideloads are supported:\n\n| Name  | Will sideload\n| ----- | -------------\n| users | The user that authored each revision\n"
      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.\n\n#### Allowed For\n\n* Agents\n\n#### Request Parameters\n\nThe DELETE request takes one parameter, an `ids` object that lists the\nticket triggers to delete.\n\n| Name | Description\n| ---- | -----------\n| ids  | The IDs of the triggers to delete\n\n#### Example request\n\n```js\n{\n  \"ids\": \"25,23,27,22\"\n}\n```\n"
      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/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.\n\n#### Allowed For\n\n* Agents\n\n#### Request Parameters\n\nThe PUT request expects a `triggers` object that lists the ticket triggers to update.\n\nEach ticket trigger may have the following properties:\n\n| Name        | Mandatory | Description\n| --------    | --------- | -----------\n| id          | yes       | The ID of the ticket trigger to update\n| position    | no        | The new position of the ticket trigger\n| active      | no        | The active status of the ticket trigger (true or false)\n| category_id | no        | The ID of the new category the ticket trigger is to be moved to\n\n#### Example Request\n\n```js\n{\n  \"triggers\": [\n    {\"id\": 25, \"position\": 3},\n    {\"id\": 23, \"position\": 5},\n    {\"id\": 27, \"position\": 9},\n    {\"id\": 22, \"position\": 7}\n  ]\n}\n```\n"
      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:
    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'
    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'
              url:
                type: string
    TriggerRevisionResponse:
      type: object
      properties:
        trigger_revision:
          type: object
          properties:
            author_id:
              type: integer
            created_at:
              type: string
            id:
              type: integer
            snapshot:
              type: object
              properties:
                actions:
                  type: array
                  items:
                    $ref: '#/components/schemas/TriggerActionObject'
                active:
                  type: boolean
                conditions:
                  $ref: '#/components/schemas/TriggerConditionsObject'
                description:
                  type: string
                  nullable: true
                title:
                  type: string
            url:
              type: string
    TriggerResponse:
      type: object
      properties:
        trigger:
          $ref: '#/components/schemas/TriggerObject'
    TriggerDefinitionResponse:
      type: object
      properties:
        definitions:
          $ref: '#/components/schemas/TriggerDefinitionObject'