Skip to main content
GET
/
v1
Phone Validation API
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "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
}
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.
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.

​
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

validMeaning
trueThe number is structurally valid for its detected region.
falseThe 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): 
{
  "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
}
Invalid response (phone=123, country=US): 
{
  "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

​
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.
​
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. This is not line-status or subscriber verification.
​
possible
Boolean
Lenient length check. true when the digits and length could belong to a real number, even if valid is false.
​
invalid_reason
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.
​
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
Location hint (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 when available (most often US/CA). Empty string otherwise, including when valid is false.
​
carrier_display
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.
​
timezones
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.
​
geographical
Boolean
Whether the number is associated with a geographic region. Always false when valid is false.
​
internationally_dialable
Boolean
Whether the number can be dialed from outside its home region. Always false 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.
CodeTypeDetails
200OKEverything worked as expected.
400Bad requestBad request.
401UnauthorizedThe request was unacceptable. Typically due to the API key missing or incorrect.
422Quota reachedThe request was aborted due to insufficient API credits. (Free plans)
429Too many requestsThe 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.
500Internal server errorThe request could not be completed due to an error on the server side.
503Service unavailableThe 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.