v2

latestOpenAPI 3.1.02026-08-075421692.0 MB

WhatsApp Phone Numbers

Purchase phone number

Deprecated alias of /v1/phone-numbers/purchase; same contract. New integrations should use that path.

Payment-first: you do not pick a specific number, the system provisions one and auto-assigns it. With usage-based billing active and a payment method on file, the number provisions inline and bills per month on your usage-based invoice (there is no checkout redirect). No payment method on file returns 402 PAYMENT_REQUIRED; a regulated country returns 202 with status: "kyc_required" and a kycUrl.

Requires usage-based billing (the Usage plan). The maximum number of phone numbers is determined by the user's plan.

post/v1/whatsapp/phone-numbers/purchase

Request body

profileIdstring required

Profile to associate the number with

countrystring

ISO 3166-1 alpha-2 country for the number (default US). International numbers require usage-based billing. Tier 3/4 countries return 202 { status: "kyc_required", kycUrl } — the customer must complete KYC at that URL before the number is ordered. See GET /v1/whatsapp/phone-numbers/countries.

purchaseIntentIdstring

Optional idempotency key. Send the same value when retrying a purchase: if a number was already bought under this key, the API returns { status: "already_purchased", numberId, phoneNumber } instead of provisioning a second number. Generate a fresh key for each genuinely new purchase.

allowMultipleboolean

Any second purchase within 10 minutes of a previous one is rejected with 409 code PURCHASE_VELOCITY as duplicate protection. Pass true to confirm the additional purchase is intentional (e.g. bulk provisioning).

Response

Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).