Outbound Calls

Place an outbound call from one of your own phone numbers to a target number. You can reference a saved agent by id, or inline a one-off configuration for this call only.

Endpoint

Method	Path	Description
`POST`	`/v1/call`	Place an outbound call

Outbound calling requires the from_number to be a number you own through a VoIP connection. Demo numbers provisioned by ThunderPhone are inbound-only.

Place a call

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt": "You are calling on behalf of Acme to confirm…",
      "voice":  "john",
      "product": "spark",
      "tools": []
    }
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/call",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "from_number": "+15551234567",
        "to_number":   "+14155550199",
        "agent_id":    12,
    },
).json()

Request fields

Field	Type	Required	Description
`from_number`	string	yes	E.164. Must be a number owned by this org (VoIP-backed)
`to_number`	string	yes	E.164 target
`agent_id`	integer	see below	An agent id in this org
`config`	object	see below	Inline config — schema matches the `call.incoming` webhook response
`max_hold_seconds`	integer	no	Override the agent’s hold timeout for this call only

Exactly one of:

agent_id — use the saved configuration.
config — inline a one-off configuration (same shape as a call.incoming webhook response).
Neither — the call uses the number’s configured outbound_agent. Fails with 400 if no outbound agent is set.

Response

Returns 201 Created:

{
  "call_id": 987654321,
  "status":  "initiated"
}

Field	Type	Description
`call_id`	integer	Assigned id — use it on the call endpoints to follow the call.
`status`	string	Always `"initiated"` on success. This is the initiation status, not the call state machine; poll `GET /v1/calls/{call_id}` for the live `status` (`in_progress` → `completed`/`failed`).

Poll GET /v1/calls/{call_id} to observe state transitions:

Live `status`	Meaning
`in_progress`	SIP dialing or connected
`completed`	Call ended normally
`failed`	Call could not be established (trial-mode, unverified number, provider error)

Error responses

Status	Body `code`/`detail` hint	Meaning
`400`	`from_number and to_number are required`	Missing required fields
`400`	`Provide either agent_id or config, not both`	Both supplied
`402`	Insufficient balance	Org balance is ≤ $0.00. Top up first
`403`	Outbound blocked (demo number, unverified VoIP, trial restriction)	See message for specifics
`404`	`from_number is not registered to this organization`
`404`	`Agent not found`	`agent_id` invalid or wrong org
`502`	Upstream SIP / LiveKit failure	Transient; safe to retry

Make sure your account has enough balance. Calls block at <= $0.00 (402). See Billing → Top up.

Agents

Configure the prompt, voice, and tools for outbound calls.

VoIP Connections

Set up the VoIP provider credentials that back outbound calls.

Calls

Observe the call as it runs and inspect the transcript afterward.

Billing

Keep your prepaid balance topped up so outbound calls can place.

Overview

Organizations

Agents

Phone Numbers

Calls

Billing

Developer

Endpoint

Place a call

Request fields

Response

Error responses

Agents

VoIP Connections

Calls

Billing

​Endpoint

​Place a call

​Request fields

​Response

​Error responses

​Related

Agents

VoIP Connections

Calls

Billing

Endpoint

Place a call

Request fields

Response

Error responses

Related