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 status, line type, carrier and location in a JSON response. The DNC Lookup API adds Federal, state and TCPA Litigator screening for US numbers.

What the Phone Validator API Returns

Every successful API call to POST /phonelookup/validate returns a JSON response with these fields for each number:

• status — Valid (correctly formed and assigned to a carrier) or Invalid
• phone_number, national_format, country_prefix — the number in standard formats
• number_type — Mobile, Landline, VoIP, Toll-Free or Unknown
• network_name, network_type, network_domain — the current carrier (reflects number porting)
• zip, area, city, state, country, timezone — location data

Single-number requests typically answer in well under a second. The lookup database is updated daily. DNC results come from a separate endpoint, POST /dnclookup/validate, which returns the numbers grouped as cleaned_number, tcpa_litigator, federal_dnc (with state_dnc naming any state list) and invalid. The Phone + DNC Lookup API (POST /lookups/validate) returns both results per number in one call. Full reference: RealValidito API docs.

Authentication and Endpoint

Authentication uses your API key and secret, passed in the POST body together with a numbers array. There are no OAuth flows, no session tokens — just your api_key and api_secret per request.

POST https://app.realvalidito.com/phonelookup/validate
api_key=YOUR_API_KEY
api_secret=YOUR_API_SECRET
numbers[]=5125550123
numbers[]=9085550188        (10 digits each, no +1, up to 1,000 per request)

// Response (shortened) — one entry per number:
{
  "status": "success",
  "512*******": {
    "status": "Valid",
    "phone_number": "+1512*******",
    "national_format": "(512) ***-****",
    "number_type": "Mobile",
    "zip": "78701",
    "city": "AUSTIN",
    "state": "TX",
    "country": "US",
    "timezone": "CST (America/Chicago)",
    "network_name": "CELLCO PARTNERSHIP DBA VERIZON",
    "network_type": "WIRELESS",
    "network_domain": "512*******@vtext.com"
  }
}

Integration Examples by Language

PHP

<?php
$ch = curl_init('https://app.realvalidito.com/phonelookup/validate');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'api_key'    => 'YOUR_API_KEY',
        'api_secret' => 'YOUR_API_SECRET',
        'numbers'    => ['5125550123'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
echo $result['5125550123']['number_type']; // e.g. "Mobile"

Python

import requests
response = requests.post(
    'https://app.realvalidito.com/phonelookup/validate',
    data={
        'api_key':    'YOUR_API_KEY',
        'api_secret': 'YOUR_API_SECRET',
        'numbers[]':  ['5125550123'],
    },
)
data = response.json()
print(data['5125550123']['network_name'])  # current carrier

JavaScript (Node.js)

const body = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  api_secret: 'YOUR_API_SECRET',
});
body.append('numbers[]', '5125550123');
const resp = await fetch('https://app.realvalidito.com/phonelookup/validate', { method: 'POST', body });
const data = await resp.json();
console.log(data['5125550123'].status); // "Valid" or "Invalid"

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}
GET https://app.realvalidito.com/dnclookup/getcredits/{api_key}/{api_secret}

Batch Processing: Up to 50,000 Rows per File

For large lists, use CSV upload in the web app instead of the API. Upload files with up to 50,000 rows each (up to 50 at a time) and download the results — all deducted from your credit balance at the standard per-lookup rate. Empty rows are not counted, but every phone cell in a counted row uses a credit, even if it is blank.

TCPA Compliance Use Case

The DNC Lookup API gives you two compliance-critical groups: federal_dnc (Federal or state DNC list) and tcpa_litigator (known TCPA plaintiffs and attorneys). Running these checks before your outbound dialer or SMS campaign helps reduce your exposure to TCPA penalties of $500–$1,500 per violation.

A recommended pre-dial filter:

// $phone = Phone Lookup result, $dnc = DNC Lookup result for the same number
$skip = $phone['status'] !== 'Valid'
     || in_array($n, $dnc['federal_dnc'])
     || in_array($n, $dnc['tcpa_litigator']);
if ($skip) {
    // Do not dial this number
}