> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trigger Workflow (single or bulk)
> 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.
**Bulk trigger** uses this same endpoint (`POST /trigger/`), just pass array of entire workflow object in the body.
## OpenAPI
````yaml POST /trigger/
openapi: 3.1.1
info:
title: SuprSend API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
paths:
/trigger/:
post:
summary: Trigger Workflow (single or bulk)
description: >
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.
operationId: trigger-workflow-api
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/WorkflowTriggerSingleBody'
title: Single workflow trigger
description: Send a single workflow trigger object as the request body.
- title: Bulk workflow trigger
type: array
description: >
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.
maxItems: 100
items:
$ref: '#/components/schemas/WorkflowTriggerSingleBody'
responses:
'202':
description: 202 - Accepted (returned for single workflow trigger requests).
content:
application/json:
examples:
Result:
value:
message_id: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status: success
schema:
type: object
description: >-
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.
properties:
message_id:
type: string
description: Unique identifier of the message generated by SuprSend.
example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status:
type: string
example: success
'207':
description: >-
207 - Multi-Status (returned for bulk workflow trigger requests).
Inspect each record's `status` and `error` for individual outcomes.
content:
application/json:
examples:
Result:
value:
records:
- status: success
message_id: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status_code: 202
- status: error
status_code: 404
error:
message: workflow not found
type: not_found
status: success
schema:
type: object
description: >-
Per-record outcomes for a bulk workflow trigger request. Each
item in `records` corresponds to the workflow at the same
index in the request array.
properties:
records:
type: array
description: >-
Per-record outcomes, in the same order as the request
array.
items:
type: object
properties:
status:
type: string
enum:
- success
- error
description: >-
Per-record status. `success` means the workflow was
accepted; `error` means it was rejected.
status_code:
type: integer
description: >-
Per-record HTTP-style status code (for example,
`202` for accepted, `404` for workflow not found).
message_id:
type: string
description: >-
Unique identifier of the message generated by
SuprSend. Present only when `status` is `success`.
error:
type: object
description: Present only when `status` is `error`.
properties:
message:
type: string
description: >-
Human-readable error message for the failed
record.
type:
type: string
description: >-
Machine-readable error type (for example,
`not_found`).
status:
type: string
description: >-
Top-level status returned by the API. Inspect each
record's `status` and `error` to determine per-record
outcomes.
example: success
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
status: fail
message: BAD REQUEST
schema:
type: object
description: This error would come if the API request format is incorrect.
properties:
status:
type: string
example: fail
message:
type: string
example: BAD REQUEST
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
status: fail
message: workflow 'workflow_slug' not found
schema:
type: object
description: This error would come if the workflow slug is not found.
properties:
status:
type: string
example: fail
message:
type: string
example: workflow 'workflow_slug' not found
deprecated: false
security:
- BearerAuth: []
x-codeSamples:
- lang: cURL
label: Trigger Workflow
source: |
curl --request POST \
--url 'https://hub.suprsend.com/trigger/' \
--header 'Authorization: Bearer __your_api_key__' \
--header 'Content-Type: application/json' \
--data '{
"workflow": "demo_notification_workflow",
"recipients": [
{
"distinct_id": "user123",
"$email": ["user@example.com"]
}
],
"data": {
"user_name": "John Doe",
"welcome_message": "Welcome to our platform!"
}
}'
- lang: cURL
label: Bulk Trigger Workflows
source: |
curl --request POST \
--url 'https://hub.suprsend.com/trigger/' \
--header 'Authorization: Bearer __your_api_key__' \
--header 'Content-Type: application/json' \
--data '[
{
"workflow": "demo_notification_workflow",
"recipients": [
{
"distinct_id": "user123",
"$email": ["user@example.com"]
}
],
"data": {
"user_name": "John Doe",
"welcome_message": "Welcome to our platform!"
}
},
{
"workflow": "demo_notification_workflow",
"recipients": [
{
"distinct_id": "user123",
"$email": ["user@example.com"]
}
],
"data": {
"user_name": "John Doe",
"welcome_message": "Welcome to our platform!"
}
}
]'
components:
schemas:
WorkflowTriggerSingleBody:
type: object
description: >-
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.
required:
- workflow
- recipients
properties:
workflow:
type: string
description: >-
You can get workflow slug from workflow settings on SuprSend
dashboard.
default: _workflow_slug_
recipients:
type: array
description: >-
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.
items:
oneOf:
- type: object
title: Identify user inline
description: >-
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.
required:
- distinct_id
properties:
is_transient:
type: boolean
description: >-
set `is_transient = true` to send notification to
anonymous user. You don't need to pass `distinct_id` for
anonymous sending.
distinct_id:
type: string
description: unique identifier of the user who needs to be notified
default: id1
$channels:
type: array
items:
type: string
example: email
description: channel to send notification to
enum:
- email
- sms
- inbox
- androidpush
- iospush
- slack
- ms_teams
- webpush
- whatsapp
$email:
type: array
items:
type: string
format: email
example: john@example.com
$sms:
type: array
items:
type: string
example: '+1234567890'
$inbox:
type: array
items:
type: string
example: 4nlPk4t4kurG5kChxxxx
$androidpush:
type: array
items:
type: string
example: __android_push_token__
$iospush:
type: array
items:
type: string
example: __ios_push_token__
$slack:
type: array
description: Slack channel configuration
items:
oneOf:
- type: object
title: Slack using email
required:
- email
- access_token
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: Slack using member ID
required:
- user_id
- access_token
properties:
user_id:
type: string
description: Slack user ID (U/WXXXXXXXX format)
example: U/WXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using channel
required:
- channel
- access_token
properties:
channel:
type: string
description: Slack channel ID (CXXXXXXXX format)
example: CXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Slack incoming webhook URL
example: >-
https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX
$ms_teams:
type: array
description: Microsoft Teams channel configuration
items:
oneOf:
- type: object
title: MS Teams using conversation ID
required:
- tenant_id
- service_url
- conversation_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
conversation_id:
type: string
description: Microsoft Teams conversation ID
example: 19:c1524d7c-a06f-456f-8abe-xxxx
- type: object
title: MS Teams using user ID
required:
- tenant_id
- service_url
- user_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
user_id:
type: string
description: Microsoft Teams user ID
example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx
- type: object
title: MS Teams using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Microsoft Teams incoming webhook URL
example: >-
https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX
$timezone:
type: string
example: America/New_York
$locale:
type: string
example: en_GB
- type: object
title: Notify object
required:
- id
- object_type
properties:
id:
type: string
description: Unique identifier of the object
example: frontend
object_type:
type: string
description: Filename to be shown in email
additionalProperties:
type: string
description: >-
You can pass other user properties similar to recipient
payload. It will be used when notification is sent to object
channels as $recipient..
actor:
type: object
description: >-
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.`.
properties:
is_transient:
type: boolean
description: >-
set `is_transient = true` to pass anonymous actor. You don't
need to pass `distinct_id` for anonymous user.
distinct_id:
type: string
description: unique identifier of the actor who performed the action
default: id1
additionalProperties:
type: string
description: >-
You can pass additional actor properties as
`"user_prop1":"value1"` . Extra properties will be update in user
profile which can then be used in the template as
`$actor.`.
data:
type: object
description: >-
variable data required to render dynamic template content or
workflow properties like dynamic delay or channel override in send
node.
properties:
$attachments:
type: array
description: >-
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).
items:
oneOf:
- type: object
title: Pass Public URL
description: >-
Pass file as **publicly accessible URL** (No limit on file
size)
required:
- url
properties:
url:
type: string
format: uri
description: Publicly accessible URL of the file
example: https://bitcoincore.org/bitcoin.pdf
filename:
type: string
description: Filename to be shown in email
example: billing.pdf
ignore_if_error:
type: boolean
description: Ignore the attachment if it fails to load
- type: object
title: Pass Base64 File Locally
description: Pass file as a **base-64 file** (supported limit < 50KB)
required:
- data
properties:
data:
type: string
description: Base64-encoded content of the file
filename:
type: string
description: Filename to be shown in email
contentType:
type: string
example: application/pdf
additionalProperties:
type: string
tenant_id:
type: string
description: >-
string identifier of the tenant/tenant this workflow is associated
with. Used to trigger
[multi-tenant](https://docs.suprsend.com/docs/tenant-workflows)
notifications
$idempotency_key:
type: string
description: Idempotency_key (valid for 24hrs)
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
is your auth token.
BearerAuth:
type: http
scheme: bearer
bearerFormat: API_Key
description: >-
Pass as `Bearer `. Get API Key from SuprSend dashboard
Developers -> API Keys section.
````