Phone Validation API

GET

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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

`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):

{
  "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

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.

String

required

The phone number to validate.

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.

String

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

Boolean

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

Boolean

Lenient length check. true when the digits and length could belong to a real number, even if valid is false.

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.

Object

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

String

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

String

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

Object

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

String

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

String

English display name for country.code.

String

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

String

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

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.

String

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

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.

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.

Boolean

Whether the number is associated with a geographic region. Always false when valid is false.

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.

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.

Phone Validation API

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
}

Verify

Lookup

Create

Getting started

REST

HTTPS

API Versions

Your API Key

Base URL

What `valid` means

Validation endpoint

Request parameters

Response parameters

Bulk upload (CSV)

Response and error codes

Other notes

​Getting started

​REST

​HTTPS

​API Versions

​Your API Key

​Base URL

​What valid means

​Validation endpoint

​Request parameters

​Response parameters

​Bulk upload (CSV)

​Response and error codes

​Other notes

Getting started

REST

HTTPS

API Versions

Your API Key

Base URL

What `valid` means

Validation endpoint

Request parameters

Response parameters

Bulk upload (CSV)

Response and error codes

Other notes