# Outbound calls

Place a phone call from one of your numbers with POST /v1/voice/calls, estimate its cost first, then transfer or end it while it is live.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

When you finish this page, you have placed a call from your number, transferred it and hung up, all over the API.

You need a [voice-enabled number](/platforms/voice/setup) and usage-based billing.

## Place a call

Call `POST /v1/voice/calls` with `to`. Zernio dials from `fromNumber`, which is optional when you own exactly one voice-enabled number.

When the callee answers, Zernio bridges them to the number's stored forward destination. A per-call `forwardTo` override takes a phone, a SIP endpoint or a `wss://` [AI agent](/platforms/voice/ai-agents).

An optional `greeting` is spoken to the callee before the bridge.

On the [balance](/pricing/balance), a call lasts only as long as your balance, plus what auto top-up can still add this month, pays for. Calls in progress count first.

At that limit the call ends with `hangupCause: "time_limit"`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: call } = await zernio.voice.createVoiceCall({
  body: {
    fromNumber: '+14155550100',
    to: '+13105551234',
    greeting: 'Connecting you now.',
  }
});
const callId = call.callId;
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

call = client.voice.create_voice_call(
    from_number="+14155550100",
    to="+13105551234",
    greeting="Connecting you now.",
)
call_id = call["callId"]
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/voice/calls" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromNumber": "+14155550100", "to": "+13105551234", "greeting": "Connecting you now."}'
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "success": true,
  "callId": "66e5f6a7b8c9d0e1f2a3b4c5",
  "status": "dialing",
  "direction": "outbound",
  "from": "+14155550100",
  "to": "+13105551234",
  "forwardTo": "tel:+13105559999",
  "greeting": "Connecting you now.",
  "recordingEnabled": false,
  "transcriptionEnabled": false
}
```

`200` means the call is dialing. The rest of the lifecycle is asynchronous.

Track it with `GET /v1/voice/calls/{id}` or the [`call.ended` and `call.failed` webhooks](/webhooks/phone#which-events-fire-in-what-order). Outbound phone calls do not emit `call.received`.

**Per-call options:**

- `recordOverride`, `transcribeOverride` and `transcriptionLanguage` change the number's defaults for this call only.
- `amd: true` turns on answering-machine detection. It defers the bridge until Zernio knows whether a human or a machine answered.
- `voicemailDropMessage` speaks a message to a detected machine and hangs up.

**Limits.** Calls are not capped by count. Your team (every number and key under the account) has two limits:

- 10 calls at once, counting outbound calls and calls forwarded to a phone.
- A daily safety limit on calling spend over the last 24 hours.

Contact support to raise them. Inside those, each profile can cap its own numbers with `maxOutboundCallsPerHour`, `maxDailyCallSpendUsd` and `maxForwardedMinutesPerDay` on `PUT /v1/profiles/{profileId}` (null clears one).

Past a limit the call returns `429` with code `call_limit_reached`. `details.limit` names it: `team_concurrent_calls`, `team_daily_cost`, `profile_outbound_calls_per_hour` or `profile_daily_call_spend`.

`GET /v1/profiles/{profileId}/limits` returns every limit with what is used and what remains.

**Retries.** Send an `Idempotency-Key` header so a retry replays the original response instead of dialing (and billing) a second call ([idempotency](/guides/idempotency)).

## Show your business on the callee's phone

Calls from a US number attached to a verified [caller identity](/platforms/phone-numbers/branded-calling) show your business name, logo and reason for calling on US mobiles, instead of a bare number.

The identity belongs to the number. No field on this endpoint turns it on, and every call from that number carries it, including SIP trunk and browser calls.

Each such call to a US number adds $0.10 ([call rates](/pricing/phone#branded-calling)).

## Estimate the cost first

Call `GET /v1/voice/calls/estimate` with `to` and the number you will call from (`from` or `fromNumberId`) before dialing.

Calls are metered per minute at the [rate for the route](/pricing/phone). The carrier prices a route by the caller ID, so the same destination can cost less from one of your numbers than from another.

- A caller in the destination country gets local rates.
- EEA callers get cheaper rates to EEA destinations, and some caller prefixes pay a surcharge. `rates.mobile.origination` names the band used.
- Mobiles and landlines are quoted separately. `lineType` says which one `to` is, and `perMinuteUsd` follows it.

A `tel:` forward is quoted as a second carrier leg from the same number.

```bash
curl "https://zernio.com/api/v1/voice/calls/estimate?to=%2B447400111222&from=%2B447400999888&minutes=5" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

Response (`200`):

```json
{
  "via": "voice",
  "destinationCountry": "GB",
  "lineType": "mobile",
  "callerId": "+447400999888",
  "callerCountry": "GB",
  "minutes": 5,
  "perMinuteUsd": 0.044,
  "billingIncrementSeconds": { "first": 60, "next": 60 },
  "rates": {
    "mobile": {
      "origination": "local",
      "perMinuteUsd": 0.044,
      "minPerMinuteUsd": 0.044,
      "maxPerMinuteUsd": 0.604,
      "networks": [
        { "name": "Mobile", "perMinuteUsd": 0.044 },
        { "name": "Mobile Other", "perMinuteUsd": 0.604 }
      ]
    },
    "landline": {
      "origination": "local",
      "perMinuteUsd": 0.0124,
      "minPerMinuteUsd": 0.0124,
      "maxPerMinuteUsd": 0.019,
      "networks": [
        { "name": "Fixed", "perMinuteUsd": 0.0124 },
        { "name": "Islands", "perMinuteUsd": 0.019 }
      ]
    }
  },
  "breakdown": {
    "telnyxCostUSD": 0.11,
    "carrierCostUSD": 0.1,
    "callControlCostUSD": 0.01,
    "recordingCostUSD": 0,
    "transcriptionCostUSD": 0,
    "brandedCallUSD": 0,
    "billableCostUSD": 0.22,
    "totalCostUSD": 0.22
  }
}
```

