Voice calls

Every Pozy number takes and makes regular phone calls as soon as it is active. Inbound calls go wherever you point them: a mobile, a SIP endpoint, or an AI voice agent. Outbound calls dial from your number with one request. Every call, in either direction, lands in one call history.

Calls are billed per connected minute by destination. Unanswered, busy and failed calls are not charged.

#Route inbound calls

All inbound settings live on one idempotent endpoint, POST /v1/phone-numbers/{id}/voice. It writes only the fields you send, so you can call it again later to change one setting.

curl -X POST https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "forwardTo": "tel:+13125550188",
    "forwardCallerId": "caller",
    "voicemailEnabled": true,
    "voicemailGreeting": "You have reached Acme. Leave a message and we will call you back."
  }'

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    forwardTo: "tel:+13125550188",
    forwardCallerId: "caller",
    voicemailEnabled: true,
    voicemailGreeting: "You have reached Acme. Leave a message and we will call you back.",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.enabled, data.pstnForwardTo);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/voice",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "forwardTo": "tel:+13125550188",
        "forwardCallerId": "caller",
        "voicemailEnabled": True,
        "voicemailGreeting": "You have reached Acme. Leave a message and we will call you back.",
    },
    timeout=30,
)
print(resp.json())

The response is the full effective configuration (pstnForwardTo, voicemail, hours, IVR, blocklist, recording settings).

#Destinations

Leave forwardTo out to keep the current destination. An empty string clears it, which leaves the number able to call out but not to ring anywhere on inbound.

#Inbound features

Business hours and the IVR menu take structured values:

{
  "businessHoursEnabled": true,
  "businessHoursTimezone": "Europe/Madrid",
  "businessHours": [
    { "day": 1, "open": "09:00", "close": "18:00" },
    { "day": 2, "open": "09:00", "close": "18:00" },
    { "day": 6, "open": "10:00", "close": "14:00" }
  ],
  "ivrEnabled": true,
  "ivrPrompt": "Press 1 for sales, 2 for support, 3 to talk to our assistant.",
  "ivrOptions": [
    { "digit": "1", "forwardTo": "tel:+13125550188", "label": "Sales" },
    { "digit": "2", "forwardTo": "sip:support@pbx.example.com", "label": "Support" },
    { "digit": "3", "forwardTo": "wss://agent.example.com/media", "label": "Assistant" }
  ]
}

• A window has day (0 is Sunday through 6), open and close as HH:MM in the timezone. A day with no window is closed. A window whose close is before its open runs past midnight. Up to 21 windows.
• A menu option has a digit (0 to 9, * or #), its own forwardTo and an optional label. Up to 12 options. No input or an unknown digit ends the call.

#The order an inbound call follows

1. Blocklist. A blocked caller gets a busy signal before the call is answered: no charge, no voicemail, no webhook.
2. call.received fires.
3. Business hours. Outside the windows, the call goes straight to voicemail (or hangs up if voicemail is off).
4. IVR menu, if on. The digit picks a destination.
5. Ring the destination. If nobody answers or the bridge fails, voicemail takes the call.
6. call.ended (or call.failed on a hard error).

Voicemail sends the account an email. The recording, and the transcript when transcription is on, attach to the call record. There is no separate voicemail webhook: call.ended carries isVoicemail: true.

#Turn calling off

DELETE /v1/phone-numbers/{id}/voice disables calls on the number. Pozy keeps the settings, so enabling again restores them.

#Place an outbound call

POST /v1/voice/calls with to. When the callee answers, Pozy bridges them to the number's forward destination, or to a per-call forwardTo. An optional greeting is spoken to the callee first.

curl -X POST https://api.pozy.ai/v1/voice/calls \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: callback-ticket-5521" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155550142",
    "to": "+13125550188",
    "forwardTo": "tel:+14155550100",
    "greeting": "Hi, this is Acme returning your call. Connecting you now."
  }'

const callRes = await fetch("https://api.pozy.ai/v1/voice/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "callback-ticket-5521",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fromNumber: "+14155550142",
    to: "+13125550188",
    forwardTo: "tel:+14155550100",
    greeting: "Hi, this is Acme returning your call. Connecting you now.",
  }),
});
const call = await callRes.json();
if (!callRes.ok) throw new Error(call.error);
console.log(call.callId, call.status); // "dialing"

resp = requests.post(
    "https://api.pozy.ai/v1/voice/calls",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "callback-ticket-5521",
    },
    json={
        "fromNumber": "+14155550142",
        "to": "+13125550188",
        "forwardTo": "tel:+14155550100",
        "greeting": "Hi, this is Acme returning your call. Connecting you now.",
    },
    timeout=30,
)
print(resp.json()["callId"])

A 200 means the call is dialing. Everything after that is asynchronous: follow it with GET /v1/voice/calls/{id}, or with call.ended and call.failed. Outbound phone calls do not send call.received.

Send an Idempotency-Key so a retry does not dial (and bill) a second call.

#Estimate the cost first

GET /v1/voice/calls/estimate?to=%2B13125550188&minutes=5&recording=true returns perMinuteUsd and a breakdown whose billableCostUSD is what you will be charged, using the same formula as the invoice. Use it to show prices to your users or to block expensive routes. Estimates cover outbound destinations only.

#Transfer and hang up

• POST /v1/voice/calls/{id}/transfer with to (a +E164 number or a sip: URI) hands a live call to someone else. The new leg always shows your number. wss:// is not a valid transfer target.
• POST /v1/voice/calls/{id}/end hangs up. It is safe to repeat: ending a finished call returns 200 with its current status. It also ends WhatsApp calls.

Final duration and cost are written when the hangup lands, so a call record can show its previous status for a moment.

#Webhook events

call.ended carries durationSeconds, endReason (hangup, no_answer, rejected or error), isVoicemail, callErrors, a cost breakdown in billing, and a signed recordingUrl when recording was on. Unanswered, busy and rejected calls end with call.ended, so branch on endReason. call.failed is for hard errors before or during the bridge.

#Limits

#Errors

#Endpoints