checkmax-phone-utils 0.2.0

Phone validation utilities (E.164 + libphonenumber) and the official REST client for the CheckMaxApp phone-verification API.

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("[phone]")          # '[phone]'
normalize("8 916 123-45-67", "RU")       # '[phone]'
validate_e164("[phone]")         # (True, '[phone]')
is_mobile("[phone]")                # True

What it does

Function	Purpose
normalize(raw, default_region)	Convert any phone-shaped input to canonical E.164, or None.
validate_e164(raw, region)	Return (is_valid, e164_or_none) for a raw input.
is_mobile(e164)	True if the number is mobile (or mobile-or-fixed).
detect_region(raw)	Return ISO 3166-1 alpha-2 region of an international number.
clean(raw)	Strip everything that is not a digit or leading +.
CheckMaxClient(api_key).check([...])	Verify numbers via the REST API — registration status + public name.

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("[phone]")
'[phone]'
>>> 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 — [e-mail]

---

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