# Phone numbers

Buy or port real phone numbers, then turn on calls, SMS and WhatsApp on the same number with one API.

A Pozy phone number is a real number on the public phone network. You buy it (or port one you already own), and it becomes the anchor for calls, texts and WhatsApp. One number can do all three, or only the one you need.

This section covers getting and running numbers, texting from them, calling from them and showing your brand when you call.

## What a number can do

| Capability | How it works | Where |
| --- | --- | --- |
| Calls | On by default as soon as the number is active. Route inbound calls to a phone, a SIP address or an AI agent. Place outbound calls from the API or a browser. | Every country Pozy sells numbers in |
| SMS and MMS | Turn on per number. US numbers need a carrier registration before they can send, which is not available yet. | SMS-capable countries and numbers only |
| WhatsApp | Connect the number to a WhatsApp Business account. Any type except toll-free. | Every country |
| Branded calling | Not available yet. Show your business name, logo and call reason on the callee's phone. | US numbers calling US mobiles |

There is no separate "WhatsApp number" or "SMS number". Features hang off the number as sub-resources: `POST /v1/phone-numbers/{id}/voice`, `POST /v1/phone-numbers/{id}/sms`. Activity lives on its own resources: call history at `/v1/calls`, texts at `/v1/sms/messages`.

> **Note:**
> 
> Phone, SMS and voice need a payment method on file. Without one, a purchase returns `402` with `payment_required`. Numbers do not carry emergency service (911, 112).

## The lifecycle

### Check what is on offer
`GET /v1/phone-numbers/countries` lists every country you can buy in, with the monthly price and a flag for each capability. It needs no API key, so you can drive a public country picker from it.

