Sign in
WhatsApp Phone Numbers

Purchase phone number

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

Payment-first: the system provisions a number and auto-assigns it, unless you pass phoneNumber to buy one exact number from GET /v1/phone-numbers/available. 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.

The monthly price is the one GET /v1/phone-numbers/countries quotes for that country and numberType at the time of purchase, and it is stamped on the number: later rate-card changes never move a number you already own.

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.

phoneNumberstring

One exact number to buy, in E.164, taken from GET /v1/phone-numbers/available. Fails with 409 code PHONE_NUMBER_UNAVAILABLE when it is no longer available.

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

OR
OR

Changes

Changed in 4 of the 56 revisions of this API.32

  • dd3865482f9f1See the full diff
    • ●

      added the new NO_WHATSAPP_ELIGIBLE_NUMBER enum value to the response property for the response status

      response-property-enum-value-added

  • eded32b628231See the full diff
    • ●

      added the new COUNTRY_OUT_OF_STOCK enum value to the response property for the response status

      response-property-enum-value-added

  • be448f13ecdc1See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • e70ed06e715011See the full diff
    • ●

      added the new PHONE_NUMBER_UNAVAILABLE enum value to the response property for the response status

      response-property-enum-value-added

    • ○

      added the new optional request property

      new-optional-request-property