checkmax-phone-utils

A small, focused Python toolkit for phone-number format validation, E.164 normalization, and an optional API client for the CheckMaxApp service. Built on top of Google's libphonenumber (Python port). Use it as a drop-in helper in your own code, or as the official client library for the live CheckMaxApp REST API.

Powered by CheckMaxApp — phone validation service for the MAX messenger. This library handles format and region validation. To check whether a number is actually registered on MAX, use the hosted CheckMaxApp service.

Quickstart

pip install checkmax-phone-utils

from checkmax_phone_utils import normalize, validate_e164, is_mobile

normalize("+7 (916) 123-45-67")          # '+79161234567'
normalize("8 916 123-45-67", "RU")       # '+79161234567'
validate_e164("+1 415 555 2671")         # (True, '+14155552671')
is_mobile("+79161234567")                # True

What it does

Full reference: see the docstrings — every public function has examples and edge-case notes.

API reference

normalize(raw: str, default_region: str = "RU") -> str | None

Safe high-level entry point. Cleans, parses, validates, and returns the canonical +CCNNNNNNNNNNN form, or None if the input is not a valid phone number.

>>> normalize("+7 (916) 123-45-67")
'+79161234567'
>>> normalize("garbage") is None
True

validate_e164(raw: str, region: str = "RU") -> tuple[bool, str | None]

Returns (is_valid, e164). When valid, e164 is the canonical form; otherwise it is None. Useful when you want to keep both signals.

is_mobile(e164: str) -> bool

True for MOBILE and FIXED_LINE_OR_MOBILE numbers; False otherwise, including when the input cannot be parsed.

detect_region(raw: str) -> str | None

Detect the ISO region from an international-format number (with + or 00 prefix). Returns None when the input lacks a country prefix.

CheckMaxClient(api_key: str)

Official client for the CheckMaxApp REST API. Get an API key from the CheckMaxApp Telegram bot. Methods: health(), balance(), usage(), check(phones), batch_create(phones), batch_status(id), batch_download(id). Raises AuthError (401) and InsufficientBalanceError (402).

from checkmax_phone_utils import CheckMaxClient

client = CheckMaxClient(api_key="mxk_...")
client.check(["79001234567"])
# [{'phone': '79001234567', 'status': 'registered',
#   'first_name': 'Ivan', 'last_name': 'Petrov'}]

The full machine-readable schema lives at openapi/checkmax-api.openapi.yaml (OpenAPI 3.0) — also published to the API directories.

Examples

The examples/ directory contains runnable scripts:

• examples/basic_validation.py — single-number validation against a small sample list.
• examples/bulk_normalize.py — normalize a CSV file of phones in bulk, emitting a CSV with e164 and valid columns.
• examples/api_client_demo.py — intended surface of the CheckMaxApp client.

Roadmap

• v0.1 — format validation, E.164 normalization, stub client.
• v0.2 — live REST client (check / batch / balance / usage), structured errors, OpenAPI 3.0 spec (current).
• v0.3 — async client, retries, optional caching.
• v0.4 — type stubs on PyPI, CLI entry point (checkmax phone <num>).

Development

git clone https://github.com/abragimbaliev/checkmax-phone-utils.git
cd checkmax-phone-utils
pip install -e ".[dev]"
pytest

CI runs pytest against Python 3.10, 3.11, and 3.12 on every push.

License

MIT. Copyright (c) 2026 CheckMax Team.

Authors

CheckMax Team — dev@checkmaxapp.com

Looking for the hosted service? CheckMaxApp — phone validation for the MAX messenger.