Purchase an available phone number. Requires a paid plan: the Free plan cannot purchase phone numbers and receives 402 with code paid_plan_required.

The included number. A paid plan includes one number at no charge, once per account: it must be a US or Canadian number (a +1 number) costing $20 a month or less. isFreeEligible in GET /v1/phone-numbers/available marks the numbers that qualify. Claiming it spends the benefit for good, across every team the account owner owns, so releasing that number does not make another one free.

Numbers with regulatory requirements. Which numbers need regulatory information is decided per number, not by a fixed country list. The purchase looks the requirements up for the exact number before charging anything:

1. GET /v1/phone-numbers/requirements?phoneNumber=.... If items is empty, buy normally.
2. Create what it asks for: addresses with POST /v1/addresses, documents with POST /v1/documents.
3. Purchase with type and regulatoryRequirements. The number is bought and billed at once with regulatoryStatus: pending_review.
4. Poll GET /v1/phone-numbers/{phoneNumberId} until regulatoryStatus is approved. Assign it to a sender before or after approval; it starts carrying messages once approved.

Reuse. Information you submitted is kept for your project, per country and type, and a later purchase there may omit regulatoryRequirements. Reuse only happens when what is kept still covers every requirement of the new number and every address and document in it belongs to the project. Otherwise, or when nothing is kept, the purchase returns 400 regulatory_compliance_required with the missing requirements in details.

Invalid values (a missing, unknown or repeated requirement id, an address or document from another project, or one rejected in review) return 400 invalid_request. If an address or document cannot be registered for review, the purchase returns 400 invalid_request naming the requirement. If the requirements cannot be looked up, the purchase returns 502 requirements_unavailable, except for US and Canadian numbers, which are sold as numbers without requirements. None of these errors charge anything.

{
  "phoneNumber": "+15551234567",
  "regulatoryRequirements": [
    {
      "requirementType": "8c5b1a2e-0f3d-4f5b-9a61-2c7e4d9b1f10",
      "fieldValue": "jd7x2k3m4n5p6q7r8s9t0abc"
    }
  ]
}

{
  "phoneNumber": {
    "phoneNumber": "+15551234567",
    "capabilities": [
      "sms",
      "voice"
    ]
  }
}