Make an outbound phone call

Have an agent dial a single recipient over the phone.

An outbound call has the agent dial a phone number over SIP instead of a browser joining a room. This guide places one call from your backend; to dial many recipients, run a voice campaign instead.

Prerequisites

• A published voice agent.
• A workspace API key with sessions:write.
• An outbound SIP trunk configured on the deployment. Without it, the dial step fails.
• The recipient’s number in E.164 format, e.g. [phone].

Place the call

POST /calls fires one outbound call with an API key alone — no human, no login:

curl -X POST "$LEHAR_BASE_URL/calls" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_sales_hi",
    "to_number": "[phone]",
    "callee_name": "Jane",
    "custom_variables": { "company": "Acme" },
    "idempotency_key": "crm-lead-8821"
  }'

You get back a call record with status: "queued". Accepting the call is asynchronous — it may be waiting for a calling window or a free concurrency slot before it dials. Add call_config to control retries, the calling window and idle timeouts; see Calls for the full contract.

Always send an idempotency_key. If you never see the response, retrying with the same key returns 409 instead of dialling the person twice.

Get the result

Poll the call until it reaches a terminal status, then read the session behind it:

curl "$LEHAR_BASE_URL/calls/$CALL_ID" -H "X-API-KEY: $LEHAR_API_KEY"

status progresses queued → dialing → in_progress → completed / failed / cancelled, and attempts lists one session per dial — transcript and usage hang off those. In production, register an outbound webhook and receive call_completed instead of polling.

Calling from the dashboard instead

POST /sessions with call_type: "outbound_phone" also dials a number, but it requires a bearer login session and a human user — it’s what the dashboard uses. Prefer POST /calls for anything server-to-server; it is the only path with retries, calling windows and idempotency.

On a phone session you don’t connect the returned participant_token — the human is on the phone leg, so the token is subscribe-only.

Notes & gotchas

• E.164 always — include the country code on every number.
• Stored numbers are masked in session metadata and logs (first char + *** + last 4).
• Dialing outcomes (busy, no-answer, declined) are classified from the SIP result — the same classification campaigns use to decide retries.
• Refused before it dials — a workspace with a negative balance gets 402 insufficient_credits, and where the deployment restricts destinations, a number outside the allowed prefixes gets 400 invalid_request. Neither creates a call record. See the Calls error table.

Calls

The full POST /calls contract.

Run your first campaign

Dial many recipients with retries.