List Your Numbers

Retrieve a paginated list of all phone numbers owned by your account, with optional filtering by country and status.

Endpoint

GET /v1/account/{account_id}/numbers

Query Parameters

Parameter	Type	Required	Description
country	string	No	Filter by ISO 3166-1 alpha-2 country code (e.g., "IN", "US")
status	string	No	Filter by status: "active", "pending", "suspended"
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

Request Example

List all numbers in your account:

curl --request GET \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers \
  --header 'Authorization: Bearer tvx_sk_live_...'

List only US numbers:

curl --request GET \
  --url 'https://api.tryvox.io/v1/account/acc_123abc/numbers?country=US&per_page=50' \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "data": [
    {
      "e164": "+14155551234",
      "country": "US",
      "type": "local",
      "region": "CA",
      "status": "active",
      "capabilities": ["voice", "sms", "mms"],
      "monthly_fee": 1.25,
      "setup_fee": 0.00,
      "currency": "USD",
      "trunk_id": "trunk_abc123",
      "application_id": null,
      "created_at": "2026-03-15T08:20:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    },
    {
      "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": "app_xyz789",
      "created_at": "2026-04-09T10:30:00Z",
      "updated_at": "2026-04-09T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 3
  }
}

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: "active", "pending", or "suspended"
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

Number Status

Status	Description
active	Number is active and ready to use
pending	Number purchase is being processed
suspended	Number has been temporarily suspended (e.g., due to billing issues)

Pagination

The response includes pagination metadata to help you navigate through large result sets:

total: Total number of numbers matching the filter
count: Number of items in the current response
per_page: Number of items per page
current_page: Current page number
total_pages: Total number of pages available

To fetch the next page, increment the page parameter in your request.

Next Steps

Configure a Number to assign it to a trunk or application
Release a Number if you no longer need it

On this page