> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Numbers API Overview
> How to search, buy, configure, and release phone numbers using the Wavix API.
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](https://app.wavix.com/) 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](/api-reference/authentication#get-your-api-key)
## Search for phone numbers
To receive calls from your customers, purchase a phone number from the Wavix global inventory.
[Get a list of countries](/api-reference/buy/list-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:
```http theme={null}
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:
```json theme={null}
{
"countries": [
{
"id": 8652,
"name": "United States",
"short_name": "US",
"has_provinces_or_states": true
}
]
}
```
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](/api-reference/buy/list-region-cities) or [a list of cities](/api-reference/buy/list-cities) for countries without regions. Use the `country_id` and, optionally, the `region_id` parameters from the responses above.
Request sample:
```http theme={null}
GET https://api.wavix.com/v1/buy/countries/8652/regions/379/cities
Authorization: Bearer your_api_key
Content-Type: application/json
```
Response sample:
```json theme={null}
{
"cities": [
{
"id": 200,
"name": "LOS ANGELES, CA",
"area_code": 213568
}
]
}
```
For USA the `area_code` parameter in the response is in NPA-NXX format.
[Get a list of phone numbers](/api-reference/buy/list-available-phone-numbers) in the selected city. Use the IDs of the selected country and city from the responses above.
Request sample:
```http theme={null}
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.
[Add the selected phone numbers](/api-reference/cart/add-to-cart) to your cart.
```http theme={null}
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.
```json theme={null}
{
"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.
Check out numbers from the cart.
After phone numbers are added to the cart, [check them out](/api-reference/cart/check-out-the-cart) to finalize the purchase.
```http theme={null}
POST https://api.wavix.com/v1/buy/cart/checkout
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request sample:
```json theme={null}
{
"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](/api-reference/my-numbers/list-phone-numbers) on your Wavix account by using the following method:
```http theme={null}
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](/api-reference/my-numbers/update-a-phone-number) for a number, use the following API method. You can update destinations for several numbers in a single request.
```http theme={null}
POST https://api.wavix.com/v1/mydids/update-destinations
Authorization: Bearer your_api_key
Content-Type: application/json
```
Request body example:
```json theme={null}
{
"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](/api-reference/my-numbers/release-phone-numbers), use the following API method:
```http theme={null}
DELETE https://api.wavix.com/v1/mydids
Authorization: Bearer your_api_key
Content-Type: application/json
```