v1.5.0
OpenAPI 3.1.0

Introduction

Check a US or Canada phone number with one request. You get the current carrier and line type from a live carrier dip, whether the number was ported, whether it was deactivated recently, a send-or-unsubscribe recommendation for messaging with the reason, and the location and time zone. A live carrier dip means we ask the carrier network at the moment you call, not a stored list.

Optional add-ons check the number against known TCPA litigators, tell you if a landline can receive SMS, and run free state do-not-call and complainer checks.

Quick start

  1. Sign up and copy your API key from the dashboard. Free accounts get 500 credits a month.
  2. Send a POST request to https://api.checkthatphone.com/v1/lookup. Put the key in the Authorization header and the phone number in a JSON body.
  3. The result is in data. credits_used shows how many credits the call used.
curl --request POST \
  --url https://api.checkthatphone.com/v1/lookup \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"phone":"8182925409"}'

If you have the IP address of the person who gave you the number (for example from your signup or lead form), send it in ip to get a more exact location than the area code gives. Turn on add-ons for one request with litigatorFilter, landlineSmsLookup, dncState and dncComplainer. Every response field is explained in the Response fields section below the endpoint. The Test Request button sends real requests and uses credits from your account.

Authentication

Send your API key as a bearer token with every request:

Header Value
Authorization Bearer YOUR_API_KEY
Content-Type application/json

Keep the key secret. Anyone who has it can use your credits. You can create and delete keys in the dashboard. A key you type into this page stays in your browser tab. We do not store it.

Server:https://api.checkthatphone.com/v1

Production

Client Libraries

Zero dependencies, Node 18+, TypeScript types included. Source on GitHub.

npm install checkthatphone

Lookup

​

One endpoint. One POST returns everything we know about a number.

Lookup Operations

Validate a US or Canada phone number

​

Returns the carrier and line type from a live carrier dip, whether the number was ported, whether it was deactivated recently, deliverability (a send or unsubscribe recommendation with the reason), and the location and time zone for a US or Canada number. Add the IP address of the person who gave you the number for a more exact location. Add-on flags run a TCPA litigator check, a landline SMS check, and free state do-not-call and complainer checks.

Body·

required
application/json
  • US or Canada phone number: 10 digits, or 11 digits starting with 1. Spaces and punctuation are ignored.

  • The IP address (IPv4 or IPv6) of the person who gave you the number, for example from your signup or lead form. With it, the location comes from the IP address, which is more exact than the area code.

  • Check the number against our TCPA litigator database (+1 credit). Adds litigator, litigator_type and litigator_name to the response.

  • Check whether a landline can receive SMS (+1 credit), charged only when the number is a landline. Adds the dipMessaging* fields. Mobile numbers are not affected.

  • Run the state do-not-call check (free). Adds dncStateChecked and dncStateResult. Covers 38 states and DC. Numbers in the other 12 states are not checked, and dncStateChecked is then missing, which means "not checked", not "clear".

  • Check the number against our national complainer list (free). Adds dncComplainerChecked and dncComplainerResult.

  • Deprecated. Use dncState and dncComplainer instead. Turns on both checks. Responses to requests that send it include a Deprecation header.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/lookup
curl https://api.checkthatphone.com/v1/lookup \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "phone": "8182925409"
}'
Phone number only
{
  "success": true,
  "credits_used": 1,
  "data": {
    "subscriber": "8182925409",
    "optDate": "2026-05-21T18:55:56.532Z",
    "action": "send",
    "deliverable": "true",
    "blackList": "false",
    "nanpType": "mobile",
    "nanpCarrier": "verizon",
    "dip": "success",
    "dipLrn": "8182925409",
    "dipPorted": "false",
    "dipOcn": "6010",
    "dipCarrier": "AT&T",
    "dipCarrierType": "mobile",
    "dipCarrierSubType": "WIRELESS",
    "geoCountry": "US",
    "geoState": "CA",
    "geoCity": "Riverside",
    "geoMetro": 803,
    "geoSource": "area-code",
    "timezone": "America/Los_Angeles",
    "tzOffset": 8,
    "smsEligible": "true"
  }
}

Response fields

​

Everything the data object can hold, in the order it is returned. Every value is a string, including "true" and "false", except the two marked as numbers. The first five groups come with every lookup. The last three appear only when you turn the add-on on, and are left out of the response otherwise.

Subscriber Info

The number you sent and when we processed it.

Field Description
subscriber The phone number that was queried.
optDate ISO 8601 timestamp of when the query was processed.

Deliverability

Our verdict, send or unsubscribe, and the reason. Every response has these.

