Make a Call

Initiate an outbound voice call. The call dials asynchronously; the response returns as soon as TryVox queues the request.

Endpoint

POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls

Prerequisite

The from number must be a verified caller ID on the account identified by {auth_id}. The API rejects unverified from numbers with 403 FORBIDDEN before placing the call.

Request body

Field	Type	Required	Description
`from`	string	yes	Caller ID in E.164 format (e.g. `+14155551234`). Must be a verified caller ID.
`to`	string	yes	Destination number in E.164 format.
`answer_url`	string	yes	URL TryVox `POST`s when the call answers. Must return VoxML.
`answer_method`	string	no	HTTP method for `answer_url`. Default: `POST`.
`fallback_url`	string	no	URL used if `answer_url` fails (timeout, 5xx, invalid VoxML).
`fallback_method`	string	no	HTTP method for `fallback_url`. Default: `POST`.
`ring_url`	string	no	URL called once the destination starts ringing.
`ring_method`	string	no	HTTP method for `ring_url`. Default: `POST`.
`hangup_url`	string	no	URL called once the call ends, with the final CDR.
`hangup_method`	string	no	HTTP method for `hangup_url`. Default: `POST`.
`caller_name`	string	no	Display name to send as caller-name where the carrier supports CNAM. Free-form text.
`ring_timeout`	integer	no	Ring timeout in seconds. Default: `60`.
`time_limit`	integer	no	Hard maximum call duration in seconds. Default: `14400` (4 hours).
`machine_detection`	string	no	`Enable` or `Disable` answering-machine detection. Default: `Disable`.

Bulk calls

The same endpoint also accepts a bulk request — pass an array of single-call bodies:

{
  "calls": [
    {"from": "+14155551234", "to": "+14155556789", "answer_url": "https://your-app.com/answer"},
    {"from": "+14155551234", "to": "+14155556790", "answer_url": "https://your-app.com/answer"}
  ]
}

The response wraps each created call in a calls array, omitting any that failed validation. Per-tenant bulk size is capped (contact support to raise).

Example request

curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155556789",
    "answer_url": "https://example.com/answer",
    "ring_url": "https://example.com/ringing",
    "hangup_url": "https://example.com/hangup",
    "ring_timeout": 30,
    "time_limit": 3600,
    "machine_detection": "Enable"
  }'

Response

201 Created:

{
  "data": {
    "request_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "TJab12cd34",
    "auth_id": "TJab12cd34",
    "from": "+14155551234",
    "to": "+14155556789",
    "direction": "outbound",
    "status": "queued",
    "start_time": "2026-04-09T10:30:00Z",
    "duration": 0,
    "billsec": 0
  }
}

request_uuid is the stable identifier for the call. Use it on Get Call, Hangup, and Call Actions. It also appears as RequestID on every webhook payload for this call's lifecycle.

Webhooks

Webhook	When
`ring_url`	Destination starts ringing.
`answer_url`	Call connects. Must return VoxML to control the call.
`fallback_url`	`answer_url` failed after retries.
`hangup_url`	Call ends. Receives the full CDR (`cost`, `currency`, `mos`, `jitter`, `packet_loss`, `hangup_cause`, etc.).

For account-level subscriptions to all call.* events, see Webhook Subscriptions.

Errors

Status	Code	Reason
400	`VALIDATION_FAILED`	Missing required field, `to`/`from` not E.164
401	`INVALID_CREDENTIALS`	Auth ID / Auth Token bad
403	`FORBIDDEN`	`from` not a verified caller ID, or URL `auth_id` doesn't match key
502	`NO_CARRIER_AVAILABLE`	No active carrier covers the destination

Notes

Phone numbers must be in E.164 format (e.g. +14155551234).
The answer_url must be publicly reachable and respond with valid VoxML within 5 seconds.
Machine detection adds 1–3 seconds to call connection time and may be charged at a premium rate depending on plan.
The response field is request_uuid, not call_uuid — there is no separate call UUID today.

Make a Call

On this page