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, timestamps, requested_execution_id, and parent_flow_execution_id. 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.

Executions that call another workflow

When an execution is waiting at a call workflow step, the workflow that actually needs the input is the child execution it started. Resume the execution you started anyway — the input is routed down the chain to the deepest waiting execution:

{
  "data": {
    "id": "child_execution_uuid",
    "requested_execution_id": "parent_execution_uuid",
    "parent_flow_execution_id": "parent_execution_uuid",
    "status": "waiting",
    "current_step": { "identifier": "ask_order_number" }
  }
}

id — the execution that received the input
requested_execution_id — the ID you sent in the path
parent_flow_execution_id — parent of the resumed execution, null at the root

Keep using the original execution ID for every reply; it stays valid as the child chain starts and finishes. variables you send are merged into the child that receives the input, and merge back into the parent when the child returns. GET /platform/v1/workflow_executions/{id} reports where input can go next in resumable_execution_id. It equals id for a plain waiting execution, points at the child while a call workflow is in progress, and is null when nothing in the chain is waiting. The execution list does not resolve this field. If the call workflow step was edited to call a different workflow while its child was still active, resume returns 422 with error: "Execution configuration changed". No input or variables are applied, and the child is preserved. Restore the original called workflow before retrying.

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, the execution is not in `waiting` status, or the call workflow configuration changed while its child was active.
`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

Migrate to Kapso

Before you start

Start an execution

Start by BSUID

Execution context

Check execution status

Resume a waiting execution

Executions that call another workflow

Errors

​Before you start

​Start an execution

​Start by BSUID

​Execution context

​Check execution status

​Resume a waiting execution

​Executions that call another workflow

​Errors

Before you start

Start an execution

Start by BSUID

Execution context

Check execution status

Resume a waiting execution

Executions that call another workflow

Errors