> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Validation API

> Cleariflow Phone Number Validation API is a fast, lightweight RESTful JSON API for structural phone number validation, E.164 normalization, and optional carrier, location, timezone, and dialability details.

It's very simple to use: submit your API key and a phone number. The API returns whether the number is **structurally valid** and, when valid, normalized E.164 formats plus optional details such as line type, location hints, carrier data, timezones, and dialability where available.

<Note>
  `valid: true` means the number matches regional format rules (length, prefix, syntax). It does **not** confirm the line is active, assigned to a subscriber, or reachable. For live line status you need carrier lookup, which is outside this API.
</Note>

## Getting started

### REST

The Phone Number Validation API, like all Cleariflow APIs, is organized around REST. It is designed to use predictable, resource-oriented URLs and HTTP status codes to indicate errors.

### HTTPS

The Phone Number Validation API requires all communications to be secured with TLS 1.2 or greater.

### API Versions

All Cleariflow APIs are versioned. The Phone Number Validation API is currently on Version 1.

### Your API Key

Your API key is your unique authentication key for the Cleariflow Phone Number Validation API. Note that each Cleariflow API has a unique API key, so you will need different keys to access the Phone Number Validation and Email Validation APIs, for example. To authenticate your requests, append your API key to the base URL.

### Base URL

```
https://phonevalidation.cleariflow.com/v1/
```

### What `valid` means

| `valid` | Meaning                                                                                                                                                                                                                                                                                                                                                        |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | The number is structurally valid for its detected region.                                                                                                                                                                                                                                                                                                      |
| `false` | The number could not be parsed or fails regional format rules. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical`, and `internationally_dialable` are always empty or false; `possible` and `invalid_reason` are still populated when the input could be parsed. `phone` contains digits from your input only. |

Fictional US 555 numbers and other structurally valid but unassigned ranges may still return `valid: true`. `carrier` and `location` are populated mainly for US/CA numbers and are often empty elsewhere.

### Validation endpoint

The API requires your unique API key and the phone number to check:

```
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
```

**Valid response** (`phone=14155552671`, `country=US`):

<ResponseExample>
  ```json theme={"system"}
  {
    "phone": "14155552671",
    "valid": true,
    "possible": true,
    "format": {
      "international": "+14155552671",
      "local": "(415) 555-2671"
    },
    "country": {
      "code": "US",
      "name": "United States",
      "prefix": "+1"
    },
    "location": "San Francisco, CA",
    "type": "Landline_or_Mobile",
    "carrier": "",
    "carrier_display": "",
    "timezones": ["America/Los_Angeles"],
    "geographical": true,
    "internationally_dialable": true
  }
  ```
</ResponseExample>

**Invalid response** (`phone=123`, `country=US`):

```json theme={"system"}
{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}
```

### Request parameters

<ParamField query="api_key" type="String" required>
  Your unique API key. Note that each user has unique API keys *for each of
  Cleariflow APIs*, so your Phone Validation API key will not work for your IP
  Geolocation API, for example.
</ParamField>

<ParamField query="phone" type="String" required>
  The phone number to validate.
</ParamField>

<ParamField query="country" type="String">
  Optional ISO 3166-1 alpha-2 hint for national-format numbers without a leading `+`. For example, `country=US` helps parse `4155552671`. Numbers with an international prefix are parsed from their country code; the detected `country.code` in the response may differ from this hint (e.g. `GG` for some `+44` mobile ranges).
</ParamField>

### Response parameters

The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).

<ResponseField name="phone" type="String">
  Normalized E.164 digits (without `+`) when `valid` is true. When `valid` is false, digits from your input only.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  `true` when the number is structurally valid. This is **not** line-status or subscriber verification.
</ResponseField>

<ResponseField name="possible" type="Boolean">
  Lenient length check. `true` when the digits and length could belong to a real number, even if `valid` is false.
</ResponseField>

<ResponseField name="invalid_reason" type="String">
  Present when `valid` is false. One of: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Omitted when `valid` is true.
</ResponseField>

<ResponseField name="format" type="Object">
  `international` and `local` formats. Empty strings when `valid` is false.
</ResponseField>

<ResponseField name="format.international" type="String">
  E.164 format with a leading `+`. Empty when `valid` is false.
</ResponseField>

<ResponseField name="format.local" type="String">
  National format for the detected region. Empty when `valid` is false.
</ResponseField>

<ResponseField name="country" type="Object">
  Detected country/territory. Empty fields when `valid` is false.
</ResponseField>

<ResponseField name="country.code" type="String">
  Two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the detected region.
</ResponseField>

<ResponseField name="country.name" type="String">
  English display name for `country.code`.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  International [calling code prefix](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (e.g. `+1`).
</ResponseField>

<ResponseField name="location" type="String">
  Location hint (region, state/province, or city). Often empty outside US/CA. Empty when `valid` is false.
</ResponseField>

<ResponseField name="type" type="String">
  Line type when `valid` is true: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special`, or `Unknown`. Always `Unknown` when `valid` is false.
</ResponseField>

<ResponseField name="carrier" type="String">
  Carrier name when available (most often US/CA). Empty string otherwise, including when `valid` is false.
</ResponseField>

<ResponseField name="carrier_display" type="String">
  Safe carrier name for end-user display (when valid and the region does not use mobile number portability). Empty when `valid` is false or the carrier cannot be shown safely.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Timezone identifiers for the number (e.g. `America/New_York`). Empty array when `valid` is true but no mapping exists; `null` when `valid` is false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Whether the number is associated with a geographic region. Always `false` when `valid` is false.
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  Whether the number can be dialed from outside its home region. Always `false` when `valid` is false.
</ResponseField>

## Bulk upload (CSV)

Here are some best practices when bulk uploading a CSV file:

* Ensure the first column contains the phone numbers to be analyzed.
* Remove any empty rows from the file.
* Include only one phone number per row.
* The maximum file size permitted is 50,000 rows.

## Response and error codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

| Code | Type                  | Details                                                                                                                                                     |
| ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Everything worked as expected.                                                                                                                              |
| 400  | Bad request           | Bad request.                                                                                                                                                |
| 401  | Unauthorized          | The request was unacceptable. Typically due to the API key missing or incorrect.                                                                            |
| 422  | Quota reached         | The request was aborted due to insufficient API credits. (Free plans)                                                                                       |
| 429  | Too many requests     | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
| 500  | Internal server error | The request could not be completed due to an error on the server side.                                                                                      |
| 503  | Service unavailable   | The server was unavailable.                                                                                                                                 |

## Other notes

A note on metered billing: Each individual phone number you submit counts as a credit used. Credits are also counted per request, not per successful response. So if you submit a request for the (invalid) phone number "kasj8929hs", that still counts as 1 credit.