---
title: "Trigger Workflow (single or bulk)"
method: POST
path: "/trigger/"
---

# Trigger Workflow (single or bulk)

`POST /trigger/`

API to trigger multi-step workflow to one or more users/objects by passing workflow slug, via `POST /trigger/`.

Send a single JSON **object** to trigger one workflow, or an array of objects to trigger multiple workflows in one call.

## Request body

- union
  - WorkflowTriggerSingleBody — A single workflow trigger payload. Send this object as-is for a single workflow trigger, or wrap multiple instances in a JSON array for a bulk trigger.
    - `workflow` string, required — You can get workflow slug from workflow settings on SuprSend dashboard.
    - `recipients` union[], required — List of recipients to be notified. You can either add recipient as array of distinct_ids or array of recipient objects. You can add up to 100 recipients in a single API.
      - union
        - object — You can pass user properties and channels inline in workflow trigger request. Properties and channels passed here also update in user profile on workflow trigger.
          - `is_transient` boolean — set `is_transient = true` to send notification to anonymous user. You don't need to pass `distinct_id` for anonymous sending.
          - `distinct_id` string, required — unique identifier of the user who needs to be notified
          - `$channels` string[]
          - `$email` string[]
          - `$sms` string[]
          - `$inbox` string[]
          - `$androidpush` string[]
          - `$iospush` string[]
          - `$slack` union[] — Slack channel configuration
            - union
              - …
          - `$ms_teams` union[] — Microsoft Teams channel configuration
            - union
              - …
          - `$timezone` string
          - `$locale` string
          - `$context` object — Scoping context for the inline profile fields on this recipient. Use `$context.tenant_id` when you want the properties and channels passed in this recipient object to be written against a specific tenant's per-tenant profile instead of the user's global profile. See [User-Tenant Mapping](/docs/user-tenant-mapping).
            - `tenant_id` string — Tenant to scope inline profile updates to. When set, must equal the top-level `tenant_id` on the trigger — mismatched values reject the request and the workflow does not run.
        - object
          - `id` string, required — Unique identifier of the object
          - `object_type` string, required — Filename to be shown in email
    - `actor` object — Includes distinct_id and properties of the user who performed the action. You can use it for [cross-user notifications]("https://docs.suprsend.com/docs/trigger-workflow#sending-cross-user-notifications"). Actor properties can be added as `$actor.<prop>`.
      - `is_transient` boolean — set `is_transient = true` to pass anonymous actor. You don't need to pass `distinct_id` for anonymous user.
      - `distinct_id` string — unique identifier of the actor who performed the action
      - `$context` object — Scoping context for the inline profile fields on the actor. Use `$context.tenant_id` to write actor properties and channels against a specific tenant's per-tenant profile. See [User-Tenant Mapping](/docs/user-tenant-mapping).
        - `tenant_id` string — Tenant to scope inline actor updates to. When set, must equal the top-level `tenant_id` on the trigger — mismatched values reject the request and the workflow does not run.
    - `data` object — variable data required to render dynamic template content or workflow properties like dynamic delay or channel override in send node.
      - `$attachments` union[] — Use this key to pass email attachment in the trigger. You can either pass attachment as a public URL or as a base64-encoded file (limit < 50KB).
        - union
          - object — Pass file as **publicly accessible URL** (No limit on file size)
            - `url` string, uri, required — Publicly accessible URL of the file
            - `filename` string — Filename to be shown in email
            - `ignore_if_error` boolean — Ignore the attachment if it fails to load
          - object — Pass file as a **base-64 file** (supported limit < 50KB)
            - `data` string, required — Base64-encoded content of the file
            - `filename` string — Filename to be shown in email
            - `contentType` string
    - `tenant_id` string — Tenant context for this trigger. Applies the tenant's branding, admin preferences, and vendor routing, and — for users with a [per-tenant profile](/docs/user-tenant-mapping) — resolves recipients against the merged (global + per-tenant) profile.
    - `$idempotency_key` string — Idempotency_key (valid for 24hrs)
  - WorkflowTriggerSingleBody[] — Send a JSON **array** of workflow trigger objects (instead of a single JSON **object**) to trigger multiple workflows in one request. Each array item uses the same payload structure as a single workflow trigger (see **Single workflow trigger**). Each record is independent - `workflow` (workflow slug), `recipients`, `tenant_id`, and `data` (including `data.$attachments` for email attachments) can all differ per record. **Limits:** - Maximum **800 KB** total request body size. - Maximum **100 records** per request. Behavior beyond these limits is undefined. **Rate limits:** A bulk request counts as **N calls** (one per record), not one call, against your rate limit. Returns **207 Multi-Status** with per-record outcomes. See the `207` response below.
    - `workflow` string, required — You can get workflow slug from workflow settings on SuprSend dashboard.
    - `recipients` union[], required — List of recipients to be notified. You can either add recipient as array of distinct_ids or array of recipient objects. You can add up to 100 recipients in a single API.
      - union
        - object — You can pass user properties and channels inline in workflow trigger request. Properties and channels passed here also update in user profile on workflow trigger.
          - `is_transient` boolean — set `is_transient = true` to send notification to anonymous user. You don't need to pass `distinct_id` for anonymous sending.
          - `distinct_id` string, required — unique identifier of the user who needs to be notified
          - `$channels` string[]
          - `$email` string[]
          - `$sms` string[]
          - `$inbox` string[]
          - `$androidpush` string[]
          - `$iospush` string[]
          - `$slack` union[] — Slack channel configuration
            - union
              - …
          - `$ms_teams` union[] — Microsoft Teams channel configuration
            - union
              - …
          - `$timezone` string
          - `$locale` string
          - `$context` object — Scoping context for the inline profile fields on this recipient. Use `$context.tenant_id` when you want the properties and channels passed in this recipient object to be written against a specific tenant's per-tenant profile instead of the user's global profile. See [User-Tenant Mapping](/docs/user-tenant-mapping).
            - `tenant_id` string — Tenant to scope inline profile updates to. When set, must equal the top-level `tenant_id` on the trigger — mismatched values reject the request and the workflow does not run.
        - object
          - `id` string, required — Unique identifier of the object
          - `object_type` string, required — Filename to be shown in email
    - `actor` object — Includes distinct_id and properties of the user who performed the action. You can use it for [cross-user notifications]("https://docs.suprsend.com/docs/trigger-workflow#sending-cross-user-notifications"). Actor properties can be added as `$actor.<prop>`.
      - `is_transient` boolean — set `is_transient = true` to pass anonymous actor. You don't need to pass `distinct_id` for anonymous user.
      - `distinct_id` string — unique identifier of the actor who performed the action
      - `$context` object — Scoping context for the inline profile fields on the actor. Use `$context.tenant_id` to write actor properties and channels against a specific tenant's per-tenant profile. See [User-Tenant Mapping](/docs/user-tenant-mapping).
        - `tenant_id` string — Tenant to scope inline actor updates to. When set, must equal the top-level `tenant_id` on the trigger — mismatched values reject the request and the workflow does not run.
    - `data` object — variable data required to render dynamic template content or workflow properties like dynamic delay or channel override in send node.
      - `$attachments` union[] — Use this key to pass email attachment in the trigger. You can either pass attachment as a public URL or as a base64-encoded file (limit < 50KB).
        - union
          - object — Pass file as **publicly accessible URL** (No limit on file size)
            - `url` string, uri, required — Publicly accessible URL of the file
            - `filename` string — Filename to be shown in email
            - `ignore_if_error` boolean — Ignore the attachment if it fails to load
          - object — Pass file as a **base-64 file** (supported limit < 50KB)
            - `data` string, required — Base64-encoded content of the file
            - `filename` string — Filename to be shown in email
            - `contentType` string
    - `tenant_id` string — Tenant context for this trigger. Applies the tenant's branding, admin preferences, and vendor routing, and — for users with a [per-tenant profile](/docs/user-tenant-mapping) — resolves recipients against the merged (global + per-tenant) profile.
    - `$idempotency_key` string — Idempotency_key (valid for 24hrs)

## Response `202`

202 - Accepted (returned for single workflow trigger requests).

- object — All workflow requests will be accepted as long as the API request is correct. To verify if the execution was successful, check the 'Requests' tab under the 'Logs' section on the SuprSend dashboard.
  - `message_id` string — Unique identifier of the message generated by SuprSend.
  - `status` string

## Other responses

- `207` — 207 - Multi-Status (returned for bulk workflow trigger requests). Inspect each record's `status` and `error` for individual outcomes.
- `400` — 400 - Bad Request
- `404` — 404 - Not Found

---

[API](https://skmtc.net/suprsend/apis/suprsend-api.md) · [All operations](https://skmtc.net/suprsend/apis/suprsend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/suprsend/suprsend-api/versions/8bd2574bd2c3/schema)