API Documentation

CheckThatPhone API v4 — accessed via RapidAPI. Validate US & Canada phone numbers with real-time carrier data.

GET https://checkthatphone.p.rapidapi.com/api

Authentication

Authenticate via RapidAPI headers. Get your API key by subscribing on RapidAPI.

Header Value
x-rapidapi-host checkthatphone.p.rapidapi.com
x-rapidapi-key Your RapidAPI subscription key
Content-Type application/json

Query Parameters

Parameter Required Description
phone Yes US or Canada phone number to validate (10 digits, no formatting)
ip No IP address of the phone owner/customer being validated. Provides precise GeoIP and timezone enrichment when available.

API v2 note: phone replaces the former subscriber parameter. ip replaces optIp. The optDate input parameter has been removed.

Code Examples

cURL

curl --request GET \
  --url 'https://checkthatphone.p.rapidapi.com/api?phone=8182925409&ip=136.38.145.14' \
  --header 'Content-Type: application/json' \
  --header 'x-rapidapi-host: checkthatphone.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY'

JavaScript

const response = await fetch(
  'https://checkthatphone.p.rapidapi.com/api?phone=8182925409&ip=136.38.145.14',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'x-rapidapi-host': 'checkthatphone.p.rapidapi.com',
      'x-rapidapi-key': 'YOUR_RAPIDAPI_KEY',
    },
  }
);
const data = await response.json();
console.log(data);

Python

import requests

url = "https://checkthatphone.p.rapidapi.com/api"
querystring = {"phone": "8182925409", "ip": "136.38.145.14"}
headers = {
    "Content-Type": "application/json",
    "x-rapidapi-host": "checkthatphone.p.rapidapi.com",
    "x-rapidapi-key": "YOUR_RAPIDAPI_KEY"
}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

Example Response

{
  "subscriber": "8182925409",
  "optDate": "2024-08-15T18:55:56.532Z",
  "action": "send",
  "deliverable": "true",
  "nanpType": "mobile",
  "blackList": "false",
  "ipResult": "valid-v4",
  "dip": "success",
  "dipLrn": "8182925409",
  "dipPorted": "false",
  "dipOcn": "6010",
  "dipCarrier": "AT&T",
  "dipCarrierSubType": "WIRELESS",
  "dipCarrierType": "mobile",
  "geoCountry": "US",
  "geoCity": "Riverside",
  "geoMetro": 803,
  "geoSource": "ip",
  "timezone": "America/Los_Angeles",
  "tzOffset": 8
}

Response Fields

Subscriber Info

Field Type Description Example
subscriber string The phone number that was queried. "8182925409"
optDate string ISO 8601 timestamp of when the query was processed. "2024-08-15T18:55:56.532Z"

Deliverability

Field Type Description Example
action string Recommended action for this number. "send" indicates the number is valid and deliverable. "send"
deliverable string Whether the phone number can currently receive calls and SMS messages. "true"
nanpType string Line type based on the North American Numbering Plan. Values: "mobile", "landline", "voip", "tollfree", etc. "mobile"
blackList string Whether the number appears on the platform's internal blacklist of flagged numbers. Not a DNC or third-party list. "false"

Carrier DIP

Field Type Description Example
dip string Status of the carrier DIP (Database Dip) lookup. "success" means carrier data was retrieved. "success"
dipLrn string Local Routing Number — the number used for actual call/SMS routing. Critical for ported numbers. "8182925409"
dipPorted string Whether the number has been ported (transferred) to a different carrier than originally assigned. "false"
dipOcn string Operating Company Number — a unique identifier code for the current carrier operating this number. "6010"
dipCarrier string Human-readable name of the carrier currently operating this phone number. "AT&T"
dipCarrierSubType string Sub-classification of the carrier type. Values: "WIRELESS", "WIRELINE", etc. "WIRELESS"
dipCarrierType string Broad category of the carrier type. Values: "mobile", "landline". "mobile"

GeoIP

Field Type Description Example
ipResult string Validation result for the IP address provided with the request. Only populated when an IP parameter is included. "valid-v4"

Geolocation

Field Type Description Example
geoCountry string Two-letter country code where the number is registered. "US"
geoCity string City associated with the phone number, derived from the area code or the provided IP address. "Riverside"
geoMetro number Metro area code (DMA code) for the geographic region of the phone number. 803
geoSource string Source of the geographic data. "ip" when derived from a provided IP address, "npa" when derived from the area code. "ip"
timezone string IANA timezone identifier for the phone number's location. "America/Los_Angeles"
tzOffset number UTC offset in hours for the phone number's timezone. 8

Ready to get started?

Choose a plan and start validating phone numbers in minutes.

View Pricing