US Phone Validation API Docs

Overview

The US Phone Validation API provides real-time validation and enrichment for United States phone numbers. Submit a phone number and receive carrier information, line type classification, geographic location, and formatted output. All responses include a confidence score indicating reliability.

Real-time validation with carrier detection
Line type classification (mobile, landline, VoIP)
Geographic location by area code and prefix
Automatic formatting and normalization

Authentication

All API requests require a RapidAPI key passed via the request header. Subscribe to any plan on RapidAPI to receive your API key.

Header
X-RapidAPI-Key: your-api-key

Endpoints

POST /v1/phone/validate

Validates a US phone number and returns carrier, line type, and geolocation data.

Request

Send a POST request with a JSON body containing the phone number to validate.

Parameter	Type	Required	Description
phone	string	Yes	US phone number (digits, with or without formatting)

Example Request Body

{
  "phone": "+12125550147"
}

Response

A successful validation returns a 200 status with the following JSON structure.

Field	Type	Description
status	string	valid or invalid
phone	string	Original input phone number
formatted	string	Formatted phone number (if valid)
carrier	string \| null	Wireless carrier name
location	string \| null	Geographic location (city, state)
line_type	string \| null	Line type: mobile, landline, or voip
confidence	number	Confidence score (0.0 – 1.0)

Example Response (200 OK)

{
  "status": "valid",
  "phone": "+12125550147",
  "formatted": "+1 (212) 555-0147",
  "carrier": "Verizon Wireless",
  "location": "New York, NY",
  "line_type": "mobile",
  "confidence": 0.97
}

Error Codes

Status	Code	Message	Description
400	INVALID_PHONE	Invalid phone number format	The provided phone number could not be parsed
400	MISSING_PARAM	Missing required parameter: phone	No phone number was provided in the request body
401	UNAUTHORIZED	Invalid or missing API key	The X-RapidAPI-Key header is missing or invalid
429	RATE_LIMIT	Rate limit exceeded	Request limit for your plan has been reached
500	INTERNAL_ERROR	Internal server error	An unexpected error occurred. Please try again.

Code Examples

cURL

              
curl --request POST \

  --url https://frapi-phone-v1.p.rapidapi.com/v1/phone/validate \

  --header 'X-RapidAPI-Key: your-api-key' \

  --header 'Content-Type: application/json' \

  --data '{"phone": "+12125550147"}'

Python

              
import requests

url = "https://frapi-phone-v1.p.rapidapi.com/v1/phone/validate"
headers = {
    "X-RapidAPI-Key": "your-api-key",
    "Content-Type": "application/json"
}
data = { "phone": "+12125550147" }

response = requests.post(url, json=data, headers=headers)
print(response.json())
              
            

JavaScript

              
const url = 'https://frapi-phone-v1.p.rapidapi.com/v1/phone/validate';
const options = {
  method: 'POST',
  headers: {
    'X-RapidAPI-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ phone: '+12125550147' })
};

const response = await fetch(url, options);
const data = await response.json();
console.log(data);
              
            

Rate Limits

Request limits depend on your subscription tier. Exceeding your limit returns a 429 status.

Tier	Requests / Month	Rate Limit
Starter (Free)	500	10 req/min
Pro	10,000	60 req/min
Enterprise	100,000	300 req/min

Try It Out

Test the API right in your browser. No API key required.