Phone Validation API

Cleariflow Phone Number Validation API is a fast, lightweight RESTful JSON API for structural phone number validation (libphonenumber), E.164 normalization, and optional carrier/location metadata.

GET /v1

Phone Validation API

cURL

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "[phone]",
    "local": "[phone]"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}

It’s very simple to use: submit your API key and a phone number. The API returns whether the number is structurally valid (per Google libphonenumber) and, when valid, normalized E.164 formats plus optional metadata such as line type, geocoding hints, and carrier data where available.

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 HLR/SMS lookup, which is outside this API.

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 (libphonenumber IsValidNumber).
false	The number could not be parsed or fails regional format rules. format, country, location, type, and carrier are always empty; 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 from US/CA metadata 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):

{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "[phone]",
    "local": "[phone]"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}

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

{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

Request parameters

api_key · 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.

phone · String · required

The phone number to validate (structural check per libphonenumber).

country · 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).

Response parameters

The API response is returned in a universal and lightweight JSON format.

phone · String

Normalized E.164 digits (without +) when valid is true. When valid is false, digits from your input only.

valid · Boolean

true when the number is structurally valid per libphonenumber. This is not line-status or subscriber verification.

format · Object

international and local formats. Empty strings when valid is false.

format.international · String

E.164 format with a leading +. Empty when valid is false.

format.local · String

National format for the detected region. Empty when valid is false.

country · Object

Detected country/territory. Empty fields when valid is false.

country.code · String

Two-letter ISO 3166-1 alpha-2 code for the detected region.

country.name · String

English display name for country.code.

country.prefix · String

International calling code prefix (e.g. +1).

location · String

Geocoding hint from libphonenumber metadata (region, state/province, or city). Often empty outside US/CA. Empty when valid is false.

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.

carrier · String

Carrier name from libphonenumber metadata when available (most often US/CA). Empty string otherwise, including when valid is false.

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.