Disconnected number check API

Disconnected number check API for US and Canadian numbers

Every lookup checks for recent carrier deactivations. When a carrier deactivated the number recently (up to 45 days), the response says so, with the date and a send-or-not answer, so you can drop the number before you call or text it.

  • Carrier data refreshed daily
  • Up to 45 days back
  • One credit per lookup
Before the next send
Number The lookup says Do this
(602) 555-0137 Deactivated by the carrier Oct 2 Suppress
(415) 555-0102 Mobile, no deactivation on record Send
(212) 555-0176 Landline, can't take texts Call only
(713) 555-0121 On our internal blacklist Don't message

Fictional 555 numbers.

The fields that flag a disconnected number

Values are strings, booleans included.

FieldExampleMeaning
deactivationDate"2026-10-02"Date of the most recent carrier deactivation, when known. Refreshed daily, 1 to 7 days behind the carrier. Final deactivations only, not temporary suspensions. Shown for up to 45 days.
action"unsubscribe"Recommended SMS list action: "send", "unsubscribe" or "error". A recent carrier deactivation (up to 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 recent-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

One rule first: action is an SMS recommendation, so a working landline also reads "unsubscribe". For a disconnection, read deactivationDate and the reason, not action alone.

If the response showsFieldDo this
Deactivated by the carrier recently (up to 45 days) deactivationDateaction = unsubscribereason 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.
Reachable, SMS-eligible, no deactivation on record action = senddeliverable = true Fine to send, allowing for the 1 to 7 day lag. It doesn't prove the same person still has the number.
A landline, VoIP or other non-mobile line action = unsubscribereason = Not a valid mobile number Not a disconnection, just not SMS-eligible. Don't text it: call instead, or find text-enabled landlines with the landline SMS lookup.
On our internal blacklist of flagged numbers blackList = truereason = Blacklisted Subscriber Don't message it.
A malformed request action = error A missing or invalid phone. Fix the input: retrying the same request returns the same error.

Example request and response

The response for a mobile number its carrier deactivated six days before the lookup. Field names and formats match the live API.

Request

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

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.

Highlighted fields in the response: action, deliverable, reason, deactivationDate, doNotSms.

{
  "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"
  }
}

When to run it

  • Before a send

    Check close to the send

    A check made weeks ago can't see a number that has gone dark since, and new deactivations take 1 to 7 days to appear. Check each number shortly before you call or text it, or scrub the list before every campaign.

    deactivationDateaction
  • On a schedule

    Rescrub at least monthly

    A deactivation stays visible for up to 45 days, then clears. Store each deactivationDate you see: if you keep reaching a number after it was deactivated, it may have a new owner. Contact list hygiene walks through the job.

    deactivationDate
  • Whole lists

    Upload the CSV

    Upload a CSV from the dashboard and every row comes back with deactivationDate, action and reason. See bulk phone validation.

    deactivationDateactionreason

Limits worth knowing

  • Daily data, 1 to 7 days behind

    A number disconnected in the last few days can still come back with no deactivationDate.

  • Up to 45 days

    A deactivation is shown for up to 45 days, then clears, so no deactivationDate doesn't mean the number was never disconnected. After that time the number may have gone to a new subscriber.

  • Final deactivations only

    A temporary suspension, and the service resuming after one, never sets deactivationDate. Only a carrier's final deactivation of the number does.

  • Why 45 days

    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.

  • Not a reassigned-number check

    deactivationDate says a carrier deactivated the number, not who holds it now. Once the date is gone, the number may go to a new subscriber, and the lookup can't tell you. The FCC's Reassigned Numbers Database (reassigned.us) is built for that question. This is not legal advice.

  • Not a live network ping

    Nothing is sent to the phone, and deliverable is a summary, not a delivery test.

  • US and Canada only

    NANP numbers only.

Pricing

The deactivation check is part of every lookup: one credit, no separate fee.

  • Free $0/mo 500 lookups included Hard cap, no overage
  • 1K $5/mo 1,000 lookups included Then $0.005 each
  • 10K $30/mo 10,000 lookups included Then $0.003 each
  • 100K $100/mo 100,000 lookups included Then $0.001 each
  • 500K $450/mo 500,000 lookups included Then $0.0009 each

Failed lookups are free. Annual billing is 15% off. Above 500,000 lookups a month, ask for a volume quote. Every detail is on the pricing page.

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 recently (up to 45 days), the response carries deactivationDate, action: "unsubscribe", deliverable: "false" and a reason like "Number deactivated by carrier id 6010 on 2026-10-02". The date stays for up to 45 days. 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. deactivationDate says a carrier deactivated the number, not who holds it now, and it is gone within 45 days. 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 credits a month, hard-capped; paid plans start at $5 a month for 1,000 credits. Failed lookups are not billed. See pricing.

Check your list before the next send

The Free plan includes 500 lookups a month, hard-capped. Paid plans start at $5 a month.