- `perMinuteUsd` is the rate most networks share. The dialed network cannot be known from the number, so a call can land anywhere from `minPerMinuteUsd` to `maxPerMinuteUsd`.
- `telnyxCostUSD`, `recordingCostUSD` and `transcriptionCostUSD` are the raw upstream costs. `telnyxCostUSD` is `carrierCostUSD` plus `callControlCostUSD`, the $0.002/min Voice API fee.
- `billableCostUSD` is what Zernio charges for them.
- `totalCostUSD` equals `billableCostUSD` on a phone call. Unlike a [WhatsApp call](/platforms/whatsapp/calling), there is no separate Meta bill.

### SIP trunk calls

Calls through a [SIP trunk](/platforms/voice/integrations/elevenlabs) are quoted when `from` is attached to a trunk. They bill twice the carrier rate, with no call-control fee.

`trunkId` alone prices from a number attached to that trunk. `via=trunk` without `from` shows the dearest caller band, a worst case rather than a quote.

The response adds `trunk`, which says whether the trunk's limits would refuse the call:

```json
{
  "via": "trunk",
  "destinationCountry": "ES",
  "lineType": "landline",
  "perMinuteUsd": 0.8002,
  "trunk": {
    "id": "6650f0c2a1b2c3d4e5f60718",
    "limitsSource": "trunk",
    "maxDestinationRateUsd": 0.3,
    "destinationWhitelisted": true,
    "rateCheck": "over",
    "outboundEnabled": true,
    "wouldBlock": true,
    "blockReasons": ["rate_above_cap"]
  }
}
```

- `maxDestinationRateUsd` (default $0.30, `null` when the trunk has no cap) is compared with the carrier's rate for the route, which is half the billed rate. Each network in `rates` carries `aboveRateCap`.
- `rateCheck: "partial"` means only some networks are above the cap, and calls to those are refused.
- The default whitelist is every country Zernio sells numbers in. Isle of Man, Jersey and Guernsey numbers on +44 count as their own countries and are not on it.

## Transfer and hang up

While a call is live, blind-transfer the callee with `POST /v1/voice/calls/{id}/transfer` and `to`. It takes a `+E164` number or a `sip:` URI. `wss://` is not a valid transfer target.

Control of the leg is handed off. The caller ID on the new leg is always your own number, and the call ends normally when the transferred leg hangs up.

```bash
curl -X POST "https://zernio.com/api/v1/voice/calls/66e5f6a7b8c9d0e1f2a3b4c5/transfer" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "tel:+13105559999"}'
```

Response (`200`):

```json
{
  "success": true,
  "callId": "66e5f6a7b8c9d0e1f2a3b4c5",
  "transferredTo": "tel:+13105559999"
}
```

End a call with `POST /v1/voice/calls/{id}/end`. It also ends WhatsApp calls, ringing or answered ([WhatsApp calling](/platforms/whatsapp/calling#step-4-place-an-outbound-call)).

It is idempotent. Ending a call that already ended returns `200` with the call's current status.

```bash
curl -X POST "https://zernio.com/api/v1/voice/calls/66e5f6a7b8c9d0e1f2a3b4c5/end" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

Response (`200`):

```json
{
  "success": true,
  "callId": "66e5f6a7b8c9d0e1f2a3b4c5",
  "status": "ending"
}
```

Final duration and cost are written when the hangup event lands, so the call record can briefly still show its prior status.

## If it fails

A `422` on `POST /v1/voice/calls` means no voice-enabled number matches `fromNumber`, or the number has no forward destination and the request sent no `forwardTo`:

```json
{
  "error": "No forward destination configured for +14155550100. Set forwardTo on the number or pass it per call.",
  "type": "invalid_request_error"
}
```

[Set the forward destination](/platforms/voice/setup#set-the-forward-destination) on the number, or pass `forwardTo` in the call.

**`402`** with `code: "insufficient_balance"` means your balance, plus what auto top-up can still add this month, cannot fund one minute of this call. Add funds at `funding_url`, then retry.

**`409` on transfer** means the call is not connected yet or has already ended.

**`502`** means the carrier refused to originate. The call is marked `failed`.

Every error uses the envelope in [error handling](/guides/error-handling).

## Related

- [Browser calling](/platforms/voice/browser-calling): place the call from a web page instead.
- [Call history and recordings](/platforms/voice/history): read the call back.
- [Place an outbound call](/voice/create-voice-call): every field of the request.
- [Phone webhooks](/webhooks/phone): `call.ended` carries duration, `endReason` and the cost breakdown.
- [Call rates](/pricing/phone): per-minute prices by destination.