Originate outbound call
Start an outbound call and return its new session_uuid after the
request is admitted. A 202 Accepted response confirms only admission; it
does not confirm that the destination rang or answered. Call progress and
completion are reported through webhooks.
Triggered webhooks:
session.created, session.ringing_started, session.answered, and
session.ended. The optional session.early_media_started event reports early media.
See Session lifecycle events for complete payload schemas and examples.
Authentication
Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.
Headers
Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.
Request
Caller ID to present, in the same E.164 format with leading + as to (e.g. +972500000000).
The schema validates canonical syntax only. Runtime country policy must support
the number, and it must be on the app’s caller-ID allow-list or match the
caller ID of a live inbound phone Session supplied in caller_id_session_uuid.
An unauthorized value is rejected with 403 forbidden (no call is placed,
no webhooks fire). Branch on the response code, not the human message.
The platform does not substitute a default caller ID; an SDK MAY catch
403 forbidden for this operation and retry with its own configured approved default.
Pre-answer ring timeout in seconds, measured from when the outbound session is created, before the dial command is dispatched. It is NOT measured from
when the destination phone starts ringing. Call setup and routing consume
part of this budget, so the callee experiences less ring time than the value
set here. On expiry the dial ends with session.ended (answered=false,
hangup_cause=“timeout”). Distinct from max_duration_sec, the post-answer cap.
Destination number in international E.164 format with leading + (e.g. +972500000000).
The schema validates canonical syntax only. Runtime country and trunk policies
determine whether the destination is currently dialable; an unsupported
destination is rejected with 400 invalid_request.
Live inbound phone Session from this app whose caller ID exactly matches from.
Use this eligible outbound trunk instead of automatic lowest-price selection.
Response headers
Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.