Calls

Outbound Calls

Trigger an outbound voice call from one of your VoIP numbers.

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#

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,
    "idempotency_key": "crm-task-4815"
  }'

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#

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"
}

201 means LiveKit accepted the origination request. The endpoint does not wait for the destination to answer. Busy, no-answer, rejection, and trunk failures therefore normally arrive asynchronously: poll GET /v1/calls/{call_id} or subscribe to telephony.complete. A failed dial transitions the call to failed, releases its billing reservation, and reports a sanitized end_reason.

If the LiveKit submission response times out, ThunderPhone cannot safely know whether LiveKit accepted the call. The API returns 202 Accepted with the same call_id and "status": "unknown"; ThunderPhone then reconciles the deterministic room and SIP participant. It never treats that timeout as a definite failure or blindly originates a second call.

Idempotent retries#

Send idempotency_key when a client might retry POST /v1/call. The key is scoped to the organization and remains reserved for as long as the CallLog is retained. The request fingerprint covers the normalized from_number, to_number, agent_id, complete inline config, language override, and max_hold_seconds.

A replay of the same request returns 200 OK, the original call_id, and "idempotent_replay": true without originating a second call. Its status reflects the durable outcome: pending, unknown, initiated, in_progress, completed, or failed. Failed replays also include the stored sanitized failure_reason. Reusing a key with a different normalized request returns 409 Conflict.

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

Error responses#

Changelog#

• 2026-08-06: POST /v1/call now returns after origination is accepted instead of waiting for answer; ring failures finalize asynchronously. Added optional idempotency_key, durable dial-state reconciliation, and 202 status=unknown for ambiguous submission timeouts.

Outbound TCPA confirmation#

Before an organization's first outbound-enabling action, an organization admin must record a one-time confirmation that its outbound calling complies with applicable telemarketing/robocall law (including the TCPA). Until it exists, POST /v1/call and campaign creation/start reject with:

{
  "code":   "outbound_tcpa_confirmation_required",
  "detail": "Outbound calling requires a one-time TCPA compliance confirmation…"
}

with status 403. The confirmation is per organization and one-time — once recorded, it is never requested again. It applies only to organizations created on or after 2026-08-03; organizations that existed before then (and enterprise-agreement organizations) are fully exempt — GET /v1/outbound-tcpa-confirmation reports this as "gate_applies": false. The gate covers only originating outbound calls: inbound calls, live-call transfers, and campaigns that are already running are never affected.

GET returns:

{
  "text_version": "outbound-tcpa-v4-2026-08-03",
  "statement_en": "I confirm on behalf of my organization that its outbound calls through ThunderPhone will comply with applicable calling laws — the TCPA and FCC rules for U.S. calls, and the destination country's laws elsewhere.",
  "fcc_link_url": "https://www.ecfr.gov/current/title-47/chapter-I/subchapter-B/part-64/subpart-L/section-64.1200",
  "docs_link_url": "https://thunderphone.com/docs/guides/outbound-calling-laws",
  "gate_applies": true,
  "confirmed": false,
  "confirmation": null
}

POST takes { "accepted": true, "text_version": "…", "locale": "en", "rendered_text": "…" }. rendered_text must be exactly the canonical statement for the submitted text_version — the statement is server-pinned, and a mismatch returns 400. It is stored server-side as a SHA-256 hash, with the UI locale, confirming user + role, IP, and user agent, as the evidence record. text_version may be the current version from GET or any still-accepted earlier version (so a dialog fetched just before a statement update still submits cleanly, paired with that version's own statement text). Returns 201 (or 200 if the org is already confirmed — repeat confirms are idempotent).

Related#