Purchase a Number

Purchase an available phone number from the TryVox catalog. Once purchased, the number is immediately active and ready to be configured.

Endpoint

POST /v1/account/{account_id}/numbers/purchase-from-inventory

Request Body

Field	Type	Required	Description
e164	string	Yes	Phone number in E.164 format (e.g., "+919876543210")
country	string	Yes	ISO 3166-1 alpha-2 country code (e.g., "IN", "US")

Request Example

curl --request POST \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/purchase-from-inventory \
  --header 'Authorization: Bearer tvx_sk_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "e164": "+919876543210",
    "country": "IN"
  }'

Response

{
  "e164": "+919876543210",
  "country": "IN",
  "type": "local",
  "region": "Maharashtra",
  "status": "active",
  "capabilities": ["voice", "sms"],
  "monthly_fee": 2.50,
  "setup_fee": 0.00,
  "currency": "USD",
  "trunk_id": null,
  "application_id": null,
  "created_at": "2026-04-09T10:30:00Z",
  "updated_at": "2026-04-09T10:30:00Z"
}

Response Fields

Field	Type	Description
e164	string	Phone number in E.164 format
country	string	ISO 3166-1 alpha-2 country code
type	string	Number type: "local", "toll_free", or "mobile"
region	string	State or region where the number is located
status	string	Number status (always "active" on purchase)
capabilities	array	Supported capabilities: "voice", "sms", "mms"
monthly_fee	number	Monthly recurring fee in USD
setup_fee	number	One-time setup fee in USD
currency	string	Currency for pricing (always "USD")
trunk_id	string	null
application_id	string	null
created_at	string	ISO 8601 timestamp of purchase
updated_at	string	ISO 8601 timestamp of last update

Billing

Purchased numbers are billed monthly on a pro-rated basis:

Monthly fees are charged at the beginning of each billing cycle
Setup fees (if any) are charged once at the time of purchase
Billing starts immediately upon successful purchase

See the pricing documentation for detailed rates by country and number type.

Error Handling

Common errors:

Error Code	Description
400	Invalid E.164 format or country code
404	Number not found in available inventory
409	Number already purchased by another account
402	Insufficient account balance

Next Steps

After purchasing a number:

List Your Numbers to view all owned numbers
Configure a Number to assign it to a trunk or application

On this page