---
title: "Trigger workflow"
method: POST
path: "/v1/workflows/{key}/trigger"
tags: ["Workflows"]
---

# Trigger workflow

`POST /v1/workflows/{key}/trigger`

Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.

## Path parameters

- `key` string, required

## Request body

- TriggerWorkflowRequest — A request to trigger a notification workflow.
  - `actor` union — A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
    - union — Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a `collection` property.
      - string — The ID of the user which is used as the reference for the recipient.
      - object — A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
        - `avatar` string, nullable — A URL for the avatar of the user.
        - `channel_data` InlineChannelDataRequest — A request to set channel data for a type of channel inline.
        - `created_at` string, date-time, nullable — The creation date of the user from your system.
        - `email` string, nullable — The primary email address for the user.
        - `id` string, required — The unique identifier of the user.
        - `locale` string, nullable — The locale of the user. Used for [message localization](/concepts/translations).
        - `name` string, nullable — Display name of the user.
        - `phone_number` string, nullable — The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
        - `preferences` InlinePreferenceSetRequest — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
        - `timezone` string, nullable — The timezone of the user. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
      - object — A custom [Object](/concepts/objects) entity which belongs to a collection.
        - `channel_data` union — An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.
          - object — A request to set channel data for a type of channel inline.
          - unknown
        - `collection` string, required — The collection this object belongs to.
        - `created_at` string, date-time, nullable — Timestamp when the resource was created.
        - `id` string, required — Unique identifier for the object.
        - `name` string, nullable — An optional name for the object.
        - `preferences` union — An optional set of [preferences](/concepts/preferences) for the object.
          - object — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
          - unknown
    - unknown
  - `cancellation_key` string, nullable — An optional key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.
  - `data` object, nullable — An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.
  - `recipients` RecipientRequest[], required — The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.
    - union — Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a `collection` property.
      - string — The ID of the user which is used as the reference for the recipient.
      - object — A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
        - `avatar` string, nullable — A URL for the avatar of the user.
        - `channel_data` InlineChannelDataRequest — A request to set channel data for a type of channel inline.
        - `created_at` string, date-time, nullable — The creation date of the user from your system.
        - `email` string, nullable — The primary email address for the user.
        - `id` string, required — The unique identifier of the user.
        - `locale` string, nullable — The locale of the user. Used for [message localization](/concepts/translations).
        - `name` string, nullable — Display name of the user.
        - `phone_number` string, nullable — The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the user (required for SMS channels).
        - `preferences` InlinePreferenceSetRequest — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
        - `timezone` string, nullable — The timezone of the user. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
      - object — A custom [Object](/concepts/objects) entity which belongs to a collection.
        - `channel_data` union — An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.
          - object — A request to set channel data for a type of channel inline.
          - unknown
        - `collection` string, required — The collection this object belongs to.
        - `created_at` string, date-time, nullable — Timestamp when the resource was created.
        - `id` string, required — Unique identifier for the object.
        - `name` string, nullable — An optional name for the object.
        - `preferences` union — An optional set of [preferences](/concepts/preferences) for the object.
          - object — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
          - unknown
  - `tenant` union — The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.
    - union — An request to set a tenant inline.
      - string — The unique identifier for the tenant.
      - object — A tenant to be set in the system. You can supply any additional properties on the tenant object.
        - `channel_data` union — The channel data for the tenant.
          - unknown
          - object — A request to set channel data for a type of channel inline.
        - `id` string, required — The unique identifier for the tenant.
        - `name` string, nullable — An optional name for the tenant.
        - `preferences` union — The preferences for the tenant.
          - unknown
          - object — Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
        - `settings` object — The settings for the tenant. Includes branding and preference set.
          - `branding` object — The branding for the tenant.
            - `icon_url` string, nullable — The icon URL for the tenant. Must point to a valid image with an image MIME type.
            - `logo_url` string, nullable — The logo URL for the tenant. Must point to a valid image with an image MIME type.
            - `primary_color` string, nullable — The primary color for the tenant, provided as a hex value.
            - `primary_color_contrast` string, nullable — The primary color contrast for the tenant, provided as a hex value.
          - `preference_set` union — The preference set for the tenant. Used to override the default preference set.
            - unknown
            - object — A request to set a preference set for a recipient.
              - …
    - unknown

## Response `200`

OK

- TriggerWorkflowResponse — The response from triggering a workflow.
  - `workflow_run_id` string, uuid, required — This value allows you to track individual messages associated with this trigger request.

---

[API](https://skmtc.net/knocklabs/apis/knock-api.md) · [All operations](https://skmtc.net/knocklabs/apis/knock-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/knocklabs/knock-api/revisions/4b8499dddbc5/schema)