### Get a number
[Buy one](https://pozy.ai/docs/telephony/buy-a-number) from live inventory, or [port in](https://pozy.ai/docs/telephony/porting) a number you already own. Regulated countries ask for identity documents first ([KYC](https://pozy.ai/docs/telephony/kyc)).

### Turn on what you need
Calls are already on. [Enable SMS](https://pozy.ai/docs/telephony/sms) (and [register for 10DLC](https://pozy.ai/docs/telephony/10dlc) in the US), or [connect WhatsApp](https://pozy.ai/docs/whatsapp/phone-numbers).

### Use it
[Place and receive calls](https://pozy.ai/docs/telephony/voice-calls), [send texts](https://pozy.ai/docs/telephony/sms) and read one [call history](https://pozy.ai/docs/telephony/call-recordings) across every number.

## List the countries

```bash cURL
curl https://api.pozy.ai/v1/phone-numbers/countries
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/phone-numbers/countries", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const c of data.countries) {
  console.log(c.code, `$${(c.monthlyCents / 100).toFixed(2)}/mo`, {
    sms: c.smsAvailable,
    whatsapp: c.whatsappAvailable,
    kyc: c.needsKyc,
    inStock: c.inStock,
  });
}
```
```python Python
import requests

resp = requests.get("https://api.pozy.ai/v1/phone-numbers/countries", timeout=30)
for c in resp.json()["countries"]:
    print(c["code"], c["monthlyCents"] / 100, c["smsAvailable"], c["needsKyc"])
```

```json
{
  "countries": [
    {
      "code": "US",
      "tier": 1,
      "monthlyCents": 300,
      "needsKyc": false,
      "callsAvailable": true,
      "smsAvailable": true,
      "whatsappAvailable": true,
      "inStock": true,
      "preOrderable": false,
      "types": [
        { "numberType": "local", "monthlyCents": 300, "smsAvailable": true, "needsKyc": false, "inStock": true, "fulfilment": "instant" },
        { "numberType": "toll_free", "monthlyCents": 300, "smsAvailable": false, "whatsappAvailable": false, "inStock": true, "fulfilment": "instant" }
      ]
    }
  ]
}
```

The country fields describe its default type, which is the first entry in `types`. Countries come back cheapest first.

| Field | Meaning |
| --- | --- |
| `monthlyCents` | Price per number per month, in US cents |
| `needsKyc` | The country regulates who can hold a number. You submit identity details before the number is ordered. |
| `inStock` | A stock snapshot, refreshed every few hours. The purchase checks again. |
| `preOrderable` | Out of stock, but you can still order it through the KYC form. Sourcing usually takes 2 to 4 weeks. |
| `fulfilment` | `instant` provisions in the request. `request` means the number is sourced to order. |
| `outboundCallingAvailable` | Business-initiated WhatsApp calls. This is not about regular phone calls. |

For one country in detail (area codes in stock, the address rule for KYC), call `GET /v1/phone-numbers/availability?country=GB`. See [Buy a number](https://pozy.ai/docs/telephony/buy-a-number#check-one-country).

## Number types

Each number is `local`, `mobile`, `national` or `toll_free`, depending on what the country stocks. Every country has a default type chosen to work with as many capabilities as possible. Pass `numberType` to pick another.

> **Warning:**
> 
> Toll-free numbers can never connect WhatsApp. Buy them with `connectWhatsapp: false` and use them for calls and SMS.

## Pricing

A number costs a flat monthly price set by its country and type. It is charged in full when the number activates and again on the 1st of each month, with no daily proration. The price is stored on the number at purchase (`monthlyCents`), so it does not change if the rate card does. Minutes and segments are billed on top.

| What | Price |
| --- | --- |
| Outbound messages (inbox replies, broadcasts, sequences; not X DMs or SMS) | First 10,000 each month free, then $1 per 10,000 |
| Managed ads (running or in review) | First 500 free, then $0.01 per active ad per month |
| X post | $0.015 per post |
| X post containing a link | $0.20 per post |
| X reads (analytics, lookups) | $0.005 per resource |
| X DMs | $0.01 per DM read, $0.015 per DM sent |
| Phone numbers | From $3 per number per month, by country |
| Calls | From $0.01 per minute by destination. Recording $0.004 per minute, transcription $0.03 per minute |
| Branded calling | $0.10 per branded call |
| SMS | From $0.008 per segment by destination |
| US 10DLC registration | $9 one-time brand fee, then $20 per month per campaign ($4 for a sole proprietor) |
| RCS agent | $150 setup, then $160 per month in the US or $75 elsewhere, plus $750 on US carrier approval |
| Creator payouts | 4% of each transfer, minimum $0.50 |
| Support assistant | At cost per answered question, capped at $100 per month |

See [Pricing](https://pozy.ai/docs/billing) for how usage lands on your invoice.

## Statuses

| Status | Meaning |
| --- | --- |
| `pending_payment` | Waiting for a payment method |
| `pending_regulatory` | In regulatory review (KYC countries) |
| `regulatory_declined` | The reviewer declined it. You can [fix and resubmit](https://pozy.ai/docs/telephony/kyc#fix-a-declined-number). |
| `provisioning`, `verifying` | Being set up. Not billed until `active`. |
| `active` | Ready to use |
| `suspended` | Stopped, for example after a failed payment. Recovers to `active`. |
| `releasing`, `released` | Returned to the carrier. `released` is final. |

## In this section

- [Buy a number](https://pozy.ai/docs/telephony/buy-a-number): Search inventory, buy, watch sold-out countries and release.
- [Port a number in](https://pozy.ai/docs/telephony/porting): Move a number you own from another carrier.
- [KYC for regulated countries](https://pozy.ai/docs/telephony/kyc): Identity documents, hosted forms and declined numbers.
- [Send SMS](https://pozy.ai/docs/telephony/sms): Texts, MMS, opt-outs and lookups.
- [US 10DLC registration](https://pozy.ai/docs/telephony/10dlc): Register a US number so it can send.
- [Voice calls](https://pozy.ai/docs/telephony/voice-calls): Inbound routing, IVR, voicemail and outbound calls.
- [AI voice agents](https://pozy.ai/docs/telephony/ai-voice-agents): Let an agent answer your number.
- [Branded calling](https://pozy.ai/docs/telephony/branded-calling): Your name and logo on the callee's screen.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/phone-numbers`](https://pozy.ai/docs/api/listPhoneNumbers) | List phone numbers |
| [`GET /v1/phone-numbers/{id}`](https://pozy.ai/docs/api/getPhoneNumber) | Get phone number |
| [`DELETE /v1/phone-numbers/{id}`](https://pozy.ai/docs/api/releasePhoneNumber) | Release phone number |
| [`POST /v1/phone-numbers/purchase`](https://pozy.ai/docs/api/purchasePhoneNumber) | Purchase phone number |
| [`GET /v1/phone-numbers/claims/{claimId}`](https://pozy.ai/docs/api/getPhoneNumberClaim) | Resolve a number claim |
| [`GET /v1/phone-numbers/countries`](https://pozy.ai/docs/api/listPhoneNumberCountries) | List offerable number countries |
| [`GET /v1/phone-numbers/available`](https://pozy.ai/docs/api/searchAvailablePhoneNumbers) | Search available numbers |
| [`GET /v1/phone-numbers/availability`](https://pozy.ai/docs/api/checkPhoneNumberAvailability) | Check country availability |
| [`GET /v1/phone-numbers/kyc`](https://pozy.ai/docs/api/getPhoneNumberKycForm) | Get KYC form spec |
| [`POST /v1/phone-numbers/kyc`](https://pozy.ai/docs/api/submitPhoneNumberKyc) | Submit KYC |
| [`GET /v1/phone-numbers/kyc/document/{documentId}`](https://pozy.ai/docs/api/viewPhoneNumberKycDocument) | View a KYC document on file |
| [`POST /v1/phone-numbers/kyc/upload-document`](https://pozy.ai/docs/api/uploadPhoneNumberKycDocument) | Upload a KYC document |
| [`POST /v1/phone-numbers/kyc/validate-address`](https://pozy.ai/docs/api/validatePhoneNumberKycAddress) | Pre-validate KYC address |
| [`POST /v1/phone-numbers/kyc/share`](https://pozy.ai/docs/api/createPhoneNumberKycLink) | Create a hosted KYC link (not available yet) |
| [`GET /v1/phone-numbers/port-in`](https://pozy.ai/docs/api/listPhoneNumberPortIns) | List port-in orders |
| [`POST /v1/phone-numbers/port-in`](https://pozy.ai/docs/api/createPhoneNumberPortIn) | Port numbers in |
| [`POST /v1/phone-numbers/port-in/check`](https://pozy.ai/docs/api/checkPhoneNumberPortability) | Check portability |
| [`GET /v1/phone-numbers/port-in/claims/{claimId}`](https://pozy.ai/docs/api/getPhoneNumberPortClaim) | Resolve a port claim |
| [`POST /v1/phone-numbers/port-in/documents`](https://pozy.ai/docs/api/uploadPhoneNumberPortInDocument) | Upload a porting document |
| [`GET /v1/phone-numbers/port-in/requirements`](https://pozy.ai/docs/api/getPhoneNumberPortInRequirements) | Country porting requirements |
| [`GET /v1/phone-numbers/port-in/{id}/requirements`](https://pozy.ai/docs/api/getPhoneNumberPortInOrderRequirements) | A port-in order's pending requirements |
| [`DELETE /v1/phone-numbers/port-in/{id}`](https://pozy.ai/docs/api/cancelPhoneNumberPortIn) | Cancel a port-in |
| [`POST /v1/phone-numbers/kyc/review-packet`](https://pozy.ai/docs/api/reviewPhoneNumberKycPacket) | Pre-review a KYC packet |
| [`GET /v1/phone-numbers/{id}/remediate`](https://pozy.ai/docs/api/getPhoneNumberRemediation) | Get declined requirements |
| [`POST /v1/phone-numbers/{id}/remediate`](https://pozy.ai/docs/api/remediatePhoneNumber) | Resubmit a declined number |
| [`POST /v1/phone-numbers/{id}/remediate/reply`](https://pozy.ai/docs/api/replyToPhoneNumberReviewer) | Reply to the regulatory reviewer |
| [`POST /v1/phone-numbers/{id}/remediate/respond`](https://pozy.ai/docs/api/respondToPhoneNumberReviewer) | Respond to the regulatory reviewer (message + corrections) |
| [`GET /v1/phone-numbers/stock-watches`](https://pozy.ai/docs/api/listPhoneNumberStockWatches) | List stock watches |
| [`POST /v1/phone-numbers/stock-watches`](https://pozy.ai/docs/api/createPhoneNumberStockWatch) | Watch an out-of-stock country |
| [`DELETE /v1/phone-numbers/stock-watches/{id}`](https://pozy.ai/docs/api/deletePhoneNumberStockWatch) | Stop watching a country |
| [`POST /v1/phone-numbers/{id}/whatsapp/request-code`](https://pozy.ai/docs/api/requestPhoneNumberWhatsAppCode) | Request the WhatsApp verification code for a number |

## Webhook events

Number status events carry a `whatsapp.number.` prefix for historical reasons. They fire for every number, whether or not WhatsApp is on it.

| Event | When it fires |
| --- | --- |
| [`whatsapp.number.activated`](https://pozy.ai/docs/webhooks/events#whatsapp-number-activated) | WhatsApp number activated. |
| [`whatsapp.number.declined`](https://pozy.ai/docs/webhooks/events#whatsapp-number-declined) | WhatsApp number declined. |
| [`whatsapp.number.action_required`](https://pozy.ai/docs/webhooks/events#whatsapp-number-action-required) | WhatsApp number action required. |
| [`whatsapp.number.verification_required`](https://pozy.ai/docs/webhooks/events#whatsapp-number-verification-required) | WhatsApp number verification-required. |
| [`whatsapp.number.suspended`](https://pozy.ai/docs/webhooks/events#whatsapp-number-suspended) | WhatsApp number suspended. |
| [`whatsapp.number.reactivated`](https://pozy.ai/docs/webhooks/events#whatsapp-number-reactivated) | WhatsApp number reactivated. |
| [`whatsapp.number.released`](https://pozy.ai/docs/webhooks/events#whatsapp-number-released) | WhatsApp number released. |
| [`whatsapp.number.kyc_submitted`](https://pozy.ai/docs/webhooks/events#whatsapp-number-kyc-submitted) | WhatsApp number KYC submitted. |
| [`phone_number.stock_available`](https://pozy.ai/docs/webhooks/events#phone-number-stock-available) | Phone-number stock available. |