---
title: "Place an outbound phone call"
method: POST
path: "/v1/voice/calls"
tags: ["Voice"]
---

# Place an outbound phone call

`POST /v1/voice/calls`

Dials `to` FROM one of your voice-enabled numbers and, on answer,
bridges the callee to the number's stored forward destination, or to
the per-call `forwardTo` override. Destinations can be your own AI
voice agent (Vapi/Retell), a phone, or a SIP endpoint. An optional
`greeting` is spoken to the callee before the bridge.

The 200 response means the call is dialing; the lifecycle continues
asynchronously (track it via `GET /v1/voice/calls/{id}` or the `call.*`
webhooks). Outbound calls are capped per rolling hour (429 when hit).

**Idempotency:** send an `Idempotency-Key` header to make retries safe;
same key + same body replays the original response instead of dialing
(and billing) a second call.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `to` string, required — Destination to dial, E.164 with leading +.
  - `fromNumber` string — Which of your voice-enabled numbers to dial from. Optional when you have exactly one.
  - `forwardTo` string — Per-call agent override (tel:+E164, sip:..., or wss://...); defaults to the number's stored forward destination.
  - `greeting` string — Spoken to the callee when they answer, before the bridge.
  - `recordOverride` boolean — Per-call recording toggle; defaults to the number's setting.
  - `transcribeOverride` boolean — Per-call transcription toggle; defaults to the number's setting.
  - `transcriptionLanguage` 'auto' | 'en' | 'es' — 'auto' derives from the callee's country; 'en'/'es' force it.
  - `amd` boolean — Answering-machine detection; defers the bridge until human vs machine is known.
  - `voicemailDropMessage` string — Spoken to a detected machine, then hang up (implies `amd`). For outbound voicemail drops.

## Response `200`

Call originated; lifecycle continues asynchronously.

- object
  - `success` boolean
  - `callId` string — Internal Call doc ID
  - `telnyxCallControlId` string
  - `status` 'dialing'
  - `direction` 'outbound'
  - `from` string
  - `to` string
  - `forwardTo` string
  - `greeting` string, nullable
  - `recordingEnabled` boolean
  - `transcriptionEnabled` boolean
  - `transcriptionLanguage` 'auto' | 'en' | 'es'

## Other responses

- `401` — Unauthorized
- `422` — No voice-enabled number matches `fromNumber`, or no forward destination configured (set the number's forward or pass `forwardTo`).
- `429` — Outbound call limit reached (per rolling hour).
- `502` — Carrier-side originate failed; the call has been marked failed.

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)