Dispatch an outbound call from an agent

curl --request POST \ --url https://api.callingbox.io/v1/calls \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data @- <<EOF { "agent_id": "b5a1c9f2-6d2d-4a7f-9f3a-5a2b1c3d4e5f", "to": "+15551234567", "instructions": "Confirm the patient's appointment tomorrow at 2pm. If they want to reschedule, ask for a preferred date and time.", "context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" } } EOF

{ "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "to_number": "<string>", "from_number": "<string>", "direction": "outbound", "persona": "<string>", "instructions": "<string>", "prompt": "<string>", "context": {}, "returns": {}, "result": {}, "result_status": "completed", "result_error": "<string>", "language": "<string>", "webhook_url": "<string>", "webhook_status": "delivered", "webhook_error": "<string>", "created_at": "2023-11-07T05:31:56Z", "started_at": "2023-11-07T05:31:56Z", "answered_at": "2023-11-07T05:31:56Z", "ended_at": "2023-11-07T05:31:56Z", "duration_seconds": 123, "billed_duration_seconds": 123, "billing_amount_milli_cents": 123, "reservation_status": "settled", "error_code": "<string>", "error_message": "<string>", "hangup_cause": "<string>", "metadata": {}, "updated_at": "2023-11-07T05:31:56Z" }

Authorizations

Authorization

string

header

default:sk_live_your_api_key

required

API key starting with sk_

Body

application/json

Request body for POST /v1/calls. Agent-centric: persona, voice, language, returns, tools, voicemail behavior, and the default webhook all come from the referenced outbound agent. Only a small set of fields can be overridden per call.

agent_id

string<uuid>

required

Id of the outbound agent to run for this call. The agent's type must be outbound.

Example:

"b5a1c9f2-6d2d-4a7f-9f3a-5a2b1c3d4e5f"

string

required

Phone number to call in E.164 format.

Example:

"+15551234567"

from_number

string

Caller ID override. Must be another number attached to this agent. If omitted, the agent's primary_number_id is used.

Example:

"+15557654321"

instructions

string

Per-call instructions. When present, wholly replaces the agent's default instructions for this call (replace semantics, not merge).

Example:

"Confirm the patient's appointment tomorrow at 2pm."

context

object

Arbitrary JSON context available to the agent during the call.

Example:

{
  "patient": "Maria Lopez",
  "doctor": "Dr. Chen"
}

webhook_url

string

Per-call webhook override. If omitted, the agent's webhook_url is used. For account-wide fan-out across multiple calls, register endpoints via POST /v1/webhook_endpoints instead.

Example:

"https://your-server.com/callingbox-webhook"

metadata

object

Arbitrary key/value metadata you can read back off the call record.

Response

Call created successfully

string<uuid>

Unique call identifier.

agent_id

string<uuid> | null

The agent that handled the call. Null for legacy calls created before agents existed.

to_number

string

Destination phone number.

from_number

string

Caller ID phone number.

status

enum<string>

Available options:

queued,

initiated,

ringing,

in_progress,

completed,

no_answer,

busy,

canceled,

failed

direction

enum<string>

outbound for calls dispatched via POST /v1/calls; inbound for calls answered by an inbound agent.

Available options:

inbound,

outbound

Example:

"outbound"

persona

string | null

Snapshot of the agent's persona at the time this call ran.

instructions

string | null

Snapshot of the instructions used for this call (per-call override on outbound, otherwise the agent's default).

prompt

string

Rendered system prompt for this call, derived from the agent's persona plus instructions. Treat this as read-only call history, not a request field.

context

object

Context provided for this call.

returns

object

Snapshot of the agent's returns schema used for this call.

result

object

Structured data extracted from the call, matching the returns schema

result_status

string

Extraction status: pending, completed, or failed

Example:

"completed"

result_error

string | null

Error message if extraction failed

language

string

Language code

webhook_url

string | null

Webhook endpoint URL

webhook_status

string

Webhook delivery status: pending, delivered, or failed

Example:

"delivered"

webhook_error

string | null

Error message if webhook delivery failed

created_at

string<date-time>

When the call was created

started_at

string<date-time> | null

When the call started ringing

answered_at

string<date-time> | null

When the callee answered

ended_at

string<date-time> | null

When the call ended

duration_seconds

integer | null

Total call duration in seconds

billed_duration_seconds

integer | null

Billable connected time in seconds

billing_amount_milli_cents

integer | null

Amount billed in milli-cents

reservation_status

string

Credit reservation status: reserved, settled, or released

Example:

"settled"

error_code

string | null

Error code from the telephony provider

error_message

string | null

Human-readable error description

hangup_cause

string | null

Telephony-level hangup reason

metadata

object

Arbitrary metadata associated with the call

updated_at

string<date-time>

Last update timestamp