Place a call

Your agent dials a person, speaks with its configured voice, works toward an objective, and records a transcript.

The request

curl -X POST https://klaw-voice.netlify.app/api/v1/calls \
  -H "Authorization: Bearer $KLAW_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-4821-attempt-1" \
  -d '{
    "agent_id": "AGENT_UUID",
    "to": "+14155550132",
    "objective": "Confirm Thursday appointment; offer to reschedule if needed.",
    "metadata": {"lead_id": "4821"},
    "callback_url": "https://example.com/hooks/call-done"
  }'

• agent_id and to (E.164) are required; everything else is optional.
• objective steers the conversation for this one call without editing the playbook.
• metadata (≤8 KB) rides along and comes back on events and call records.
• The Idempotency-Key header makes retries safe — same key, same call.

Response 201: {"call_id", "call_sid", "status", "polling_url", "transcript_url"}.

Watching it live

Poll GET /api/v1/calls/{id} (full record: status, transcript, summary, sentiment, intent) or GET /api/v1/calls/{id}/transcript for just the turns. Prefer push? Subscribe a webhook to call.ended / call.transcribed.

Guardrails

Outbound calling is capped at 5 concurrent and 50 calls/hour per account — see Rate limits. Calls to a person require their prior consent; you are responsible for complying with telemarketing law in your jurisdiction.

Quick proof-of-life

POST /api/agents/{id}/test-call {"phone": "+1..."} rings you (NANP numbers, 5/day) — the fastest way to hear a persona before pointing it at customers.