Call resource

A Call represents a single phone call — outbound when you create it with a request, or inbound when a number assigned to your application receives one. Outbound calls are placed with a single POST /v1/calls; inbound calls reach your answer_url, which returns a JSON call-control document telling Connect what to do next. While a call is live you can fetch its state, list past calls with filters, or update it to redirect or hang up.

IllustrativeThe capabilities here — placing and receiving calls, answering-machine detection, alternate-number failover and caller-ID/DID rotation — are real and shipping in TelVox Dial. The public REST shapes, field names and enums are developer preview and may change before GA. Base URL: https://api.telvox.dev.

Properties

Fields marked PII carry personal data and are subject to your retention and masking policy.

Property	Type	Description
sid	string	Unique identifier for the call, prefixed CA.
object	string	Always "call".
from	string	Caller ID in E.164 — the number presented to the far end. May rotate when DID rotation is enabled.
to	string	Destination in E.164, a SIP URI, or a client identifier for a WebRTC endpoint. PII.
direction	enum	outbound-api, outbound-dial, or inbound.
status	enum	Current lifecycle state — see the status enum below.
answer_url	string	Your endpoint that returns a JSON call-control document when the call is answered.
status_callback	string	Your endpoint that receives lifecycle event callbacks.
duration	integer	Billable call duration in seconds. Null until the call completes.
answered_by	enum	When answering-machine detection runs: human, machine_start, machine_end, fax, or unknown.
price	string	Usage cost for the call. Null until rated; reported in your account currency.
created_at	string	ISO 8601 timestamp the call resource was created.

Status enum

The status field moves through these states. Terminal states (completed, busy, no-answer, failed, canceled) end the call.

Value	Type	Description
queued	status	The call is accepted and waiting to be placed.
initiated	status	The call is being placed to the carrier.
ringing	status	The destination is ringing.
in-progress	status	The call was answered and is connected.
completed	status	The call ended normally after being answered.
busy	status	The destination returned busy.
no-answer	status	The call rang but was never answered.
failed	status	The call could not be completed (network or carrier error).
canceled	status	The call was canceled before it was answered.

Create a call

Place an outbound call. On answer, Connect fetches your answer_url and runs the returned call-control document.

POST/v1/calls

Place an outbound call from your number to a destination.

Parameter	Type	Description
fromrequired	string	Caller ID to present, in E.164. Must be a number assigned to your account or a verified caller ID.
torequired	string	Destination in E.164, a SIP URI (sip:…), or a WebRTC client identifier (client:…).
answer_urlrequired	string	HTTPS endpoint that returns a JSON call-control document when the call is answered. Required unless answer_document is supplied.
answer_document	object	Inline JSON call-control document to run on answer, in place of answer_url.
status_callback	string	HTTPS endpoint to receive lifecycle event callbacks.
status_callback_events	array	Which events to deliver: initiated, ringing, answered, completed. Defaults to completed.
machine_detection	enum	Enable answering-machine detection: none, detect, or detect_message_end.
timeout	integer	Seconds to let the destination ring before giving up. Defaults to 60.
record	boolean	Record the call from answer. See the Recording resource for retrieval.

POST/v1/calls

illustrative

# illustrative — shape may differ at GA
curl https://api.telvox.dev/v1/calls \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d from="+14155550100" \
  -d to="+14155550199" \
  -d answer_url="https://your.app/voice/answer" \
  -d status_callback="https://your.app/voice/status" \
  -d status_callback_events="ringing" \
  -d status_callback_events="answered" \
  -d status_callback_events="completed"

201 createdqueued

201 response

illustrative

// illustrative — shape may differ at GA
{
  "object": "call",
  "sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "from": "+14155550100",
  "to": "+14155550199",
  "direction": "outbound-api",
  "status": "queued",
  "answer_url": "https://your.app/voice/answer",
  "status_callback": "https://your.app/voice/status",
  "duration": null,
  "answered_by": null,
  "price": null,
  "created_at": "2026-06-22T17:04:11Z"
}

201 created

