---
title: "Start a call"
method: POST
path: "/v1/calls"
tags: ["Call control"]
---

# Start a call

`POST /v1/calls`

Places an outbound call. Returns the call with its `uuid` for tracking and control.

## Request body

- CallRequest
  - `from` string, required — Caller ID. Must be an active or verified phone number on the account.
  - `to` string, required — Destination number in E.164 format
  - `callback_url` string, required — The callback URL where Wavix sends the call status updates
  - `recording` boolean — Specifies whether to record the call
  - `voicemail_detection` boolean — Specifies whether the AMD is turned on for the call
  - `tag` string — Call metadata
  - `timeout` integer — The ring timeout, in seconds, before the call is considered unanswered.

## Response `200`

Returns the created call.

- CallCreateResponse
  - `uuid` string, uuid — Call ID. Deprecated — use `id` instead.
  - `id` string, uuid — Call ID. Alias of `uuid`.
  - `direction` 'inbound' | 'outbound' — Direction of the call. One of `inbound` (call received by the account) or `outbound` (call placed by the account).
  - `event_type` 'call_setup' | 'ringing' | 'early_media' | 'answered' | 'completed' | 'busy' | 'cancelled' | 'rejected' | 'on_call_event' — Most recent lifecycle event for the call. One of: - `call_setup` — the call is being initiated. - `ringing` — the destination is ringing. - `early_media` — early media (such as ringback) is playing before answer. - `answered` — the destination answered the call. - `completed` — the call ended normally. - `busy` — the destination was busy. - `cancelled` — the call was cancelled before answer. - `rejected` — the destination rejected the call. - `on_call_event` — an in-call event occurred (see `event_payload`).
  - `event_time` string, date-time — Date and time of the latest event
  - `event_payload` OnCallEventPayload — Payload for the `on_call_event` event type.
    - `type` 'audio' | 'collect', required — Type of in-call sub-event. One of `audio` (audio playback progress) or `collect` (DTMF digit collection progress).
    - `payload` object, nullable — Sub-event-specific data. Structure depends on the `type` field: - `audio`: `{ "status": "started" | "completed", "playback_id": "<uuid>" }` - `collect`: `{ "digits": "<digits>", "status": "started" | "completed" | "failed" }`
  - `from` string — Caller ID
  - `to` string — Destination number
  - `call_started` string, date-time — Date and time when the call started
  - `call_answered` string, date-time, nullable — Date and time when the call was answered
  - `call_completed` string, date-time, nullable — Date and time when the call ended
  - `machine_detected` boolean — Indicates whether the call was answered by an answering machine
  - `tag` string — Call metadata

## Other responses

- `400` — Returns a validation error when a request parameter is invalid.
- `401` — Unauthorized

---

[API](https://skmtc.net/wavix/apis/wavix-apis.md) · [All operations](https://skmtc.net/wavix/apis/wavix-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wavix/wavix-apis/revisions/b22f170488b6/schema)