Purchase Phone Number
Buy a phone number for your workspace, either from your plan's free allowance or through a Stripe Checkout page.
What happens depends on your plan:
- Free allowance. If your plan still has free numbers left (Studio and Agency Plus include some), the number is bought straight away and the response is a JSON object.
- Paid number. Otherwise the API does not buy the number yet. It creates a Stripe Checkout session and returns its URL as the response body. The number is provisioned only after someone opens that URL in a browser and completes the payment.
Pick a number first with Search Available Numbers.
Your role needs the phone_number:create permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
countrystringrequiredCountry code: US, CA, AU, or GB (GB only when it appears in Available Countries). Any other country also needs addressSid.
typestringNumber type: local or mobile. Required for every country except AU.
Toll-free numbers can't be bought through the API. tollFree, or any number with a toll-free area code (800, 833, 844, 855, 866, 877, 888), is refused with 403 and code TOLL_FREE_NOT_AVAILABLE. For GB, only mobile is available: local returns 400 with code UK_LOCAL_NOT_AVAILABLE.
phoneNumberstringrequiredThe number to buy, in E.164 format, as returned by Search Available Numbers.
addressSidstringAddress SID for regulatory compliance. Required for countries other than US, CA, AU and GB.
couponstringStripe coupon applied to the checkout. Used only for a paid number.
Response
Free allowance (201)
modestringAlways free.
messagestringPhone number purchased using free plan allowance.
phoneNumberstringThe number you bought, in E.164 format.
sidstringThe provider's ID for the number. This is the sid you send to Release Phone Number.
freeStatusobjectYour free allowance after this purchase: limit, used, remaining and hasFree.
Paid number (201)
The body is a bare string: the Stripe Checkout URL. Open it in a browser to pay. The number appears in List Phone Numbers once the payment completes.
Errors
Errors return {"error": "...", "code": "..."}. code is present on the errors raised during the purchase itself.
| Status | code | When |
|---|---|---|
400 | none | country, phoneNumber or x-workspace-id missing, type missing for a non-AU country, or addressSid missing where it's required |
400 | INVALID_COUNTRY | GB is not available on this deployment |
400 | UK_LOCAL_NOT_AVAILABLE | GB with type local |
400 | MARKUP_BELOW_MIN / MARKUP_EXCEEDS_MAX | Sub-workspace billed through its agency's own Stripe, with a phone number markup outside $5 to $20 a month |
403 | TOLL_FREE_NOT_AVAILABLE | Toll-free type or toll-free number |
403 | FREE_PLAN_PURCHASE_BLOCKED | The workspace is on the free plan. You can still bring your own number |
403 | TRIAL_PURCHASE_BLOCKED | The plan is still in its free trial. Numbers can be bought once the first payment goes through |
500 | PURCHASE_FAILED | Anything else, for example the number was taken by someone else in the meantime |
{
"country": "US",
"type": "local",
"phoneNumber": "+14155550123"
}{
"mode": "free",
"message": "Phone number purchased using free plan allowance.",
"phoneNumber": "+14155550123",
"sid": "1293384261075731499",
"freeStatus": {
"limit": 3,
"used": 1,
"remaining": 2,
"hasFree": true
}
}https://checkout.stripe.com/c/pay/cs_test_EXAMPLE0000000000Last updated on