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.

​
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

Get your API key

​
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
Authorization: Bearer your_api_key
Content-Type: application/json
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
Authorization: Bearer your_api_key
Content-Type: application/json
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
Authorization: Bearer your_api_key
Content-Type: application/json
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
Authorization: Bearer your_api_key
Content-Type: application/json
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
Authorization: Bearer your_api_key
Content-Type: application/json
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
Authorization: Bearer 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
Authorization: Bearer your_api_key
Content-Type: application/json
Request body example: 
{
  "ids": [
    1,
    2
  ],
  "destinations": [
    {
      "transport": 1,
      "destination": "sip@example.com",
      "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
Authorization: Bearer your_api_key
Content-Type: application/json