Create a call - CallingBox

{ "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "to_number": "<string>", "from_number": "<string>", "status": "queued", "direction": "outbound", "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

string

required

Phone number to call in E.164 format

Example:

"+15551234567"

prompt

string

default:Hello from CallingBox.

Instructions for the AI during the call

Example:

"Confirm dental appointment tomorrow at 2pm"

context

object

Arbitrary JSON context available to the AI during the call

Example:

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

returns

object

Schema defining what structured data to extract from the call. Keys are field names, values describe expected types.

Example:

{
  "confirmed": "boolean",
  "reschedule_to": "string"
}

language

string

default:en

Language code for the call (en, es)

Example:

"en"

from_number

string

Caller ID phone number in E.164 format. Must be an active number owned by the organization. If omitted, the organization's oldest active purchased number is used. The request fails if the organization has no active numbers.

Example:

"+15559876543"

webhook_url

string

Per-call inline webhook URL. Receives every lifecycle event for this call, signed with the organization's default signing secret. For account-wide fan-out across multiple calls, use POST /v1/webhook_endpoints instead.

Example:

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

Response

Call created successfully

string<uuid>

Unique call identifier

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

string

Call direction

Example:

"outbound"

prompt

string

The prompt used for the call

context

object

Context provided for the call

returns

object

Return schema defined for the 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

API Reference

Authorizations

Body

Response