Trigger Step

The trigger step is the starting point of every notiflow. When you run a notiflow via the API, execution begins at this step and flows through the subsequent steps.

How It Works

When you call the run endpoint, you provide:

• Recipients — The users who will receive the notifications
• Actor (optional) — The user who caused the notification (e.g., the commenter, the follower)
• Data (optional) — Custom payload with dynamic content for templates
• Topic (alternative) — Send to all users subscribed to a topic instead of listing recipients

The trigger step receives this data and passes it to every subsequent step in the flow.

Running via API

Use the Admin API to run a notiflow:

curl -X POST https://api.notiflows.com/admin/notiflows/{notiflow_id}/run \
  -H "x-notiflows-api-key: pk_your_api_key" \
  -H "x-notiflows-secret-key: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "external_id": "user_123",
        "email": "jane@example.com",
        "first_name": "Jane"
      }
    ],
    "actor": {
      "external_id": "user_456",
      "first_name": "Alex"
    },
    "data": {
      "order_id": "ORD-789",
      "total": "$99.00"
    }
  }'

Authentication

The Admin API requires two headers:

Find both keys in your Notiflows Dashboard under Project Settings.

Request Body

Recipients

The recipients field is an array of user objects. Each object must include an external_id — the user ID from your system. You can also include user attributes that will be stored and available in templates:

{
  "recipients": [
    {
      "external_id": "user_123",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "avatar": "https://example.com/avatars/jane.jpg",
      "locale": "en-US",
      "timezone": "America/New_York",
      "custom_fields": {
        "plan": "premium",
        "company": "Acme Inc"
      }
    }
  ]
}

If a recipient with the given external_id doesn't exist yet, Notiflows creates the user automatically with the provided attributes. If they already exist, their attributes are updated.

Actor

The actor field is optional and uses the same structure as a recipient object. The actor represents the user who triggered the notification — for example, the person who commented on a post or followed another user.

{
  "actor": {
    "external_id": "user_456",
    "first_name": "Alex"
  }
}

Data

The data field is an optional JSON object containing any custom payload you want to use in templates:

{
  "data": {
    "order_id": "ORD-789",
    "total": "$99.00",
    "items": [
      { "name": "Widget", "quantity": 2 }
    ]
  }
}

Topic (Alternative to Recipients)

Instead of listing individual recipients, you can send to all users subscribed to a topic:

{
  "topic": "order-updates",
  "data": {
    "order_id": "ORD-789"
  }
}

You must provide either recipients or topic, but not both.

Response

A successful request returns 201 Created:

{
  "notiflow_run_id": "01HQXYZ123456789ABCDEFGHIJ"
}

Errors

Prerequisites

Before a notiflow can be run:

1. The notiflow must have a published version — see Versioning
2. The notiflow must be active (not deactivated)

Data Context

The data you pass when running becomes available in templates throughout the flow:

See Templates for how to use these variables.

Connected Steps

The trigger step connects to the first action step in your flow. This is typically a channel step, but could also be a control step like wait, digest, or a condition step for routing.