Authentication

All API requests require a Bearer token. Get your API key from the dashboard after signing up.

Authorization: Bearer an_live_<your_key>

Quick Start

Three steps to give your agent a phone number:

1. 1

   Sign up and create an API key

   Sign up at /signup, then create an API key in the dashboard.

2. 2

   Add credits
   POST /credits/purchase

   {
     "amount_cents": 1000
   }

   $5 per number, $0.05/min outbound, $0.03/min inbound.

3. 3

   Provision a phone number

   Option A: Managed mode — just provide a system prompt, no server needed:

   POST /numbers (managed)

   {
     "system_prompt": "You are a helpful sales assistant for Acme Corp.",
     "first_message": "Hello, how can I help you?",
     "area_code": "415"
   }

   Option B: Webhook mode — route calls to your own server for full control:

   POST /numbers (webhook)

   {
     "webhook_url": "https://your-agent.com/voice",
     "area_code": "415"
   }

Webhook Format

Your webhook_url receives POST requests in OpenAI-compatible chat completions format:

{
  "model": "custom",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hi, I'd like to schedule an appointment." }
  ],
  "stream": true
}

Respond with SSE-streamed chat completion chunks. The text is spoken back via TTS.

data: {"choices":[{"delta":{"content":"Sure, I can"}}]}

data: {"choices":[{"delta":{"content":" help with that."}}]}

data: [DONE]

Numbers API

{
  "system_prompt": "You are a helpful assistant.",
  "webhook_url": "https://your-agent.com/voice",
  "area_code": "415",
  "voice_id": "cgSgspJ2msm6clMCkdW9",
  "first_message": "Hello!",
  "inbound_mode": "autopilot",
  "metadata": {}
}

Calls API

{
  "from": "num_a1b2c3d4e5f6",
  "to": "+15551234567",
  "metadata": {}
}

SMS API

{
  "from": "num_a1b2c3d4e5f6",
  "to": "+15551234567",
  "body": "Hello from my agent!",
  "metadata": {}
}

Credits API

Webhooks API

Register webhooks to receive events. Payloads are HMAC-signed.

Error Format

{
  "success": false,
  "error": {
    "message": "Insufficient credits.",
    "code": "insufficient_credits"
  }
}