Purchase number for location

POST 
/phone-system/numbers/location/:locationId/purchase

Purchase number for location. With version: v3, the HTTP 201 body is the standard success envelope (status, data, message, statusCode). The v3 purchase fields live under data: number, locationId, id, and underLcAccount (renamed from under_ghl_account).

Request

version stringrequired

Send v3 to use the v3 response contract (AIP). This is the supported version value for these endpoints.

Available optionsv3

locationId stringrequired

Location ID as string

application/json

application/json

Body

Bodyrequired

phoneNumberstringrequired

phoneNumber to purchase

addressSidstringrequired

addressSid twilio address id

bundleSidstringrequired

bundleSid twilio bundle id

countryCodestringrequired

country for which the phone numbers are being requested

numberTypeobjectrequired

type of phone number to be purchased

paymentIntentIdstringrequired

stripe payment intent id

stripeAccountIdstringrequired

stripe account id

paymentMethodIdstringrequired

stripe registered payment method id

localitystringrequired

locality of the user in which number is being purchased

regionstringrequired

region of the user in which number is being purchased

fingerprintIdstringrequired

fingerprintId is request id which is unique for every purchase number request

skipLocationKYCbooleanrequired

Skip location-level KYC verification if agency-level compliance has already been verified

Example (auto)

{
  "phoneNumber": "830236932",
  "addressSid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "bundleSid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "countryCode": "US",
  "numberType": "local",
  "paymentIntentId": "pi_3Oxxxxxxxxxxxxxxxxxxxx",
  "stripeAccountId": "acct_1Oxxxxxxxxxxxxxxxx",
  "paymentMethodId": "pm_1Oxxxxxxxxxxxxxxxx",
  "locality": "Austin",
  "region": "TX",
  "fingerprintId": "purchase-req-abc-123",
  "skipLocationKYC": false
}

application/json

Success envelope; v3 purchase details are in data (slim shape: number, locationId, id, underLcAccount).

application/json

Schema

Schema

statusstringrequired
Outcome indicator from the shared success helper.
Available optionssuccess
dataobjectrequired

V3 purchase payload: purchased number, location, Twilio account id, and underLcAccount.

messagestringrequired

Human-readable success message.

statusCodenumberrequired

HTTP status echoed in the response body.

Example (auto)

{
  "status": "success",
  "data": {
    "number": "+17745678902",
    "locationId": "tDtDnQdgm2LXpyiqYvZ6",
    "id": "twilio-account-123",
    "underLcAccount": false
  },
  "message": "Number purchase successful",
  "statusCode": 201
}