Phone numbers

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

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.

#The lifecycle

#List the countries

curl https://api.pozy.ai/v1/phone-numbers/countries

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,
  });
}

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"])

{
  "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.

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.

#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.

#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.

See Pricing for how usage lands on your invoice.

#Statuses

#In this section

#Endpoints

#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.