Sign in

v1

latestOpenAPI 3.1.02026-07-22115189303.8 KB
Workflows

Start workflow execution

Start a new execution of a workflow asynchronously. The workflow will begin processing in the background.

You'll receive a 202 Accepted response with a tracking_id immediately. Use this tracking_id to:

  • Poll GET /workflow_executions with tracking_id filter to check status
  • Correlate execution events with your own systems

The execution will fail if:

  • The workflow is not in 'active' status
  • Required phone_number is missing or invalid
  • The workflow definition is malformed

Use cases:

  • Start workflow from external trigger (API, webhook, scheduled job)
  • Test workflow with specific initial variables
  • Retry failed execution with same parameters

Burst rate limit: This endpoint has an additional per-workflow burst limiter on top of the general platform API rate limits. The burst counter is scoped by API key and workflow ID and resets every second.

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

Successful responses include X-Burst-RateLimit-Limit and X-Burst-RateLimit-Remaining headers. If the burst limit is exceeded, the API returns 429 Too Many Requests with Retry-After: 1.

post/workflows/{workflow_id}/executions

Request body

Example request

{
  "workflow_execution": {
    "phone_number": "+14155552671",
    "variables": {
      "user_name": "Alice",
      "order_id": "ORD-12345",
      "priority": "high"
    },
    "context": {
      "source": "mobile_app",
      "campaign_id": "SUMMER2024"
    }
  }
}

Response

Workflow execution queued successfully (processing in background)

Example response

{
  "data": {
    "message": "Workflow execution initiated"
  }
}