Skip to main content
POST
/
flows
/
{flow_id}
/
executions
Create a new flow execution
curl --request POST \
  --url https://app.kapso.ai/api/v1/flows/{flow_id}/executions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "phone_number": "+1234567890",
  "whatsapp_config_id": "config-123abc",
  "variables": {
    "user_id": "123",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "context": {
    "source": "mobile_app",
    "version": "1.2.3"
  },
  "initial_data": {}
}
'
{
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": "Flow execution queued"
}

Authorizations

​
X-API-Key
string
header
required

API key required for all endpoints

Path Parameters

​
flow_id
string<uuid>
required

Body

application/json
​
phone_number
string
required

Phone number to associate with this flow execution (required for conversation tracking)

Example:

"+1234567890"

​
whatsapp_config_id
string<uuid>

Optional WhatsApp configuration to use for this execution. Must belong to the project (direct or via customer). When omitted, uses project's default WhatsApp config.

Example:

"config-123abc"

​
variables
object

Variables to pass to the flow execution

Example:
{
  "user_id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}
​
context
object

Additional context for the execution

Example:
{
  "source": "mobile_app",
  "version": "1.2.3"
}
​
initial_data
object

Initial data to pass to the flow

Response

Flow execution accepted and queued

​
flow_id
string<uuid>

ID of the flow being executed

​
tracking_id
string<uuid>

Unique tracking ID for this execution request

​
message
string
Example:

"Flow execution queued"