Phone Validator API: Complete Integration Guide for US Developers

The RealValidito Phone Validator API validates any US or Canada phone number in real time — returning line type, carrier, DNC status, and geographic data in a single JSON call.

What the Phone Validator API Returns

Every successful API call to POST /phonelookup/validate returns a structured JSON response with all of the following fields:

• valid — whether the number is a valid NANP number
• active — whether the number is currently in service
• line_type — Mobile, Landline, VoIP, Toll-Free, Prepaid, or Pager
• carrier — current serving carrier name
• original_carrier — issuing carrier (detects number portability)
• city, state, zip, area_code, timezone — geographic intelligence
• dnc — Federal Do Not Call registry status
• tcpa_litigant — flag for known TCPA lawsuit filers

Response time is consistently under 1 second. The API runs against a continuously updated database synchronized with 100+ authoritative carrier and regulatory sources.

Authentication and Endpoint

Authentication uses a two-key system passed in the POST body. There are no OAuth flows, no session tokens — just your api_key and api_secret per request.

POST https://app.realvalidito.com/phonelookup/validate
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "api_secret": "YOUR_API_SECRET",
  "phone": "5551234567"
}

Integration Examples by Language

PHP

<?php
$payload = json_encode([
    'api_key'    => 'YOUR_API_KEY',
    'api_secret' => 'YOUR_API_SECRET',
    'phone'      => '5551234567',
]);
$ch = curl_init('https://app.realvalidito.com/phonelookup/validate');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
echo $result['line_type']; // e.g. "Mobile"

Python

import requests

response = requests.post(
    'https://app.realvalidito.com/phonelookup/validate',
    json={
        'api_key':    'YOUR_API_KEY',
        'api_secret': 'YOUR_API_SECRET',
        'phone':      '5551234567',
    }
)
data = response.json()
print(data['carrier'])  # e.g. "T-Mobile"

JavaScript (Node.js)

const resp = await fetch('https://app.realvalidito.com/phonelookup/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key:    'YOUR_API_KEY',
    api_secret: 'YOUR_API_SECRET',
    phone:      '5551234567',
  }),
});
const data = await resp.json();
console.log(data.dnc); // true or false

Checking Your Credit Balance

Monitor remaining credits at any time without consuming a lookup credit:

GET https://app.realvalidito.com/phonelookup/getcredits/{api_key}/{api_secret}

Batch Processing: Up to 50,000 Numbers

For high-volume validation, skip the per-call API and use CSV batch upload through the dashboard. Upload a file with up to 50,000 phone numbers, get a clean results export — all deducted from your credit balance at the standard per-lookup rate. No credits are charged for blank rows or format errors.

TCPA Compliance Use Case

Every response includes two compliance-critical fields: dnc (Federal Do Not Call registry match) and tcpa_litigant (known TCPA lawsuit plaintiff). Integrating these checks before your outbound dialer or SMS campaign eliminates your exposure to TCPA penalties of $500–$1,500 per violation.

A recommended pre-dial filter:

if ($result['dnc'] || $result['tcpa_litigant'] || !$result['active']) {
    // Skip this number — do not dial
}