Start and resume via API

Two endpoints cover the whole lifecycle from an external system:

POST /platform/v1/workflows/{workflow_id}/executions — start an execution
POST /platform/v1/workflow_executions/{execution_id}/resume — resume an execution that is waiting for input

Both are asynchronous: they queue the work and return immediately.

Before you start

The workflow status must be active
The workflow needs an active API trigger
Every request needs an X-API-Key header

Start an execution

curl -X POST "https://api.kapso.ai/platform/v1/workflows/$WORKFLOW_ID/executions" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_execution": {
      "phone_number": "+14155552671",
      "phone_number_id": "123456789012345",
      "variables": {
        "customer_name": "Alice Smith",
        "order_total": 149.99
      },
      "context": {
        "source": "checkout_flow"
      }
    }
  }'

Field	Description
`phone_number`	E.164 number of the participant. Required unless you send `recipient`.
`recipient`	BSUID or parent BSUID of the participant. Required unless you send `phone_number`.
`phone_number_id`	WhatsApp number that handles the conversation. Defaults to the project’s WhatsApp config.
`whatsapp_config_id`	Deprecated. Use `phone_number_id`.
`variables`	Initial workflow variables, available as `{{var_name}}` or `{{vars.var_name}}`.
`context`	Extra contextual data merged into the `context` namespace, outside the variable namespace.
`initial_data`	Custom payload passed to the workflow’s first step.

Response is 202 Accepted:

{
  "data": {
    "message": "Workflow execution initiated",
    "workflow_id": "workflow_uuid",
    "id": "execution_uuid",
    "tracking_id": "tracking_uuid"
  }
}

Keep id to fetch or resume the execution, and tracking_id to correlate it with your own systems.

Start by BSUID

When you only have a business-scoped user ID, send recipient instead of phone_number:

curl -X POST "https://api.kapso.ai/platform/v1/workflows/$WORKFLOW_ID/executions" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_execution": {
      "recipient": "US.13491208655302741918",
      "phone_number_id": "123456789012345"
    }
  }'

If you send both identifiers, the phone number routes the conversation and the BSUID is kept as the participant identity. BSUID recipients are not supported on sandbox numbers.

Execution context

An API-triggered execution starts with:

{{system.trigger_type}}                            # "api_call"
{{system.tracking_id}}                             # tracking_id from the response
{{system.api_key_id}}                              # API key used
{{system.trigger_whatsapp_config_id}}              # WhatsApp config handling the conversation

{{context.channel}}                                # "api"
{{context.phone_number}}                           # normalized phone number, when sent
{{context.whatsapp_business_scoped_user_id}}       # when recipient is a BSUID
{{context.whatsapp_parent_business_scoped_user_id}} # when recipient is a parent BSUID (US.ENT.…)

{{vars.your_variable}}                             # from the variables object

See Triggers for the full context reference.

Check execution status

curl "https://api.kapso.ai/platform/v1/workflow_executions/$EXECUTION_ID" \
  -H "X-API-Key: $KAPSO_API_KEY"

The execution row is created when the queued job picks up the request, so a lookup fired immediately after the 202 can return 404. Retry after a moment. To find executions that need input, filter the workflow’s execution list:

curl "https://api.kapso.ai/platform/v1/workflows/$WORKFLOW_ID/executions?status=waiting" \
  -H "X-API-Key: $KAPSO_API_KEY"

Resume a waiting execution

An execution enters waiting when it reaches a wait for response step. Resume it with the input the workflow was waiting for:

curl -X POST "https://api.kapso.ai/platform/v1/workflow_executions/$EXECUTION_ID/resume" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "kind": "payload",
      "data": "yes, proceed"
    },
    "variables": {
      "confirmed_at": "2026-08-11T18:00:00Z"
    }
  }'

Field	Description
`message.data`	Required. String, object, or array passed to the waiting step.
`message.kind`	Optional. Defaults to `payload`.
`variables`	Optional. Merged into the execution’s `vars`; existing keys are overwritten.

Note that message and variables sit at the top level, not under workflow_execution. The response is 200 OK with the execution’s id, status, tracking_id, current_step, and timestamps. Resume work runs in the background, so the returned status can still be waiting — poll GET /platform/v1/workflow_executions/{id} to see it advance. Only one resume can be pending at a time. A second request while the first is still pending returns 409 Conflict.

Errors

Status	When
`400`	Resume request without a `message` object or without `message.data`.
`404`	Workflow or execution not found in this project.
`409`	A resume is already pending, or the execution is being processed by another request. Retry after a short delay.
`422`	Workflow not active, no active API trigger, neither `phone_number` nor `recipient` sent, `recipient` is not a valid BSUID or parent BSUID, `recipient` used with a sandbox number, `phone_number_id` not in this project, or the execution is not in `waiting` status.
`429`	Burst rate limit exceeded. Retry after the seconds in `Retry-After`.

The start endpoint has a burst limiter on top of the general rate limits, scoped by API key and workflow, resetting every second:

legacy / free: 5 requests per second
pro: 15 requests per second
enterprise / platform: 30 requests per second

Successful responses carry X-Burst-RateLimit-Limit and X-Burst-RateLimit-Remaining.

Getting started

WhatsApp

For your team

Onboard customers

Automations

Before you start

Start an execution

Start by BSUID

Execution context

Check execution status

Resume a waiting execution

Errors

​Before you start

​Start an execution

​Start by BSUID

​Execution context

​Check execution status

​Resume a waiting execution

​Errors

Before you start

Start an execution

Start by BSUID

Execution context

Check execution status

Resume a waiting execution

Errors