Skip to main content
The Wavix platform provides access to a global inventory of local, mobile, national, and toll-free numbers in over 140 countries. In this section, you will learn how to search, purchase, configure, and release phone numbers using the Wavix API.
The Numbers API is available only for Flex Pro users.

​
Prerequisites

Before you can search for and buy your first phone number, sign up for a Wavix account.

​
Create a Wavix account

  1. Sign up for a Wavix account using your business email address.
  2. Confirm your email address and phone number during the sign-up process.
  3. Wait for your account to be approved by the Wavix team.
  4. After approval, choose either the Wavix Flex or Flex Pro account level.
Once your account is approved, you can access the Wavix app and APIs.

​
Find your API key

Wavix uses API keys to authenticate requests. To find API keys associated with your account:
  1. Sign in to your Wavix account.
  2. Go to Administration → API Keys.
  3. Copy the API key you want to use, or create a new one by clicking Create new.

​
Search for phone numbers

To receive calls from your customers, purchase a phone number from the Wavix global inventory.
1

Get a list of countries

Get a list of countries with phone numbers available. You can search for geo, toll-free, or both types of phone numbers. You can also filter by SMS-enabled numbers.Request sample:
GET https://api.wavix.com/v1/buy/countries?type_filter=all&text_enabled_only=false&appid=your_api_key
Response sample:
{
  "countries": [
    {
      "id": 8652,
      "name": "United States",
      "short_name": "US",
      "has_provinces_or_states": true
    }
  ]
}
2

Get a list of provinces or states

This step is required only for countries with provinces or states, such as the USA, Canada, and Australia.
For countries with provinces or states, get a list of cities in a region or a list of cities for countries without regions. Use the country_id and, optionally, the region_id parameters from the responses above.Request sample:
GET https://api.wavix.com/v1/buy/countries/8652/regions/379/cities?appid=your_api_key
Response sample:
{
  "cities": [
    {
      "id": 200,
      "name": "LOS ANGELES, CA",
      "area_code": 213568
    }
  ]
}
For USA the area_code parameter in the response is in NPA-NXX format.
3

Get a list of phone numbers

Get a list of phone numbers in the selected city. Use the IDs of the selected country and city from the responses above.Request sample:
GET https://api.wavix.com/v1/buy/countries/8652/city/200/dids?type_filter=all&text_enabled_only=true&appid=your_api_key
The response will contain phone numbers and their details, such as ID, activation fee, monthly fee, and the number of inbound channels.

​
Buy phone numbers

To purchase phone numbers, follow these steps.
1

Add numbers to cart

Add the selected phone numbers to your cart.
PUT https://api.wavix.com/v1/buy/cart?appid=your_api_key
The request body must contain an array of phone numbers you want to purchase.
{
  "ids": ["18022551119"]
}
The response will contain phone numbers successfully added to the cart and their details, such as activation fee, monthly fee, and the number of inbound channels for the number.
2

Check out numbers from cart

Check out numbers from the cart.After phone numbers are added to the cart, check them out to finalize the purchase.
POST https://api.wavix.com/v1/buy/cart/checkout?appid=your_api_key
Request sample:
{
  "ids": ["18022551119"]
}
Activation fee and monthly fee will be automatically deducted from your balance. Make sure you have enough funds in your account or a primary card linked to your account with sufficient funds.

​
List purchased numbers

You can get a list of purchased numbers on your Wavix account by using the following method: 
GET https://api.wavix.com/v1/mydids?appid=your_api_key
The response will contain numbers and their details, such as status, activation, monthly fees, and the number of inbound channels. A number status can be one of the following:
  • active - The number is fully configured and can receive inbound calls.
  • inactive - Additional documents are required to activate the number. For inactive numbers, the response will contain a description of the documents required to activate the number.

​
Update number destination

For active numbers, Wavix can route inbound calls to:
  • a SIP trunk
  • a SIP URI
  • a dedicated PSTN number
To update inbound call routing and SMS endpoint for a number, use the following API method. You can update destinations for several numbers in a single request. 
POST https://api.wavix.com/v1/mydids/update-destinations?appid=your_api_key
Request body example: 
{
  "ids": [
    1,
    2
  ],
  "destinations": [
    {
      "transport": 1,
      "destination": "[email protected]",
      "priority": 1,
      "callhunt": false,
      "active": true
    }
  ]
}

​
Return number

Return numbers you no longer use to the Wavix global inventory. To return unused numbers, use the following API method: 
DELETE https://api.wavix.com/v1/mydids?appid=your_api_key