Trillet AI logo

Purchase Phone Number

Buy a phone number for your workspace, either from your plan's free allowance or through a Stripe Checkout page.

POSThttps://api.trillet.ai/v1/api/twilio/purchase-number

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-idstringrequired

Workspace identifier for the API.

Request Body

countrystringrequired

Country code: US, CA, AU, or GB (GB only when it appears in Available Countries). Any other country also needs addressSid.

typestring

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

phoneNumberstringrequired

The number to buy, in E.164 format, as returned by Search Available Numbers.

addressSidstring

Address SID for regulatory compliance. Required for countries other than US, CA, AU and GB.

couponstring

Stripe coupon applied to the checkout. Used only for a paid number.

Response

Free allowance (201)

modestring

Always free.

messagestring

Phone number purchased using free plan allowance.

phoneNumberstring

The number you bought, in E.164 format.

sidstring

The provider's ID for the number. This is the sid you send to Release Phone Number.

freeStatusobject

Your free allowance after this purchase: limit, used, remaining and hasFree.

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.

StatuscodeWhen
400nonecountry, phoneNumber or x-workspace-id missing, type missing for a non-AU country, or addressSid missing where it's required
400INVALID_COUNTRYGB is not available on this deployment
400UK_LOCAL_NOT_AVAILABLEGB with type local
400MARKUP_BELOW_MIN / MARKUP_EXCEEDS_MAXSub-workspace billed through its agency's own Stripe, with a phone number markup outside $5 to $20 a month
403TOLL_FREE_NOT_AVAILABLEToll-free type or toll-free number
403FREE_PLAN_PURCHASE_BLOCKEDThe workspace is on the free plan. You can still bring your own number
403TRIAL_PURCHASE_BLOCKEDThe plan is still in its free trial. Numbers can be bought once the first payment goes through
500PURCHASE_FAILEDAnything else, for example the number was taken by someone else in the meantime
{
  "country": "US",
  "type": "local",
  "phoneNumber": "+14155550123"
}
Free allowance
{
  "mode": "free",
  "message": "Phone number purchased using free plan allowance.",
  "phoneNumber": "+14155550123",
  "sid": "1293384261075731499",
  "freeStatus": {
    "limit": 3,
    "used": 1,
    "remaining": 2,
    "hasFree": true
  }
}
Paid number
https://checkout.stripe.com/c/pay/cs_test_EXAMPLE0000000000

Last updated on