Phone Verification API

POSTv1

Authentication

x-authkey: YOUR_API_KEY

Endpoint

POST /phone-verification

Parameters

Name	Type	Required
number	STRING	Required

Code Examples

Sample Response

{
  "data": {
    "valid": true,
    "number": "+18005551234",
    "abusive": false,
    "carrier": "",
    "is_voip": false,
    "rfc3966": "tel:+1-800-555-1234",
    "location": "Unknown",
    "possible": true,
    "timezone": "America/Adak",
    "is_mobile": false,
    "line_type": "Toll Free",
    "timezones": [
      "America/Adak",
      "America/Anchorage",
      "America/Anguilla",
      "America/Antigua",
      "America/Barbados",
      "America/Boise",
      "America/Cayman",
      "America/Chicago",
      "America/Denver",
      "America/Dominica",
      "America/Edmonton",
      "America/Fort_Nelson",
      "America/Grand_Turk",
      "America/Grenada",
      "America/Halifax",
      "America/Jamaica",
      "America/Juneau",
      "America/Los_Angeles",
      "America/Lower_Princes",
      "America/Montserrat",
      "America/Nassau",
      "America/New_York",
      "America/North_Dakota/Center",
      "America/Phoenix",
      "America/Port_of_Spain",
      "America/Puerto_Rico",
      "America/Regina",
      "America/Santo_Domingo",
      "America/St_Johns",
      "America/St_Kitts",
      "America/St_Lucia",
      "America/St_Thomas",
      "America/St_Vincent",
      "America/Toronto",
      "America/Tortola",
      "America/Vancouver",
      "America/Winnipeg",
      "Atlantic/Bermuda",
      "Pacific/Guam",
      "Pacific/Honolulu",
      "Pacific/Pago_Pago",
      "Pacific/Saipan"
    ],
    "risk_level": "low",
    "risk_score": 30,
    "e164_format": "+18005551234",
    "country_code": "US",
    "country_name": "Unknown",
    "is_toll_free": true,
    "local_format": "(800)5551234",
    "is_disposable": false,
    "is_fixed_line": false,
    "country_prefix": "+1",
    "is_premium_rate": false,
    "national_format": "(800) 555-1234",
    "international_format": "+1 800-555-1234"
  },
  "status": "success"
}

Validation & Risk Analysis

The core of the API. We determine if the number is real, active, and safe to contact.

Use `risk_score` and `abusive` to automatically block burner phones and potential fraudsters.

Key Name	Type	Description
valid	Boolean	Returns `true` if the number is assigned to a real region and follows valid syntax.
possible	Boolean	Returns `true` if the number has the correct number of digits for its country (even if not currently active).
risk_score	Integer	A score from 0 (Safe) to 100 (High Risk). See the Risk Guide below.
risk_level	String	A summary verdict: 'low', 'medium', or 'high'.
abusive	Boolean	Returns `true` if the number is associated with high-risk behavior (e.g., VOIP, Disposable, Premium Rate).
is_disposable	Boolean	Returns `true` if the number belongs to a temporary SMS service (like TextNow, Burner, Google Voice).
is_premium_rate	Boolean	Returns `true` if calling this number costs extra money (e.g., 900 numbers).

Line Type & Carrier Info

Understand exactly what kind of device is behind the number.

Crucial for SMS marketing (you cannot send SMS to Fixed Lines) and anti-fraud (VOIP is often used by bots).

Key Name	Type	Description
line_type	String	The classification of the number. Values: 'Mobile', 'Fixed Line', 'Toll Free', 'VOIP', etc.
carrier	String	The name of the service provider (e.g., 'Verizon', 'T-Mobile', 'Google Voice'). May be empty for some regions.
is_mobile	Boolean	Returns `true` if the number is a cellular phone capable of receiving SMS.
is_fixed_line	Boolean	Returns `true` if the number is a landline.
is_voip	Boolean	Returns `true` if the number is Virtual/Internet-based. High correlation with bots and fraud.
is_toll_free	Boolean	Returns `true` if the number is free to call (e.g., 800 numbers).

Standardized Formats

Stop storing messy phone numbers. We parse inputs like `(800) 555-1234` and return clean, database-ready formats.

Key Name	Example	Description
e164_format	+18005551234	The global database standard. Use this for storage.
national_format	(800) 555-1234	How the number should be displayed to a user in the same country.
international_format	+1 800-555-1234	How the number should be displayed to international users.
rfc3966	tel:+1-800-555-1234	The URI format used for 'Click-to-Call' links in HTML.
country_prefix	+1	The dialing code for the country.

Location & Timezone

Geographic data derived from the area code and carrier details.

Use `timezone` to prevent calling customers in the middle of the night.

Key Name	Type	Description
country_code	String	Two-letter ISO code (e.g., 'US', 'CA', 'GB').
country_name	String	Full English name of the country.
location	String	The specific region, state, or city associated with the area code.
timezone	String	The primary timezone for this number (e.g., 'America/New_York').
timezones	Array	A list of all possible timezones (if the area code spans multiple zones).

Risk Score Guide

How to interpret the `risk_score` (0-100).

Score	Level	Meaning
0 - 39	Low	Standard mobile or landline. Safe to trust.
40 - 69	Medium	Toll-free or unknown line type. Acceptable, but maybe verify.
70 - 100	High	VOIP, Disposable, or Premium Rate. Likely a bot, scammer, or burner phone.