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 belong to the account identified by {auth_id}.

Request body

Field	Type	Required	Description
`from`	string	yes	Account-owned caller ID in E.164 format (e.g. `+14155551234`).
`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` cannot be fetched successfully, such as a timeout or HTTP error.
`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`.
`status_callback_url`	string	no	URL called for ringing, answered, and hangup transitions.
`status_callback_method`	string	no	HTTP method for `status_callback_url`. Default: `POST`.
`webhook_secret`	string	no	Your per-account secret used to sign this call's POST requests to Answer, Fallback, Ring, Hangup, and Status URLs. It is write-only.
`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",
    "status_callback_url": "https://example.com/status",
    "webhook_secret": "replace-with-your-account-webhook-secret",
    "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. Webhook payloads identify the call with CallUUID; lifecycle status payloads also include RequestID.

Webhooks

Webhook	When
`ring_url`	Destination starts ringing.
`answer_url`	Call connects. Must return VoxML to control the call.
`fallback_url`	`answer_url` timed out or returned an HTTP error.
`hangup_url`	Call ends. Receives final timing, billing, and media-quality fields when available.

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` does not belong to the account, or URL `auth_id` doesn't match the authenticated account.
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 15 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