Buy a number

Buying a number takes two calls: search the inventory, then purchase. In countries that do not regulate numbers (the US among them) the number is active when the purchase returns. Regulated countries answer with a KYC step instead.

#Before you start

• A payment method on file. Telephony is billed on your monthly invoice.
• A profile id. Each number belongs to one profile. See Profiles.

#Search available numbers

GET /v1/phone-numbers/available queries the carrier's live inventory for a country (default US). Every result lists its features, and voice is always included.

curl "https://api.pozy.ai/v1/phone-numbers/available?country=US&areaCode=415&sms=true&limit=10" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/available?country=US&areaCode=415&sms=true&limit=10", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const n of data.numbers) console.log(n.phoneNumber, n.locality, n.features);

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/phone-numbers/available",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"country": "US", "areaCode": "415", "sms": "true", "limit": 10},
    timeout=30,
)
for n in resp.json()["numbers"]:
    print(n["phoneNumber"], n.get("locality"), n["features"])

{
  "country": "US",
  "numberType": "local",
  "requireSms": true,
  "numbers": [
    { "phoneNumber": "+14155550142", "features": ["voice", "sms", "mms"], "locality": "San Francisco" },
    { "phoneNumber": "+14155550143", "features": ["voice", "sms", "mms"], "locality": "San Francisco", "bestEffort": true }
  ]
}

When too few numbers match, nearby numbers fill the list and carry bestEffort: true. Drop them if the exact area matters. An unknown query parameter is a 400 that lists the accepted ones.

#Purchase

POST /v1/phone-numbers/purchase takes a profileId and a country. Leave out phoneNumber and Pozy assigns one. Pass a phoneNumber from your search to buy that exact number.

curl -X POST https://api.pozy.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "6650c1f0a2b3c4d5e6f70812",
    "country": "US",
    "phoneNumber": "+14155550142",
    "wantsSms": true,
    "connectWhatsapp": false,
    "purchaseIntentId": "order-8841-line-1"
  }'

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/purchase", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "6650c1f0a2b3c4d5e6f70812",
    country: "US",
    phoneNumber: "+14155550142",
    wantsSms: true,
    connectWhatsapp: false,
    purchaseIntentId: "order-8841-line-1",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.phoneNumber?.id, data.phoneNumber?.status);

resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/purchase",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "profileId": "6650c1f0a2b3c4d5e6f70812",
        "country": "US",
        "phoneNumber": "+14155550142",
        "wantsSms": True,
        "connectWhatsapp": False,
        "purchaseIntentId": "order-8841-line-1",
    },
    timeout=60,
)
print(resp.status_code, resp.json())

{
  "message": "Phone number provisioned",
  "phoneNumber": {
    "id": "6650d2e1b3c4d5e6f7081923",
    "phoneNumber": "+14155550142",
    "status": "active",
    "country": "US",
    "provisionedAt": "2026-10-30T10:12:00Z",
    "profileId": "6650c1f0a2b3c4d5e6f70812"
  }
}

Keep phoneNumber.id. It is the {id} for every feature endpoint (/voice, /sms, /sip-trunk).

#When the profile already has a number

A profile holds one number. If the profile you pass already has one, Pozy puts the new number on the next free profile (creating one if needed) and returns it in profileId. Read profileId from the response rather than assuming.

#Regulated countries

A country with needsKyc: true answers 202 instead of provisioning:

{
  "status": "kyc_required",
  "country": "GB",
  "numberType": "local",
  "kycUrl": "https://pozy.ai/kyc/..."
}

Send your customer to kycUrl, or collect the details yourself with the KYC endpoints. Passing phoneNumber for a regulated country or type is a 400: the number is assigned after review.

#Check one country

GET /v1/phone-numbers/availability?country=BR&numberType=local answers for a single country: whether stock exists, which area codes are in stock (areaOptions), and the address rule for KYC (addressConstraint).

areaAvailability sorts every area of the country into inStock, preOrder and outOfStock. Pass an ndc from inStock as areaCode on the purchase to hold the order to that area.

#Watch a sold-out country

When a country or area has no stock, you have two options:

• Pre-order it. If the type is preOrderable, submit the KYC form with preOrder: true. The number is sourced for you, usually within 2 to 4 weeks, and nothing is billed until it is active.
• Watch it. POST /v1/phone-numbers/stock-watches with a country (and optionally numberType and areaCode) puts you on the list.

curl -X POST https://api.pozy.ai/v1/phone-numbers/stock-watches \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "IE", "numberType": "local" }'

Stock is checked every few hours. When numbers come back, Pozy sends the phone_number.stock_available webhook, so subscribe to it to hear about it. A watch fires once and is then used up, so create it again if you miss the stock.

#Manage numbers

• GET /v1/phone-numbers lists your numbers. Filter by status or profileId. Released numbers are left out unless you ask for status=released.
• GET /v1/phone-numbers/{id} returns one number with its features and voice settings.
• DELETE /v1/phone-numbers/{id} releases a number.

#Limits

#Errors

All errors use the standard error shape.

#Endpoints

#Webhook events