Purchase a phone number
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:
GET /v1/phone-numbers/requirements?phoneNumber=.... Ifitemsis empty, buy normally.- Create what it asks for: addresses with
POST /v1/addresses, documents withPOST /v1/documents. - Purchase with
typeandregulatoryRequirements. The number is bought and billed at once withregulatoryStatus: pending_review. - Poll
GET /v1/phone-numbers/{phoneNumberId}untilregulatoryStatusisapproved. 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.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Phone number in E.164 format.
"+15551234567"
Optional custom name for the phone number.
100Type the number was found under in GET /v1/phone-numbers/available. Used to look the number up and to keep regulatory information for reuse. Required when regulatoryRequirements is sent. toll_free is accepted as an alias of tollFree. A number not listed under this type is refused with 400 number_unavailable saying so.
local, national, tollFree, mobile Regulatory information, for numbers whose requirements list is not empty. Get the list with GET /v1/phone-numbers/requirements?phoneNumber=... and send one entry per requirement id, except action requirements, which take no value. Every required id must be present, once, and no unknown id may be sent; otherwise the purchase is refused with 400 invalid_request before anything is charged.
The information is kept for your project under the number's country and type. A later purchase there may omit this field if what is kept still covers that number's requirements. Omit it for numbers without requirements.
50Response
Phone number purchased successfully.