Phone number validation in Python: phonenumbers, Pydantic and a live check

pip install phonenumbers==9.0.40 httpx pydantic

# phone.py
import re
import phonenumbers
from phonenumbers import NumberParseException, PhoneNumberFormat, PhoneNumberType, ValidationResult

# Our reserved test range (+44 7700 9xxxxx). libphonenumber marks it invalid on purpose.
TEST_RANGE = re.compile(r"^\+4477009\d{5}$")
LENGTH_REASONS = {ValidationResult.TOO_SHORT: "too_short", ValidationResult.TOO_LONG: "too_long"}


def normalize_phone(raw: str, region: str | None = None, allow_test_range: bool = False) -> dict:
    raw = (raw or "").strip()
    if not raw or len(raw) > 32:
        return {"ok": False, "reason": "unparseable"}
    try:
        p = phonenumbers.parse(raw, region)  # region like "GB"; None requires a leading +
    except NumberParseException:
        return {"ok": False, "reason": "unparseable"}
    e164 = phonenumbers.format_number(p, PhoneNumberFormat.E164)
    if allow_test_range and TEST_RANGE.match(e164):
        return {"ok": True, "e164": e164, "region": "GB", "type": "TEST"}
    if not phonenumbers.is_valid_number(p):
        why = phonenumbers.is_possible_number_with_reason(p)
        return {"ok": False, "reason": LENGTH_REASONS.get(why, "invalid")}
    return {
        "ok": True,
        "e164": e164,
        "region": phonenumbers.region_code_for_number(p),
        "type": PhoneNumberType.to_string(phonenumbers.number_type(p)),
    }

# models.py
from typing import Annotated
from pydantic import AfterValidator, BaseModel
from phone import normalize_phone


def _e164(value: str) -> str:
    r = normalize_phone(value, "GB")  # your default region, e.g. from the form's country picker
    if not r["ok"]:
        raise ValueError(f"not a valid phone number ({r['reason']})")
    return r["e164"]


E164Phone = Annotated[str, AfterValidator(_e164)]


class SignUp(BaseModel):
    name: str
    phone: E164Phone

# mvclient.py
import os
import time
import httpx

API = os.environ.get("MOBILEVALIDATE_BASE_URL", "https://api.mobilevalidate.com")


class ApiError(Exception):
    def __init__(self, code: str, status: int, message: str = ""):
        super().__init__(f"{code} ({status}): {message}")
        self.code, self.status = code, status


def _client() -> httpx.Client:
    return httpx.Client(
        base_url=API,
        headers={"Authorization": f"Bearer {os.environ['MOBILEVALIDATE_API_KEY']}"},
        timeout=httpx.Timeout(45.0),  # the server may long-poll for up to `wait` seconds
    )


def _call(client: httpx.Client, method: str, path: str, **kw) -> dict:
    for attempt in range(4):
        r = client.request(method, path, **kw)
        if r.is_success:
            return r.json()
        try:
            err = r.json().get("error", {})
        except ValueError:  # e.g. an HTML error page from a proxy
            err = {"retryable": r.status_code >= 500}
        if err.get("retryable") and attempt < 3:
            time.sleep(float(r.headers.get("retry-after", 2**attempt)))
            continue
        raise ApiError(err.get("code", f"http_{r.status_code}"), r.status_code, err.get("message", ""))


def lookup(numbers: list[str], checks: list[str] | None = None) -> list[dict]:
    """Check up to 100 E.164 numbers. Numbers travel in the POST body, never in the URL."""
    with _client() as client:
        res = _call(client, "POST", "/v1/lookup",
                    json={"numbers": numbers, "checks": checks or ["carrier"], "wait": 10})
        while res["status"] == "pending":
            time.sleep((res.get("next") or {}).get("poll_after_ms", 2000) / 1000)
            res = _call(client, "GET", f"/v1/lookups/{res['id']}", params={"wait": 10})
    out = []
    for r in res["results"]:
        c = (r.get("checks") or {}).get("network.carrier") or {}
        attrs = c.get("attributes") or {}
        out.append({
            "e164": r.get("e164"),
            "number_status": r["number_status"],   # valid | invalid_number | duplicate | suppressed
            "status": c.get("status"),              # completed | unknown | pending | unsupported_country
            "line_type": attrs.get("line_type"),    # None = unknown, never "not mobile"
            "carrier": attrs.get("carrier"),
            "reason": c.get("reason"),
            "checked_at": c.get("checked_at"),
        })
    return out

{'e164': '+447700900001', 'number_status': 'valid', 'status': 'completed', 'line_type': 'mobile',
 'carrier': 'Test Carrier', 'reason': None, 'checked_at': '2026-09-25T18:59:29.902Z'}
{'e164': '+447700900004', 'number_status': 'valid', 'status': 'completed', 'line_type': 'mobile',
 'carrier': 'Test Carrier', 'reason': None, 'checked_at': '2026-09-25T18:59:34.921Z'}

# test_phone.py
import os
import pytest
from pydantic import ValidationError
from models import SignUp
from phone import normalize_phone


@pytest.mark.parametrize("raw,region,e164", [
    ("(202) 555-0143", "US", "+12025550143"),
    ("07911 123456", "GB", "+447911123456"),
    ("+49 1512 3456789", None, "+4915123456789"),
])
def test_normalizes_to_e164(raw, region, e164):
    assert normalize_phone(raw, region)["e164"] == e164


@pytest.mark.parametrize("raw,reason", [
    ("+1 123 456 7890", "invalid"),       # right length, impossible area code
    ("+44 79111 234567", "too_long"),
    ("202-555-0143", "unparseable"),     # no region, no +
])
def test_rejects(raw, reason):
    assert normalize_phone(raw)["reason"] == reason


def test_pydantic_model():
    assert SignUp(name="Ada", phone="07911 123456").phone == "+447911123456"
    with pytest.raises(ValidationError):
        SignUp(name="Ada", phone="12345")


@pytest.mark.skipif(not os.environ.get("MOBILEVALIDATE_API_KEY", "").startswith("mv_test_"),
                    reason="needs a test key")
def test_lookup_in_test_mode():
    from mvclient import lookup
    rows = {r["e164"]: r for r in lookup(["+447700900001", "+447700900002", "+447700900003"])}
    assert rows["+447700900001"]["line_type"] == "mobile"
    assert rows["+447700900002"]["status"] == "unknown"      # no data: not billed
    assert rows["+447700900003"]["reason"] == "UPSTREAM_TIMEOUT"