Field Description
action Recommended SMS list action. Returns one of: "send" — the number passed the enabled technical and screening checks. This does not establish consent or legal authorization to contact the subscriber. · "unsubscribe" — don't message. Triggered by a TCPA litigator match, a non-mobile / non-SMS-capable carrier, an internal blacklist hit, or a recent carrier deactivation (up to 45 days). Check reason for the specific cause and blackList / deactivationDate for the extras. · "error" — the request was malformed (missing or invalid phone). Retrying produces the same error.
deliverable Composite reachability summary covering line type, blacklist, litigator filter, and recent-deactivation checks. Always agrees with action — "true" when action is "send", "false" when action is "unsubscribe". Not a real-time delivery probe; carriers do not guarantee actual delivery.
error "true" if an error occurred while processing this lookup. Inspect reason for details.
reason Human-readable explanation for the action. The exact strings we return: "Associated with TCPA Litigator DO NOT CONTACT" · "Not a valid mobile number" · "Blacklisted Subscriber" · "Number deactivated by carrier id <N> on <date>"
deactivationDate The date a carrier last deactivated this number. It shows for up to 45 days after the deactivation, then disappears. Temporary suspensions don't count. Our data updates daily, so a new deactivation can take 1–7 days to show up. FCC rules require carriers to age a disconnected number for at least 45 days before reassigning it to someone else (47 CFR 52.15); the same subscriber can reactivate it sooner, so a date here means a recent deactivation, not that the line is dead.
blackList "true" when the number is on our internal blacklist of flagged numbers OR when the litigator filter matched (litigator hits force this flag). Inspect reason and litigator to disambiguate which check triggered it. Distinct from the do-not-call checks — those are the dnc* fields returned by the free dncState and dncComplainer checks.
smsEligible Present as "true" when the number is eligible to receive SMS — an active mobile, or a landline confirmed SMS-capable when landlineSmsLookup: true is set. Omitted entirely when not eligible. The inverse of doNotSms.
doNotSms Present as "true" when the number is NOT eligible to receive SMS — either undeliverable (not a mobile, deactivated, or blacklisted) or a known TCPA litigator. Omitted entirely otherwise. The inverse of smsEligible.

NANP

Line type and carrier from the North American Numbering Plan records, the number's original assignment.

Field Description
nanpType Line type per the North American Numbering Plan. Values: "mobile", "landline", "not-mobile".
nanpCarrier Carrier name per NANP. Not authoritative due to number porting — prefer dipCarrier when available.

Carrier DIP

The live carrier dip: current carrier, line type, and whether the number was ported.

Field Description
dip Status of the live carrier dip lookup. One of "success", "error", "invalid".
dipLrn Local Routing Number — the number used for actual call/SMS routing. Critical for ported numbers.
dipPorted "true" when dipLrn differs from subscriber — the standard industry method for detecting that a number has been ported (transferred) to a different carrier than originally assigned.
dipOcn Operating Carrier Numeric ID — unique identifier code for the current carrier operating this number.
dipCarrier Authoritative carrier name from DIP lookup.
dipCarrierType Broad carrier type. One of "mobile", "landline", "invalid", "undefined".
dipCarrierSubType Carrier sub-type, as the carrier records classify the company that serves the number. Values: WIRELESS Wireless (mobile carrier) · PCS Personal Communications Service (mobile) · PCSR Personal Communications Service Reseller · WRSL Wireless Reseller (MVNO) · PAGING Paging and Messaging · ILEC Incumbent Local Exchange Carrier (landline) · CLEC Competitive Local Exchange Carrier (landline) · ULEC Unbundled Local Exchange Carrier · RBOC Regional Bell Operating Company · ICO Independent Telephone Company · CAP Competitive Access Provider · IXC Inter-exchange Carrier · LRSL Local Reseller · IPES Internet Protocol Enabled Services (VoIP) · ETHX Ethernet Exchange · INTL International Telecommunications Service Provider · GENERAL Unclassified The literal string "undefined" sometimes appears as noise in the carrier records; it is not a classification.

IP & Geolocation

Location and time zone. From the area code by default; more exact when you send ip.

Field Description
ipResult Validation result for the IP address provided with the request. Examples: "valid-v4", "valid-v6". Only populated when an ip parameter is included.
geoCountry Two-letter country code where the number is registered.
geoState Two-letter US state code.
geoCity City associated with the phone number, derived from the area code or the provided IP address.
geoMetro (number) Metro area code (DMA code) for the geographic region of the phone number.
geoSource Source of the geographic data. "ip" when derived from a provided IP address, "area-code" when derived from the phone number itself.
timezone IANA timezone identifier for the phone number's location.
tzOffset (number) UTC offset in hours for the phone number's timezone.

Litigator Filter

Only with litigatorFilter (+1 credit).

Field Description
litigator "true" if the subscriber is a suspected TCPA litigator. Do not contact. Returned when litigatorFilter: true is set on the request.
litigator_type Litigator classification. One of "litigator", "plaintiff", "agitator". All three carry the same recommended action ("unsubscribe") — the value is informational about how the match was classified in our source data; treat the action identically across all three.
litigator_name Name on record for the matched litigator. Present when a likely name is on record; not all matches have a name. Treat as potentially sensitive — handle carefully and do not log unnecessarily.

Landline SMS Lookup

Only with landlineSmsLookup (+1 credit, charged for landlines only). Left out of the response otherwise.

