Calls API
Queue outbound calls and retrieve call records with your sk_live_ API key. All routes require Authorization: Bearer sk_live_...
POST /v1/calls/outbound
Creates an outbound call, resolves the agent, checks minute quota, emits call.queued, and attempts telephony dispatch when configured.
curl -X POST https://voxbridge.cc/v1/calls/outbound \
-H "Authorization: Bearer sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"from": "+15559876543",
"agent_id": null,
"client_name": "Jane Doe",
"context": {
"reference_number": "398690",
"product": "personal_loan"
},
"metadata": {
"crm_id": "lead_8821"
},
"schedule_at": null,
"webhook_url": "https://partner.example/hooks/voice",
"max_attempts": 3
}'
Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Destination phone (E.164 preferred; US 10-digit normalized to +1) |
from | string | No | Caller ID; required once live telephony is enabled |
agent_id | UUID | No | Outbound agent; defaults to org is_default agent |
client_name | string | No | Callee name for prompts and records |
context | object | No | Variables injected into agent system prompt |
metadata | object | No | Opaque data echoed in webhooks and stored on call |
schedule_at | datetime | No | UTC schedule time; defaults to now |
webhook_url | string | No | Per-call webhook override |
max_attempts | integer | No | Retry cap (1–10, default 3) |
Response
HTTP 201 Created with a CallOut object:
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"agent_id": "...",
"direction": "outbound",
"status": "queued",
"to_number": "+15551234567",
"from_number": null,
"client_name": "Jane Doe",
"context": { "reference_number": "398690" },
"metadata": { "crm_id": "lead_8821" },
"disposition": null,
"transcript": null,
"recording_url": null,
"structured_answers": null,
"attempt_count": 0,
"max_attempts": 3,
"duration_seconds": null,
"scheduled_at": "2026-06-01T14:00:00Z",
"started_at": null,
"completed_at": null,
"created_at": "2026-06-01T14:00:01Z"
}
Errors
400— No default agent configured401— Invalid or missing API key402— Monthly minute limit reached404—agent_idnot found or inactive422— Validation failure (phone length, etc.)
GET /v1/calls
List calls for the authenticated organization, newest first.
curl "https://voxbridge.cc/v1/calls?status=queued&limit=25&offset=0" \
-H "Authorization: Bearer sk_live_YOUR_KEY"
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status: queued, calling, completed, failed, etc. |
limit | integer | 25 | Page size (1–100) |
offset | integer | 0 | Pagination offset |
Response wrapper:
{
"items": [ /* CallOut[] */ ],
"total": 142,
"limit": 25,
"offset": 0
}
GET /v1/calls/{call_id}
Fetch a single call by UUID. Returns 404 if the call belongs to another organization.
curl https://voxbridge.cc/v1/calls/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
-H "Authorization: Bearer sk_live_YOUR_KEY"
Call status lifecycle
| Status | Meaning |
|---|---|
queued | Accepted by API; awaiting dialer |
calling | Media/SIP session active |
completed | Call finished successfully |
failed | Dial or agent error (error_message set) |