checkthatphone

Official Python client for the CheckThatPhone phone validation API. Validate US and Canadian phone numbers in real time: carrier and line type from live carrier data, portability and deliverability, GeoIP and timezone, plus optional TCPA litigator screening and a free state do-not-call scrub — one call, one credit.

Zero dependencies (standard library only). Python 3.9+.

Install

pip install checkthatphone

Quick start

import os
from checkthatphone import CheckThatPhone

client = CheckThatPhone(api_key=os.environ["CHECKTHATPHONE_API_KEY"])

result = client.lookup("8182925409")
print(result.data["nanpType"])     # "mobile"
print(result.data["dipCarrier"])   # "AT&T"
print(result.data["deliverable"])  # "true"
print(result.credits_used)         # 1

Get an API key at checkthatphone.com — the free tier includes 500 lookups per month.

TCPA litigator screening

Flag known serial TCPA plaintiffs before you call or text (+1 credit):

result = client.lookup("8182925409", litigator_filter=True)
if result.data.get("litigator") == "true":
    # result.data["litigator_type"]: "litigator" | "plaintiff" | "agitator"
    suppress(result.data["subscriber"])

State DNC scrub (free)

Screen state do-not-call registries (40 states) and a national complainer list at no extra credit:

result = client.lookup("8182925409", dnc_other=True)
result.data.get("dncStateResult")       # "STATE DNC" or ""
result.data.get("dncComplainerResult")  # "DNC COMPLAINER" or ""
result.data.get("dncStateCovered")      # "false" = state not in the data; don't read "" as clear

Landline SMS reachability

Some landlines can receive texts. Detect them instead of dropping them (+1 credit, charged only when the number is a landline):

result = client.lookup("5551234567", landline_sms_lookup=True)
if result.data.get("dipMessagingEnabled") == "true":
    send_sms(...)

GeoIP and timezone

Pass the contact's IP for city-level location and the IANA timezone (no extra charge) — useful for TCPA calling-hours compliance:

result = client.lookup("8182925409", ip="136.38.145.14")
result.data["timezone"]  # "America/Los_Angeles"

Errors

Non-2xx responses raise CheckThatPhoneError with status, code, detail, and a retryable hint. Failed and invalid requests are billed 0 credits.

from checkthatphone import CheckThatPhoneError

try:
    client.lookup("not-a-number")
except CheckThatPhoneError as err:
    if err.retryable:
        retry_later()

Full field reference

Every response field (carrier DIP, portability/LRN, deactivation, blacklist, and more) is documented at checkthatphone.com/docs.

License

MIT

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tjkcc from gravatar.com tjkcc

Credits

Author: CheckThatPhone

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.9

Tags

carrier-lookup dnc litigator nanp phone-number phone-validation sms tcpa

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

checkthatphone-0.1.0.tar.gz (5.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

checkthatphone-0.1.0-py3-none-any.whl (5.3 kB view details)

Uploaded Python 3

File details

Details for the file checkthatphone-0.1.0.tar.gz.

File metadata

  • Download URL: checkthatphone-0.1.0.tar.gz
  • Upload date:
  • Size: 5.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for checkthatphone-0.1.0.tar.gz
Algorithm Hash digest
SHA256 26feb5c49192f2697e067e2c84d4ec65311ee469154d682469a39437649b9957
MD5 09b8b6ec5f4a02687146230bbf480b6c
BLAKE2b-256 e5f0fa41e7dc3cc8492b8837a524cbffcf5386d20150eab4d24a76224f6f594b

See more details on using hashes here.

Provenance

The following attestation bundles were made for checkthatphone-0.1.0.tar.gz:

Publisher: publish.yml on CheckThatPhone/checkthatphone-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file checkthatphone-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: checkthatphone-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 5.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for checkthatphone-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8a56072f9c3e21dcfca0cb462b6cd9670a4d7da32a792b48d3c78c8b3a296d09
MD5 1d4467a5bfd979d693d9259da80d1ea8
BLAKE2b-256 afada76378174d1d32ba9ea01195328d5c5586778361a1d1cb3909d4eb9567be

See more details on using hashes here.

Provenance

The following attestation bundles were made for checkthatphone-0.1.0-py3-none-any.whl:

Publisher: publish.yml on CheckThatPhone/checkthatphone-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page