Reference

API Documentation

Real-time validation of US and Canada phone numbers: 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:

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}'

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

# Set litigatorFilter and/or landlineSmsLookup to true to enable add-ons
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}'

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 and Litigator Filter 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.