> ## 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.

# Number Validator API

> How to validate phone numbers using the Wavix Number Validator API.

The Wavix Number Validator API allows customers to automate the phone number validation process by checking the phone number validity, reachability, and roaming status. Using the API, Wavix customers can also get the name of the current carrier of the phone number, check if it was ported, and more.

All phone numbers are validated using the latest international numbering plan databases.

Based on your specific business needs, you can get detailed information about either a single phone number or several numbers with one request. You can also choose one of three validation request types: `format`, `analysis`, or `validation`.

The table below shows phone number details returned depending on the request type.

**Phone number details returned by request type**

| Parameter                    | Format | Analysis | Validation |
| ---------------------------- | :----- | :------- | :--------- |
| Phone number validity        | Yes    | Yes      | Yes        |
| Phone number country         | Yes    | Yes      | Yes        |
| Local format                 | Yes    | Yes      | Yes        |
| E.164 format                 | Yes    | Yes      | Yes        |
| MCC, MNC for mobile numbers  | —      | Yes      | Yes        |
| Type (mobile/toll-free/etc.) | —      | Yes      | Yes        |
| Current carrier              | —      | Yes      | Yes        |
| Ported status                | —      | Yes      | Yes        |
| Unallocated range            | —      | Yes      | Yes        |
| Risky destination            | —      | Yes      | Yes        |
| Timezone                     | —      | —        | Yes        |
| Reachability\*               | —      | —        | Yes        |
| Roaming status\*             | —      | —        | Yes        |

\*Reachability and roaming statuses are returned for mobile phone numbers only. The feature is available in selected countries only. Please contact your account manager for more details.

## Prerequisites

Before you can access the Wavix Number Validator API, you need to sign up for Wavix.

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

## How to validate a single phone number

To get detailed information about [a single phone number](/api-reference/number-validator/validate-a-number), use the following method:

```http theme={null}
GET https://api.wavix.com/v1/validation?phone_number=number&type=validation_type
Authorization: Bearer your_api_key
Content-Type: application/json
```

Pass the following parameters in the request URL:

* `number` - the phone number to be validated.
* `validation_type` - the Wavix Number validator request type: `format`, `analysis`, or `validation`.

All parameters are mandatory and cannot be blank.

If successful, the method returns the `HTTP 200 OK` status code. The response body will contain information about the phone number.

```json theme={null}
{
   "phone_number": "+6288736592000",
   "is_valid": true,
   "country_code": "ID",
   "e164_format": "+6288736592000",
   "national_format": "087-36592-000",
   "ported": false,
   "mcc": "510",
   "mnc": "10",
   "phone_type": "mobile",
   "carrier_name": "PT. Telekomunikasi Selular",
   "risky_destination": false,
   "unallocated_range": false,
   "reachable": true,
   "roaming": false,
   "timezone": "UTC+07:00",
   "cost": "0.015",
   "error_code": "000"
}
```

## How to validate multiple phone numbers

The Wavix Number Validator API allows you to get detailed information about [several phone numbers](/api-reference/number-validator/validate-multiple-numbers) with a single request.

Under most circumstances, it takes about 30 seconds to validate a batch of 500 phone numbers. We recommend you use `async:true` if you're planning to validate more than 500.

```http theme={null}
POST https://api.wavix.com/v1/validation
Authorization: Bearer your_api_key
Content-Type: application/json
```

Request body example:

```json theme={null}
{
   "async": false,
   "type": "validation",
   "phone_numbers": [
      "+6288736592000",
      "+6288736592001",
      "+6288736592002"
   ]
}
```

* `async` — whether the request executes asynchronously.
* `type` — validation type: `format`, `analysis`, or `validation`.
* `phone_numbers` — array of E.164-formatted numbers to validate.

All parameters are mandatory and cannot be blank.

### Response

For synchronous requests, if successful, the method returns the `HTTP 200 OK` status code. The response contains detailed information about each phone number.

```json theme={null}
{
    "status": "success",
    "pending": 0,
    "items": [
        {
            "phone_number": "+6288736592000",
            "is_valid": true,
            "country_code": "ID",
            "e164_format": "+6288736592000",
            "national_format": "087-36592-000",
            "ported": false,
            "mcc": "510",
            "mnc": "10",
            "phone_type": "mobile",
            "carrier_name": "PT. Telekomunikasi Selular",
            "risky_destination": false,
            "unallocated_range": false,
            "reachable": true,
            "roaming": false,
            "timezone": "UTC+07:00",
            "cost": "0.015",
            "error_code": "000"
        },
        {
            "phone_number": "+6288736592001",
            "is_valid": true,
            "country_code": "ID",
            "e164_format": "+6288736592001",
            "national_format": "087-36592-001",
            "ported": false,
            "mcc": "510",
            "mnc": "10",
            "phone_type": "mobile",
            "carrier_name": "PT. Telekomunikasi Selular",
            "risky_destination": false,
            "unallocated_range": false,
            "reachable": true,
            "roaming": false,
            "timezone": "UTC+07:00",
            "cost": "0.015",
            "error_code": "000"
        }
    ]
}
```

For asynchronous requests, if successful, the method returns the `HTTP 201 Created` status code, which means the validation process has started. The response contains a token that needs to be used to poll the results.

```json theme={null}
{
  "request_uuid": "12542c5c-1a17-4d12-a163-5b68543e75f6"
}
```

To [poll asynchronous validation results](/api-reference/number-validator/retrieve-validation-results), use the following method:

```http theme={null}
GET https://api.wavix.com/v1/validation/{request_uuid}
Authorization: Bearer your_api_key
Content-Type: application/json
```

If successful, the response will contain detailed information about the phone numbers that have already been validated and the status of the asynchronous validation.

```json theme={null}
{
  "status": "progress",
  "count": 4,
  "pending": 2,
  "items": [
    {
      "phone_number": "+6288736592000",
      "is_valid": true,
      "country_code": "ID",
      "e164_format": "+6288736592000",
      "national_format": "087-36592-000",
      "ported": false,
      "mcc": "510",
      "mnc": "10",
      "phone_type": "mobile",
      "carrier_name": "PT. Telekomunikasi Selular",
      "risky_destination": false,
      "unallocated_range": false,
      "reachable": true,
      "roaming": false,
      "timezone": "UTC+07:00",
      "cost": "0.015",
      "error_code": "000"
    },
    {
      "phone_number": "+6288736592001",
      "is_valid": true,
      "country_code": "ID",
      "e164_format": "+6288736592001",
      "national_format": "087-36592-001",
      "ported": false,
      "mcc": "510",
      "mnc": "10",
      "phone_type": "mobile",
      "carrier_name": "PT. Telekomunikasi Selular",
      "risky_destination": false,
      "unallocated_range": false,
      "reachable": true,
      "roaming": false,
      "timezone": "UTC+07:00",
      "cost": "0.015",
      "error_code": "000"
    }
  ]
}
```