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

Khairul Fauzy Khairudin

# Phone Number Validator API

## Overview

The Phone Number Validator API checks and formats phone numbers for 245 countries and territories. Send a number in international format, or a national number with a default country, and get back whether it is valid, its line type (mobile, fixed line, VoIP and more), the E.164, international, national and RFC 3966 formats, the country and the calling code. A bulk endpoint handles up to 100 numbers in one call.

It is built for developers of sign up and checkout forms, CRMs, SMS and calling platforms, and data cleaning jobs who need numbers stored in one consistent format. In our tests `+14155552671` came back valid in US format, the UK national number `07911 123456` with country `GB` came back as a valid mobile in E.164 as `+447911123456`, and `12345` came back invalid with the error `missing_country_or_plus_prefix`.

## Features

*   **4 endpoints**: single validation, bulk validation, supported countries and example numbers.
*   **245 countries**: every country and territory with its calling code.
*   **Line type**: mobile, fixed line, VoIP, toll free and other number types.
*   **All common formats**: E.164, international, national and RFC 3966.
*   **Bulk**: up to 100 numbers per call with valid and invalid counts.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Sign up forms**: check a phone number before sending a verification SMS.
*   **CRM data**: normalise stored numbers to E.164.
*   **SMS platforms**: skip landlines before sending text messages.
*   **Lead cleaning**: validate imported lead lists in bulk.
*   **Checkout**: format delivery contact numbers per country.

## API Documentation

### Base URL

All requests use the following base URL.

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

### Authentication

All requests are authenticated with 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 one number

Validates and formats one number. Numbers without a `+` prefix need `country`.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `phone` | query | Phone number, for example `+14155552671` or `07911 123456` | string | Yes | - | - |
| `country` | query | Two-letter country code used when the number has no `+` prefix, for example `GB` | string | No | - | 2 letters |

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "input": "+14155552671",
  "valid": true,
  "possible": true,
  "type": "fixed_line_or_mobile",
  "e164": "+14155552671",
  "international": "+1 415 555 2671",
  "national": "(415) 555-2671",
  "rfc3966": "tel:+14155552671",
  "country_code": "US",
  "country_name": "United States",
  "calling_code": "+1",
  "national_number": "4155552671",
  "extension": null,
  "error": null
}
```

A number that cannot be placed in a country returns `valid: false` with an `error`:

```json
{
  "input": "12345",
  "valid": false,
  "possible": false,
  "type": null,
  "e164": null,
  "international": null,
  "national": null,
  "rfc3966": null,
  "country_code": null,
  "country_name": null,
  "calling_code": null,
  "national_number": null,
  "extension": null,
  "error": "missing_country_or_plus_prefix"
}
```

#### 2. Validate up to 100 numbers

Validates a list of numbers in one call, with an optional default country for national numbers.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `phones` | body | List of phone numbers | array of strings | Yes | - | 100 numbers |
| `country` | body | Default two-letter country code for numbers without a `+` prefix | string | No | - | 2 letters |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/rasareka/phone-validator/phone/v1/validate-bulk' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phones": ["+447911123456", "020 7946 0958", "+919876543210"], "country": "GB"}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "valid": 3,
  "invalid": 0,
  "results": [
    {
      "input": "+447911123456",
      "valid": true,
      "possible": true,
      "type": "mobile",
      "e164": "+447911123456",
      "international": "+44 7911 123456",
      "national": "07911 123456",
      "rfc3966": "tel:+447911123456",
      "country_code": "GG",
      "country_name": "Guernsey",
      "calling_code": "+44",
      "national_number": "7911123456",
      "extension": null,
      "error": null
    },
    {
      "input": "020 7946 0958",
      "valid": true,
      "possible": true,
      "type": "fixed_line",
      "e164": "+442079460958",
      "international": "+44 20 7946 0958",
      "national": "020 7946 0958",
      "rfc3966": "tel:+442079460958",
      "country_code": "GB",
      "country_name": "United Kingdom",
      "calling_code": "+44",
      "national_number": "2079460958",
      "extension": null,
      "error": null
    }
  ]
}
```

The `results` list above is shortened to two of the three numbers.

#### 3. List supported countries

Returns every supported country with its code and calling code.

**Method:** `GET`

**Endpoint:** `/phone/v1/countries`

**Parameters:**

None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/phone-validator/phone/v1/countries' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "count": 245,
  "countries": [
    {
      "code": "AF",
      "name": "Afghanistan",
      "calling_code": "+93"
    },
    {
      "code": "AX",
      "name": "Åland Islands",
      "calling_code": "+358"
    },
    {
      "code": "AL",
      "name": "Albania",
      "calling_code": "+355"
    }
  ]
}
```

The `countries` list above is shortened to three of 245 entries.

#### 4. Example number for a country

Returns an example mobile number for a country in each format, useful for form placeholders.

**Method:** `GET`

**Endpoint:** `/phone/v1/example`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `DE` | string | Yes | - | 2 letters |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/phone-validator/phone/v1/example?country=DE' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "example": {
    "e164": "+4915123456789",
    "international": "+49 1512 3456789",
    "national": "01512 3456789"
  }
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 400 | Bad Request | A required parameter is missing or invalid. The body has an `error` code and a `message`. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 429 | Too Many Requests | You went over 10 requests per second or used up the quota of your plan. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second, and each subscription plan has its own monthly quota. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Does it check that the number is switched on?**
    No. It checks that the number is valid and possible for its country and returns the line type. It does not call or message the number.

*   **Why did a UK number come back as Guernsey?**
    Some UK number ranges belong to the Crown Dependencies. The country follows the number range, while the calling code stays `+44`.

*   **When do I need country?**
    Only for national numbers without a `+` prefix, such as `020 7946 0958`.

*   **What is fixed_line_or_mobile?**
    In the US and Canada mobile and landline numbers share the same ranges, so the type cannot be told apart from the number alone.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Validate and format phone numbers for 245 countries: valid flag, mobile, landline or VoIP type, E.164 and national formats. Up to 100 per call.

Phone Number Validation API: Format, Type and Country

Free trial

rasareka

PAYG

Validate and format phone numbers for 245 countries: valid flag, line type (mobile, landline, VoIP), E.164 and national formats, country. Bulk 100 per call.