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. |