Field Description
dipMessagingLookup Present only when landlineSmsLookup: true is set and the lookup actually ran, i.e. the number is a landline: "true". Absent for mobile numbers (the lookup does not apply and is not charged) and when the add-on is not requested.
dipMessagingEnabled Returned only when landlineSmsLookup: true is set. "true" if landline messaging is enabled for this number. Only meaningful alongside dipMessagingLookup: "true".
dipMessagingProvider Name of the messaging provider serving this landline number. Populated only when the landline messaging lookup returned a positive match.
dipMessagingRefId Messaging provider's reference ID for this number.
dipMessagingCountryCode Two-letter country code of the messaging provider.

State DNC & Complainers

Only with dncState and dncComplainer (free). A missing *Checked field means the check did not run, not that the number is clear.

Field Description
dncStateChecked Present only when the state DNC check ran: "true", or "error" if it could not be completed (treat the state result as unavailable, never as clear). Absent when dncState was not requested, and for numbers in the 12 states the state check does not cover: Colorado, Florida, Indiana, Louisiana, Massachusetts, Mississippi, Missouri, Oklahoma, Pennsylvania, Tennessee, Texas and Wyoming. Absent always means "not checked", never "clear".
dncStateResult "STATE DNC" when the state do-not-call check matches the number; an empty string when it does not. Present only when dncStateChecked is "true". The state check covers 38 states plus DC, refreshed weekly.
dncComplainerChecked Present only when the complainer check ran: "true", or "error" if it could not be completed (treat the result as unavailable, never as clear). Absent only when dncComplainer was not requested.
dncComplainerResult "DNC COMPLAINER" when the number is on our national complainer list; an empty string when it is not. Present only when dncComplainerChecked is "true". The list holds roughly 700,000 numbers belonging to people who have lodged complaints against telemarketers but have not sent a demand letter or filed suit. Informational: a match never changes action.
dncOtherChecked (deprecated) Legacy. "true" when either DNC check ran, "error" if it failed; absent when neither ran. Use dncStateChecked and dncComplainerChecked, which report each check separately.
dncStateCovered (deprecated) Deprecated: use dncStateChecked. Returned whenever the state check is requested: "true" when dncStateChecked is "true", "false" otherwise. Kept so existing integrations keep working.

Credits and add-ons

​

A lookup costs one credit. Each paid add-on adds one credit. The two DNC checks are free. Failed requests (any 4xx or 5xx response) never use credits.

Request flag What it adds to data Cost
none carrier and line type (live carrier dip), ported or not, recent deactivation, deliverability (send or unsubscribe, with the reason), location and time zone 1 credit
litigatorFilter TCPA litigator check: litigator, litigator_type, litigator_name +1 credit
landlineSmsLookup Can this landline receive SMS: the dipMessaging* fields +1 credit, only for landlines
dncState State do-not-call check: dncStateChecked, dncStateResult free
dncComplainer National complainer list check: dncComplainerChecked, dncComplainerResult free

credits_used in the response and the X-Credits-Used header both show the exact number of credits used.

The state check covers 38 states and DC. Numbers in the other 12 states (Colorado, Florida, Indiana, Louisiana, Massachusetts, Mississippi, Missouri, Oklahoma, Pennsylvania, Tennessee, Texas and Wyoming) are not checked, and the response has no dncStateChecked field. A missing *Checked field means "not checked", not "clear". The DNC checks do not look at the federal Do Not Call registry, and they do not change action.

Official SDKs

​

Official clients for Node.js and Python. They have no dependencies and cover the full API, including every add-on. Both are open source (MIT) on GitHub.

  • Node.js: npm install checkthatphone (checkthatphone-node). Node 18 or newer. TypeScript types included.
  • Python: pip install checkthatphone (checkthatphone-python). Python 3.9 or newer. Standard library only.

The code samples on the endpoint above include both SDKs.

Errors and retries

​

The API uses standard HTTP status codes. An error response looks like { "error": "...", "detail": "..." }. Each status is listed on the endpoint above. In short:

  • 400: the request is wrong, for example a bad phone number. Fix it before you retry. The same request will fail again.
  • 401: the API key is missing or wrong.
  • 402: requests are paused. Either your account reached its safety limit for this billing period (contact us and we will raise it), or your last invoice is unpaid (pay it on the billing page and requests start again by themselves).
  • 429: you sent requests too fast, or a Free account used its 500 credits for the month. Slow down, or upgrade. There is no fixed published rate limit. Each account's limit grows with its billing history.
  • 502 and 503: a temporary problem on our side. Wait a moment and retry. On a 503, wait the number of seconds given in the Retry-After header.

Bulk lists

​

Have a large list? Upload a CSV in your dashboard instead of writing code. Up to 1,000,000 rows per file, the same fields for every row, and the same price per number as this API. See Features: two ways to call.

Markdown and OpenAPI

​

This reference is also available as Markdown for AI agents and as an OpenAPI 3.1 file for code generators.

Models

​
​
​
​