Name: Phone Number Validator API: Format, Type and Country
Brand: compasslab-1
SKU: api-compasslab-1-phone-validator
Availability: InStock
Author: API Market

WPTOOLS

# Phone Number Validator API

## Overview

The Phone Number Validator API checks and formats phone numbers from any country. It has 2 endpoints. The validate endpoint takes one number in almost any written form (spaces, dots, dashes, brackets, a `+` or `00` prefix, national format with a default `country`, extensions, and letters on vanity numbers such as 1-800-FLOWERS) and tells you whether it is a valid, assigned number range for its country, and if not, why (`too_short`, `needs_country`, `not_assigned` and so on). Valid numbers come back in E.164, international and national format, with the number type (mobile, fixed line, toll-free, VoIP, premium rate and more), the country, the calling code, the region or city, the time zones and, where known, the original carrier. The batch endpoint runs the same checks on up to 50 numbers in one call and adds a count of valid and invalid numbers.

It is built for signup and checkout forms that need to normalise numbers before storing them, SMS and calling workflows that should only dial valid numbers at a sensible local time, and CRM cleanup and spreadsheet imports where the same number is written many different ways. Each result is a flat JSON object with the original `input`, the `valid` and `possible` flags, the three formats, `country_code` (ISO 3166-1 alpha-2), `calling_code`, `type`, `carrier`, `location`, `time_zones`, `extension` and a `reason` when the number is not valid. Checks run offline against Google's libphonenumber metadata (version 9.0.40, through the Python `phonenumbers` package), so there is no network lookup and no check of whether a number is currently switched on.

## Features

*   **2 endpoints**: Validate one number with `GET`, or up to 50 numbers in one `POST` batch.
*   **Any input format**: International (`+44 20 7946 0958`, `0044...`), national with a default `country`, brackets, dots, dashes, extensions and vanity letters.
*   **Three output formats**: E.164 for storage and SMS or voice APIs, plus international and national display formats.
*   **Number type**: Mobile, fixed line, fixed line or mobile, VoIP, toll-free, premium rate, shared cost, personal, pager, UAN, voicemail or unknown.
*   **Location data**: Country code, calling code, region or city, and the time zones of the number range.
*   **Reasons for invalid numbers**: `not_a_number`, `needs_country`, `invalid_country_code`, `too_short`, `too_long`, `invalid_length` or `not_assigned`.
*   **Data source**: Google's libphonenumber metadata (version 9.0.40). Checks run offline, with no HLR or network lookup.
*   **Batch summary**: The batch endpoint returns results in input order with a `summary` of valid and invalid counts, and each batch counts as one request.
*   **Rate limit**: 1 request per second on FREE, 5 on PRO, 10 on ULTRA and 20 on MEGA.

## Use Cases

*   **Signup and checkout forms**: Reject numbers that cannot be real and store the rest in E.164.
*   **SMS and calling workflows**: Send texts only to numbers whose type is mobile, and use `time_zones` to call at the right local time.
*   **CRM cleanup and deduplication**: Convert every number to E.164 so each number has one key.
*   **Spreadsheet and legacy imports**: Clean numbers typed with spaces, dots, dashes, brackets and extensions in one batch call.
*   **Lead routing**: Route contacts by `country_code` or `location` before they reach a sales team.
*   **Data quality checks**: Use `reason` to explain to a user why a number was rejected.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/phone-validator
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate a phone number

Parses one phone number and returns whether it is valid and possible for its country, the E.164, international and national formats, the number type, country code, calling code, region or city, time zones, original carrier where known, any extension, and a `reason` when it is not valid. A number written in national format needs `country`, otherwise `reason` is `needs_country`.

**Method:** `GET`

**Endpoint:** `/v1/phone/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `number` | query | The phone number in any format, for example `+33 1 23 45 67 89`, `0033...`, `(212) 555-0123`, `1-800-FLOWERS` or a number with an extension. URL-encode it, so `+` becomes `%2B`. | string | Yes | - | 64 characters |
| `country` | query | Default country as an ISO 3166-1 alpha-2 code (for example `GB`), used for numbers written without a `+` country code. | string | No | - | 2 characters |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/phone-validator/v1/phone/validate?number=%2B14155552671" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "input": "+14155552671",
  "valid": true,
  "possible": true,
  "e164": "+14155552671",
  "international": "+1 415-555-2671",
  "national": "(415) 555-2671",
  "country_code": "US",
  "calling_code": 1,
  "type": "fixed_line_or_mobile",
  "carrier": null,
  "location": "San Francisco, CA",
  "time_zones": [
    "America/Los_Angeles"
  ],
  "extension": null,
  "reason": null
}
```

