Dial

Originate outbound calls and check the status of in-progress dials. Dial creates a new voice session that your application controls just like an inbound session.

App authentication via X-App-ID and X-API-Key headers. The originated session is automatically owned by your app.

Create dial

Originate a new outbound call. Returns immediately with the new session_uuid; call progress is delivered via webhooks.

Request body

Field	Type	Required	Description
`to`	string	required	Destination number in Israeli domestic format (e.g. `0527121102`). Landline (02/03/04/08/09), mobile (050–055/058), or VoIP (072/073/074/076/077/079).
`from`	string	required	Caller ID number to present, in the same Israeli domestic format as `to`. Must be on your app’s allow-list.
`timeout_sec`	integer	optional	Ring timeout in seconds. Default 30, range 1–300.
`max_duration_sec`	integer	optional	Maximum total call duration in seconds. Default 3600, range 1–14400.
`metadata`	object	optional	Free-form key/value object echoed back on subsequent webhooks for this session.

Response — 202 Accepted

{
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "dialing"
}

POST /api/v1/dial

curl -X POST https://gateway.example.com/api/v1/dial \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "0527121102", "from": "0721234567", "timeout_sec": 30}'

Triggered webhooks

session.dialing — gateway has begun dialing.
session.ringing — far end is ringing.
session.early_media — optional; early audio is flowing. NOT the same as answer.
call.answered — called party picked up (true answer).
call.hangup — call ended (success or failure carries hangup_cause).

Error responses

Status	Condition
`400`	Missing `to`, invalid number format, or `timeout_sec` / `max_duration_sec` out of range.
`401`	Missing or invalid auth.
`403`	`from` is not on this app’s caller-ID allow-list (`cid_not_allowed`).
`429`	Rate limit exceeded.
`500`	Internal gateway error.
`503`	No outbound capacity available right now (`no_fs_capacity`). Retry with backoff.

See the Rate limits guide for cooldown windows and 429 retry semantics.

Get dial status

Look up the current status of a dial originated by your app.

Response

{
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ringing",
  "started_at": "2026-05-06T12:34:56Z"
}

status is one of dialing, ringing, early_media, answered, ended. started_at is the dial creation time in ISO-8601 (RFC 3339) UTC.

Error responses

Status	Condition
`401`	Missing or invalid auth.
`404`	Dial UUID not found or not owned by your app.