Skip to main content
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

MethodPathDescription
POST/v1/callPlace 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
  }'

​
Request fields

FieldTypeRequiredDescription
from_numberstringyesE.164. Must be a number owned by this org (VoIP-backed)
to_numberstringyesE.164 target
agent_idintegersee belowAn agent id in this org
configobjectsee belowInline config — schema matches the call.incoming webhook response
max_hold_secondsintegernoOverride the agent’s hold timeout for this call only
Exactly one of:
  1. agent_id — use the saved configuration.
  2. config — inline a one-off configuration (same shape as a call.incoming webhook response).
  3. 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"
}
FieldTypeDescription
call_idintegerAssigned id — use it on the call endpoints to follow the call.
statusstringAlways "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 statusMeaning
in_progressSIP dialing or connected
completedCall ended normally
failedCall could not be established (trial-mode, unverified number, provider error)

​
Error responses

StatusBody code/detail hintMeaning
400from_number and to_number are requiredMissing required fields
400Provide either agent_id or config, not bothBoth supplied
402Insufficient balanceOrg balance is ≤ $0.00. Top up first
403Outbound blocked (demo number, unverified VoIP, trial restriction)See message for specifics
404from_number is not registered to this organization
404Agent not foundagent_id invalid or wrong org
502Upstream SIP / LiveKit failureTransient; 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.