POST

Purchase Phone Number

Provisions a new phone number for a sub-account.

POSThttps://api.vantaxai.com/v1/phone-numbers

Search for an available number by `area_code` or a broader `number_pattern`, then provision it to the given sub-account. Provide exactly one of `area_code` or `number_pattern`. The provisioned number can be assigned to an Agent immediately after purchase.

Provisions a real, billable number

This endpoint provisions an actual phone number from the carrier and is billable. A monthly rental charge applies to the sub-account for as long as the number is held. Use Release Phone Number to stop the charges.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Body Parameters

sub_account_idstringrequired
Sub-account that will own and be billed for the number.
example: sub_8a1f4c2e
countrystringrequired
ISO 3166-1 alpha-2 country code to search within. Defaults to "US".
example: US
area_codestringoptional
Preferred area code to search for an available number. Provide this or `number_pattern`.
example: 415
number_patternstringoptional
Digit pattern to match available numbers, using `*` as a wildcard. Provide this or `area_code`.
example: +1415555****

Request

curl -X POST https://api.vantaxai.com/v1/phone-numbers \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "sub_account_id": "sub_8a1f4c2e",
    "country": "US",
    "area_code": "415"
  }'

const res = await fetch("https://api.vantaxai.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    Authorization: "Bearer vx_live_3fa9c2...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sub_account_id: "sub_8a1f4c2e",
    country: "US",
    area_code: "415",
  }),
});
const { data: number } = await res.json();

const number = await vantax.phoneNumbers.purchase({
  subAccountId: "sub_8a1f4c2e",
  country: "US",
  areaCode: "415",
});

number = vantax.phone_numbers.purchase(
    sub_account_id="sub_8a1f4c2e",
    country="US",
    area_code="415",
)

Response

{
  "success": true,
  "message": "Phone number purchased successfully",
  "data": {
    "id": "pn_55ad12",
    "number": "+14155550142",
    "country": "US",
    "source": "platform",
    "agent_id": null,
    "sub_account_id": "sub_8a1f4c2e",
    "capabilities": {
      "voice": true,
      "sms": true
    },
    "created_at": "2026-01-14T10:30:00Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "area_code", "message": "Provide either area_code or number_pattern" }
  ]
}

{
  "success": false,
  "message": "No available numbers matched the requested area code"
}