Place an Outbound Call
POST /api/v1/calls — dial out through an already-configured phone configuration.
Places a real outbound call through a phone configuration you've already set up in Studio (see Providers). The response doesn't arrive until the call is answered, fails, or times out — there's no separate status-polling endpoint.
POST /api/v1/callsRequires an outbound phone configuration
trunkId must reference a phone configuration that's direction: outbound, status: active, and
has finished provisioning. Trunk creation and provisioning happen in Studio, not via this API —
see Providers.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
trunkId | string (UUID) | Yes | The outbound phone configuration to call through. Must belong to your organization (and, for a project-scoped key, your project). |
to | string | Yes | Destination number, E.164 or digits-only. |
phoneNumberId | string (UUID) | Yes | Which caller-ID number on the trunk to dial from. It must have a voice configuration bound to it — that's what tells the agent how to speak. |
Response
201 Created:
{
"roomName": "elizon-call-8f2a1c9e-...",
"sipCallId": "d290f1ee-...",
"to": "+15551234567",
"from": "+15557654321",
"trunkId": "3f9c1a2e-..."
}Errors
| Status | error | When |
|---|---|---|
400 | validation error | Request body fails validation |
400 | wrong_direction | trunkId refers to an inbound trunk |
400 | trunk_not_provisioned | The trunk hasn't finished provisioning yet |
400 | phone_number_missing_voice_config | phoneNumberId has no voice configuration bound to it |
403 | forbidden | trunkId doesn't belong to your organization/project |
403 | budget_required | Your organization has no voice_minutes budget configured — see below |
429 | budget_exceeded | Your configured voice_minutes budget for this call's scope is exhausted |
502 | call_failed | The carrier rejected the call (busy, no answer, invalid number) — the message has the detail |
A voice_minutes budget is required
Unlike starting a voice session, placing an outbound call over the public API requires your
organization to have a voice_minutes budget configured (Settings → Budgets) before any call can
be placed at all — there's no "unlimited by default" option here. This is a deliberate guardrail:
an outbound, pay-per-minute dial-out with no cap is a real fraud-risk surface for a
third-party-callable endpoint.
Example
curl -X POST https://api.elizon.com/api/v1/calls \
-H "X-API-Key: elz_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"trunkId": "3f9c1a2e-...",
"to": "+15551234567",
"phoneNumberId": "8b1e4a2f-..."
}'