API ReferenceCalls

Initiate an outbound call

Starts an outbound call. Returns `201` with the `Call` object. The `status` field tells you which path served the request: - `initiated` — the call was dialed synchronously (default). - `queued` — outbound calls are paced through the carrier-safe priority lane (the platform stays within per-carrier rate limits); the call dials as soon as the carrier has headroom. The response is immediate; you learn the live outcome from the `call.*` webhooks you already receive (`call.initiated`, `call.completed`, …). Either way the response shape is identical and the returned `call_id` is immediately queryable via `GET /v1/calls/{call_id}`. A `queued` call carries no `mno`/`started_at` yet — those land once it dials.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
agent_idstringRequired
from_numberstringRequired
to_numberstringRequired
webhook_urlstringOptional

Response

Call accepted. status is initiated (dialed synchronously) or queued (accepted onto the paced priority lane; dials when the carrier has headroom — outcome via call.* webhooks).

call_idstring
agent_idstring
from_numberstring
to_numberstring
directionenum
statusenum
mnostring
quality_mosdouble1-5

Mean Opinion Score (1.0-5.0) for voice quality. Estimated from RTP statistics (jitter, packet loss, RTT). Null if call did not complete.

resolutionenum

AI-classified call outcome. Null if not yet classified.

classified_atdatetime
Timestamp when the call outcome was classified by AI.
recording_urlstring

URL to download the call recording (audio/wav). Null if recording was not enabled or the caller opted out.

started_atdatetime
ended_atdatetime
Timestamp when the call ended. Omitted while the call is in progress.
duration_secondsinteger

Call duration in seconds. Omitted while the call is in progress (or for a 0-second call).

cost_minorlong

Per-call charge in minor currency units (e.g. kobo). Omitted until the call is billed; a present 0 means no charge.

currencystring

ISO 4217 currency code paired with cost_minor (e.g. NGN). Omitted when there is no cost.