Quickstart

Place your first outbound call from the API in four steps — key, flow, call, result.

This is the shortest path from an API key to a phone ringing. Everything here runs against the public API, so it works the same from a terminal, a backend service, or an automation platform.

Note

You need a workspace with at least one flow and a wallet balance. Both are set up in the dashboard; this page assumes they exist.

Create an API key

Generate a key in your workspace settings. Every request carries it in the X-API-Key header — see Authentication for the details and for what the key is scoped to.

export KILEVEL_API_KEY="your-key-here"

Find the flow you want to run

Flows hold the conversation logic. List them and take the apiId of the one you want — that is the stable identifier to use in requests, not the numeric id.

curl -s https://api.kilevel.com/api/external/v1/flows \
  -H "X-API-Key: $KILEVEL_API_KEY"

{
  "content": [
    { "apiId": "f_sales_voice", "name": "Sales — outbound", "language": "en" }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1
}

Place the call

One request queues one outbound call session. rowData is merged into the conversation as variables the flow can reference; contextData is metadata that travels with the call and comes back on the result, which is where to put your own identifiers.

curl -s -X POST https://api.kilevel.com/api/external/v1/outbound/calls \
  -H "X-API-Key: $KILEVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowApiId": "f_sales_voice",
    "customerNumber": "+15551234567",
    "fromPhoneNumber": "+15557654321",
    "contactName": "Taylor Reed",
    "rowData": { "company": "Acme", "pipeline": "sales" },
    "contextData": { "crmLeadId": "lead_123" }
  }'

Omit flowApiId entirely and the call runs on your workspace's default manual-call flow. See Outbound calls for the inline flow variant, which lets you pass a one-off conversation without saving anything to the flow library.

Read the result

Calls are asynchronous — the request above returns once the session is queued, not once the conversation is over. Poll call history, or have an automation push the result to you.

curl -s "https://api.kilevel.com/api/external/v1/call-history?page=0&size=20" \
  -H "X-API-Key: $KILEVEL_API_KEY"

The row carries the transcript, the recording, the structured fields the flow was asked to extract, and the contextData you sent in.

Quickstart

What to read next