Fetch a call

Retrieve a single call by its SID, including live status while it is in progress.

GET/v1/calls/{sid}

Fetch one call by its SID.

GET/v1/calls/{sid}

illustrative

# illustrative — shape may differ at GA
curl https://api.telvox.dev/v1/calls/CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4 \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

200 response

illustrative

// illustrative — shape may differ at GA
{
  "object": "call",
  "sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "from": "+14155550100",
  "to": "+14155550199",
  "direction": "outbound-api",
  "status": "completed",
  "duration": 47,
  "answered_by": "human",
  "price": "0.0094",
  "created_at": "2026-06-22T17:04:11Z"
}

200 ok

List calls

Return a paginated list of calls, newest first, narrowed by the filters below. See pagination for cursoring.

GET/v1/calls

List calls with optional filters and pagination.

Query	Type	Description
to	string	Return only calls to this number (E.164).
from	string	Return only calls from this caller ID (E.164).
status	enum	Filter by call status, e.g. completed or in-progress.
start_time_after	string	Return calls that started on or after this ISO 8601 timestamp.
start_time_before	string	Return calls that started on or before this ISO 8601 timestamp.
limit	integer	Page size, 1–100. Defaults to 50.
starting_after	string	Cursor — a call SID to page forward from.

GET/v1/calls

illustrative

# illustrative — shape may differ at GA
curl "https://api.telvox.dev/v1/calls?status=completed&limit=25" \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

200 response

illustrative

// illustrative — shape may differ at GA
{
  "object": "list",
  "url": "/v1/calls",
  "has_more": true,
  "next_cursor": "CA7d2c…",
  "data": [
    {
      "object": "call",
      "sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
      "to": "+14155550199",
      "status": "completed",
      "duration": 47
    }
  ]
}

200 ok

Update a call

Modify a call that is in progress — redirect it to a new call-control document, or end it.

POST/v1/calls/{sid}

Redirect a live call to a new document, or hang it up.

Parameter	Type	Description
status	enum	Set to "completed" to hang up an in-progress call immediately, or "canceled" to cancel a call that has not yet been answered.
redirect_url	string	HTTPS endpoint returning a new call-control document. The live call is redirected to run it, interrupting the current instruction.

POST/v1/calls/{sid}

illustrative

# illustrative — redirect a live call to a new document
curl https://api.telvox.dev/v1/calls/CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4 \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d redirect_url="https://your.app/voice/transfer"

200 okin-progress

200 response

illustrative

// illustrative — shape may differ at GA
{
  "object": "call",
  "sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "status": "in-progress",
  "direction": "outbound-api"
}

200 ok

StatusCallback events

If you set status_callback when creating a call, Connect POSTs to that URL as the call moves through its lifecycle. Subscribe to specific events with status_callback_events; respond 2xx promptly. Delivery is over the same signed, SSRF-safe egress that powers Dial — see webhooks & callbacks for signature verification.

Event	Fires when
initiated	The call leaves the queue and is being placed to the carrier.
ringing	The destination starts ringing.
answered	The call is answered and connected.
completed	The call ends — includes final duration and price.

Callback payload

POSTyour status_callback

illustrative

// illustrative — POST body delivered to your status_callback
{
  "call_sid": "CA8f0e1d7c4b2a9f6e3d0c1b8a7f6e5d4",
  "event": "answered",
  "status": "in-progress",
  "from": "+14155550100",
  "to": "+14155550199",
  "answered_by": "human",
  "timestamp": "2026-06-22T17:04:19Z"
}

deliver to your endpointanswered

Field	Type	Description
call_sid	string	The SID of the call this event is about.
event	enum	The lifecycle event: initiated, ringing, answered, or completed.
status	enum	The call status at the moment of the event.
from	string	Caller ID presented on the call (E.164).
to	string	Destination of the call (E.164 / SIP / client). PII.
timestamp	string	ISO 8601 time the event fired.
duration	integer	Present on completed — billable seconds.
answered_by	enum	Present when machine detection ran — human, machine_start, etc.