Disconnected number check API

Disconnected number check API for US and Canadian numbers

Every CheckThatPhone lookup includes a check for recent carrier deactivations. When a carrier deactivated the number in the last 45 days, the response returns deactivationDate, action: "unsubscribe", deliverable: "false" and a reason such as "Number deactivated by carrier id 6010 on 2026-10-02", so you can drop the number before you call or text it.

Our deactivation data refreshes daily, with a 1 to 7 day lag between a carrier deactivation and the field appearing. It is not a reassigned-number check and not a live network ping. One POST /v1/lookup call costs one credit, and the Free plan includes 500 lookups a month.

Get a free API key Deliverability fields in the docs →

The fields that flag a disconnected number

Values are strings, including booleans.

FieldExampleMeaning
deactivationDate "2026-10-02" Date of the most recent carrier deactivation, when known. Refreshed daily, 1 to 7 days behind the carrier. Entries expire after 45 days, and the field clears as soon as the number is reactivated.
action "unsubscribe" Recommended SMS list action: "send", "unsubscribe" or "error". A carrier deactivation in the last 45 days is one of the triggers for "unsubscribe".
reason "Number deactivated by carrier id 6010 on 2026-10-02" Why action is what it is. A deactivation reads "Number deactivated by carrier id <N> on <date>".
deliverable "false" Reachability summary covering line type, blacklist, litigator filter and the 45-day deactivation check. Always agrees with action. Not a real-time delivery probe.
doNotSms "true" Present as "true" when the number can't receive SMS, including when it was deactivated. Its inverse, smsEligible, is present when it can.
blackList "false" "true" when the number is on our internal blacklist of flagged numbers, or when the litigator filter matched. Not a do-not-call registry check.

What to do with each response

ResponseWhat it meansWhat to do
deactivationDate set, action: "unsubscribe", reason: "Number deactivated by carrier id … on …" The carrier deactivated the number on that date, within the last 45 days, and it hasn't been reactivated since. Don't call or text it. Suppress the contact and store the date. If a later lookup shows the number active again, it may belong to someone new: confirm before you contact it.
action: "send", deliverable: "true", no deactivationDate A reachable, SMS-eligible number with no carrier deactivation on record, allowing for the 1 to 7 day lag. Fine to send. It doesn't prove the same person still has the number.
action: "unsubscribe", reason: "Not a valid mobile number" Not SMS-eligible: a landline, VoIP or other non-mobile line. This alone is not a disconnection. Don't text it. Call instead, or find text-enabled landlines with the landline SMS lookup.
action: "unsubscribe", reason: "Blacklisted Subscriber", blackList: "true" The number is on our internal blacklist of flagged numbers. Don't message it.
action: "error" The request was malformed: a missing or invalid phone. Fix the input. Retrying the same request returns the same error.

action is an SMS recommendation, so a working landline also reads "unsubscribe". For a disconnection signal, read deactivationDate and the reason, not action alone. Line type is covered on the line type lookup API page.

Example request and response

curl --request POST \
  --url 'https://api.checkthatphone.com/v1/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"phone": "602-555-0137"}'

An illustrative response for a mobile number its carrier deactivated six days before the lookup (a fictional 555 number; field names and formats match the live API): 

{
  "success": true,
  "credits_used": 1,
  "data": {
    "subscriber": "6025550137",
    "optDate": "2026-10-08T16:24:51.207Z",
    "action": "unsubscribe",
    "deliverable": "false",
    "reason": "Number deactivated by carrier id 6010 on 2026-10-02",
    "deactivationDate": "2026-10-02",
    "nanpType": "mobile",
    "blackList": "false",
    "dip": "success",
    "dipLrn": "6025550137",
    "dipPorted": "false",
    "dipOcn": "6010",
    "dipCarrierSubType": "WIRELESS",
    "dipCarrier": "AT&T",
    "dipCarrierType": "mobile",
    "geoState": "AZ",
    "geoCity": "phoenix",
    "geoCountry": "US",
    "timezone": "America/Phoenix",
    "tzOffset": 7,
    "geoSource": "area-code",
    "error": "false",
    "doNotSms": "true"
  }
}

credits_used: 1 is the whole cost of this call. The same lookup also returns the carrier, porting status (see the LRN lookup API), line type and location.

Where to run it

Limits worth knowing

Pricing

The deactivation check is part of every lookup: one credit, no separate fee. The Free plan has 500 lookups a month, hard-capped. Paid plans are $5 for 1,000, $30 for 10,000, $100 for 100,000 and $450 for 500,000 lookups a month, with overage from $0.005 down to $0.0009 per lookup. Failed lookups are free. See pricing.

Disconnected number check: common questions

How do I check if a phone number is disconnected?

Send it to POST /v1/lookup. If its carrier deactivated it in the last 45 days and it hasn't been reactivated, the response carries deactivationDate, action: "unsubscribe", deliverable: "false" and a reason like "Number deactivated by carrier id 6010 on 2026-10-02". The check is part of every lookup.

How current is the deactivation data?

It refreshes daily, and there is a 1 to 7 day lag between a carrier deactivating a number and deactivationDate appearing. A number disconnected in the last few days can still look active, so check as close to the send as you can.

Does it tell me if a number has been reassigned to someone new?

No. Once a number is reactivated, deactivationDate clears, whether the number went back to the same subscriber or to a new one. The FCC's Reassigned Numbers Database is built for the reassignment question.

Does the API call or text the number?

No. Nothing is sent to the phone. The lookup reads carrier data, and deliverable is a reachability summary, not a real-time delivery probe. Carriers don't guarantee delivery.

Does a landline that returns "unsubscribe" mean it is disconnected?

No. action is an SMS list recommendation, so a working landline returns "unsubscribe" with the reason "Not a valid mobile number" because it isn't a mobile number. For a disconnection, look for deactivationDate and a "Number deactivated" reason.

How much does a disconnected number check cost?

One credit per lookup, with no extra fee for the deactivation check. The Free plan includes 500 lookups a month, hard-capped; paid plans start at $5 a month for 1,000 lookups. Failed lookups are not billed. See pricing.

Related

Try it on your list

Free tier: 500 lookups per month, hard-capped. Paid plans start at $5/month.

Get API access Read the docs