`valid` means the number belongs to a real, assigned number range for its country. `possible` only means its length is plausible. Where a country uses the same number ranges for mobile and fixed line numbers, as in this US example, `type` is `fixed_line_or_mobile`.

#### 2. Validate a batch of phone numbers

Runs the same checks as the single endpoint on 1 to 50 numbers and returns the results in the same order as the request, with a `count` and a `summary` of valid and invalid numbers. `country` applies to every number written without a `+` country code. Each batch counts as one request.

**Method:** `POST`

**Endpoint:** `/v1/phone/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `numbers` | body | Array of 1 to 50 phone numbers in any format, each 1 to 64 characters. Split larger lists into several calls. | array of strings | Yes | - | 50 items |
| `country` | body | Default country as an ISO 3166-1 alpha-2 code, used for every number written without a `+` country code. | string | No | - | 2 characters |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/phone-validator/v1/phone/batch" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+442071838750", "020 7183 8750", "12345"], "country": "GB"}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "summary": {
    "valid": 2,
    "invalid": 1
  },
  "results": [
    {
      "input": "+442071838750",
      "valid": true,
      "possible": true,
      "e164": "+442071838750",
      "international": "+44 20 7183 8750",
      "national": "020 7183 8750",
      "country_code": "GB",
      "calling_code": 44,
      "type": "fixed_line",
      "carrier": null,
      "location": "London",
      "time_zones": [
        "Europe/London"
      ],
      "extension": null,
      "reason": null
    },
    {
      "input": "020 7183 8750",
      "valid": true,
      "possible": true,
      "e164": "+442071838750",
      "international": "+44 20 7183 8750",
      "national": "020 7183 8750",
      "country_code": "GB",
      "calling_code": 44,
      "type": "fixed_line",
      "carrier": null,
      "location": "London",
      "time_zones": [
        "Europe/London"
      ],
      "extension": null,
      "reason": null
    },
    {
      "input": "12345",
      "valid": false,
      "possible": true,
      "e164": "+4412345",
      "international": "+44 12345",
      "national": "12345",
      "country_code": null,
      "calling_code": 44,
      "type": "unknown",
      "carrier": null,
      "location": null,
      "time_zones": [],
      "extension": null,
      "reason": "not_assigned"
    }
  ]
}
```

The first two inputs are the same London number written two ways, and both come back with the same `e164` value. The third is not an assigned number, so `valid` is `false` and `reason` is `not_assigned`.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request was processed. An invalid phone number still returns `200`, with `valid: false` and a `reason`. |
| 400 | Bad Request | The `country` value is not a known ISO 3166-1 alpha-2 code. The `detail` field explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Check that you are calling `/v1/phone/validate` or `/v1/phone/batch` under the base URL. |
| 422 | Unprocessable Entity | A parameter is missing or invalid, for example no `number`, a number longer than 64 characters, a `country` that is not 2 characters, or a batch with no numbers or more than 50. The response says which field failed. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE allows 1 request per second, PRO 5, ULTRA 10 and MEGA 20. The plans include 500, 10,000, 50,000 and 250,000 calls respectively, and a batch of up to 50 numbers counts as one request. The FREE plan stops at its 500 calls, while the paid plans keep working past their included calls and bill the extra calls. Requests above the per-second limit, or on the FREE plan after its calls are used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. To check many numbers quickly, use the batch endpoint rather than many single calls.

## FAQ

**Do I need to send the country?**

Only for numbers written in national format, such as `030 123456` or `020 7183 8750`. Numbers that start with `+` or `00` carry their own country code and need no `country`. Without it, a national-format number returns `valid: false` with `reason: needs_country`.

**Is the carrier current?**

No. `carrier` is the carrier the number range was originally assigned to, where that is known. Numbers can be ported to another carrier, so treat it as a hint. It is often `null`, as in the examples above.

**Can it tell if a number is active?**

No. Numbers are checked against official numbering plans in Google's libphonenumber metadata. There is no HLR lookup and no call to any network, so a valid number may still be disconnected.

**What is the difference between `valid` and `possible`?**

`possible` only checks that the length is plausible for the country. `valid` checks that the number falls in a real, assigned number range. A number can be possible but not valid, as with `12345` in the batch example.

**Why is the type `fixed_line_or_mobile`?**

Some countries, such as the United States, use the same number ranges for mobile and fixed line numbers, so the metadata cannot tell them apart.

**How accurate are the results?**

Results follow Google's libphonenumber metadata (version 9.0.40). The provider reports that in its own tests 25 business numbers from 10 countries matched Google's official libphonenumber demo, at about 70 ms per number.

**Does the provider store the numbers I send?**

The provider states that numbers are processed in memory and are never stored or logged.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Phone number validator API that checks numbers from any country and returns E.164 and national formats, line type, country, region and time zones.

Phone Number Validator API: Format, Type and Country

FREE