Phone validation API documentation

Real-time validation of US and Canada phone numbers: live carrier dip, line type, portability, deliverability, and geolocation in a single REST call. Sign up for a free API key (500 lookups/month, hard-capped).

Authentication

Pass the API key from your dashboard as a bearer token in the Authorization header. Keep it secret: anyone with the key can spend your credits.

Request Body

Send a JSON body with the following fields:

Response Envelope

Every response is wrapped in a standard envelope:

Official SDKs

Zero-dependency, typed clients that cover the full API surface including all add-on flags. Both are MIT-licensed and open source on GitHub.

• Node.js — npm install checkthatphone (checkthatphone-node, Node 18+, TypeScript types included)
• Python — pip install checkthatphone (checkthatphone-python, Python 3.9+, standard library only)

Code Examples

cURL

curl --request POST \
  --url 'https://api.checkthatphone.com/v1/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"phone":"8182925409","ip":"136.38.145.14","litigatorFilter":false,"landlineSmsLookup":false,"dncState":false,"dncComplainer":false}'

JavaScript

const response = await fetch('https://api.checkthatphone.com/v1/lookup', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '8182925409',
    ip: '136.38.145.14',
    litigatorFilter: false,
    landlineSmsLookup: false,
  }),
});
const result = await response.json();
console.log(result.data);

Python

import requests

response = requests.post(
    'https://api.checkthatphone.com/v1/lookup',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'phone': '8182925409',
        'ip': '136.38.145.14',
        'litigatorFilter': False,
        'landlineSmsLookup': False,
    },
)
result = response.json()
print(result['data'])

With add-on features

# Enable add-ons per request. litigatorFilter and landlineSmsLookup are paid;
# dncState and dncComplainer (the DNC checks) are free.
curl --request POST \
  --url 'https://api.checkthatphone.com/v1/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"phone":"8182925409","litigatorFilter":true,"landlineSmsLookup":true,"dncState":true,"dncComplainer":true}'

Example Response

{
  "success": true,
  "credits_used": 1,
  "data": {
    "subscriber": "4155551234",
    "optDate": "2026-05-23T06:58:42.048Z",
    "action": "send",
    "deliverable": "true",
    "reason": "",
    "nanpType": "mobile",
    "blackList": "false",
    "dip": "success",
    "dipLrn": "4155551234",
    "dipPorted": "false",
    "dipOcn": "6214",
    "dipCarrier": "AT&T",
    "dipCarrierSubType": "WIRELESS",
    "dipCarrierType": "mobile",
    "geoState": "CA",
    "geoCity": "san francisco",
    "geoCountry": "US",
    "geoSource": "area-code",
    "timezone": "America/Los_Angeles",
    "tzOffset": 8,
    "error": "false"
  }
}

Response Fields

All fields below appear inside data on the response envelope. Fields in the Landline SMS Lookup, Litigator Filter, and State DNC & Complainers groups are only present when the corresponding request flag is enabled.

Errors

Standard HTTP status codes apply. The response envelope carries a structured error when applicable.