Phone numbers for WhatsApp

Every WhatsApp account sits on a phone number. You can buy one through Pozy, which arrives already verified with Meta and can also make calls and send SMS, or connect a number you already own. This page covers the WhatsApp side of numbers: getting one ready, keeping it registered and knowing when it stops working. Searching inventory, country rules, KYC and porting are in Phone, SMS & voice.

#Buy a number for WhatsApp

Call POST /v1/phone-numbers/purchase with the profile the number should belong to. connectWhatsapp is true by default, so the purchase hands straight over to WhatsApp signup, where the new number appears as Verified in Meta's picker.

curl -X POST https://api.pozy.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "6710c4e2b9a1f03d8e5c7a21",
    "country": "US",
    "numberType": "local",
    "areaCode": "415",
    "wantsWhatsapp": true,
    "purchaseIntentId": "bakery-main-line"
  }'

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: "6710c4e2b9a1f03d8e5c7a21",
    country: "US",
    numberType: "local",
    areaCode: "415",
    wantsWhatsapp: true,
    purchaseIntentId: "bakery-main-line",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

console.log(data);

import os
import requests

H = {"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"}
resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/purchase",
    headers=H,
    json={
        "profileId": "6710c4e2b9a1f03d8e5c7a21",
        "country": "US",
        "numberType": "local",
        "areaCode": "415",
        "wantsWhatsapp": True,
        "purchaseIntentId": "bakery-main-line",
    },
    timeout=30,
)
print(resp.json())

purchaseIntentId makes the purchase safe to retry: sending the same id again returns the number you already bought (status: "already_purchased") instead of buying a second one.

A number needs a payment method on the workspace. Without one the purchase returns 402 payment_required. Pricing is per number per month (WhatsApp pricing).

#Add WhatsApp to a number you bought for calls or SMS

If a Pozy number was bought without WhatsApp, start Meta's verification with POST /v1/phone-numbers/{id}/whatsapp/request-code (method SMS or VOICE). Pozy receives the code on the number itself, so you do not have to relay it. Then connect the number through signup as usual.

If Meta refuses the number for WhatsApp, a number that is already live keeps working for calls and SMS and the call returns 409 number_not_whatsapp_eligible. A number that was never live is swapped for an eligible one at no cost, and the response says replaced: true with the newPhoneNumber.

#Move a number to another profile

A Pozy number belongs to one profile, and connecting it from any other profile returns 409. To re-home it, call PATCH /v1/whatsapp/phone-numbers/{id}/profile with the new profileId. That moves the number and every account built on it (WhatsApp, calls, SMS) together. id is the number id from GET /v1/phone-numbers, not an account id.

#Bring your own number

A number on your own carrier connects through Embedded Signup or a Meta token. It works for WhatsApp messages and calls, but Pozy cannot add SMS or phone-network calling to it, because there is no Pozy line behind it. GET /v1/phone-numbers lists it under connected, not numbers.

Meta occasionally asks a number you brought from another provider to verify again. When that happens:

1. Request a code with POST /v1/accounts/{accountId}/whatsapp/request-code (SMS or VOICE). The code goes to the business's own phone, so someone there has to read it. You can request one every 10 minutes, and Meta adds its own cooldown.
2. Submit it with POST /v1/accounts/{accountId}/whatsapp/verify-code.
3. Finish with POST /v1/accounts/{accountId}/whatsapp/register. Verifying alone does not put the number back on the Cloud API.

#Register a number that has a PIN

If the number has two-step verification turned on, the connect flow cannot register it on its own and Meta rejects the registration (error 133005). The account still looks connected, but every send fails with (#200) You do not have the necessary permission.

Run the registration again with the right PIN. Pozy uses the PIN for this call only and does not store it.

curl -X POST https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/whatsapp/register \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "205718" }'

A 422 means Meta still refused, most often a wrong PIN. Check it in WhatsApp Manager and try again.

#Check that a number is alive

A WhatsApp channel can die without much warning, for example when a coexistence number is disconnected from the phone. Do not rely on the absence of an account.disconnected event; check directly.

Health also reports messagingRestriction when Meta refuses sends for a reason other than the channel itself:

The restriction appears on the first refused send and clears on the next delivered message.

#Number lifecycle

Numbers bought through Pozy move through statuses, and Pozy sends an event on each step. The event names start with whatsapp.number. for historical reasons, but they fire for every Pozy number, including ones used only for calls or SMS.

Numbers in instant countries skip the review states and go straight to active.

#Release a number

DELETE /v1/phone-numbers/{id} releases a number you bought. It disconnects the WhatsApp account on it, stops the monthly charge and makes the number unusable. This cannot be undone.

#Endpoints

#Webhook events