Search Available Numbers

Search for available phone numbers in the TryVox catalog by country, type, region, area code, or number pattern.

Endpoint

GET /v1/account/{account_id}/numbers/catalog

Query Parameters

Parameter	Type	Required	Description
country	string	Yes	ISO 3166-1 alpha-2 country code (e.g., "IN", "US", "GB")
type	string	No	Number type: "local", "toll_free", or "mobile"
region	string	No	State or region filter (e.g., "CA" for California)
area_code	string	No	Area code filter (e.g., "415" for San Francisco)
contains	string	No	Number pattern to search for (e.g., "1234")
limit	integer	No	Results per page (default: 20, max: 100)

Request Example

Search for local phone numbers in India:

curl --request GET \
  --url 'https://api.tryvox.io/v1/account/acc_123abc/numbers/catalog?country=IN&type=local&limit=10' \
  --header 'Authorization: Bearer tvx_sk_live_...'

Search for toll-free numbers in the US with a specific area code:

curl --request GET \
  --url 'https://api.tryvox.io/v1/account/acc_123abc/numbers/catalog?country=US&type=toll_free&area_code=800' \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "data": [
    {
      "e164": "+919876543210",
      "country": "IN",
      "type": "local",
      "region": "Maharashtra",
      "capabilities": ["voice", "sms"],
      "monthly_fee": 2.50,
      "setup_fee": 0.00,
      "currency": "USD"
    },
    {
      "e164": "+919876543211",
      "country": "IN",
      "type": "local",
      "region": "Maharashtra",
      "capabilities": ["voice", "sms"],
      "monthly_fee": 2.50,
      "setup_fee": 0.00,
      "currency": "USD"
    }
  ],
  "pagination": {
    "total": 245,
    "count": 10,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 25
  }
}

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
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")

Next Steps

Once you find a number you want, proceed to purchase it.