The unit we maintain
Each country record contains an ISO region, country calling code, national presentation pattern, one E.164-shaped example, an expected national length, a safety classification and a source URL. The record is designed for form tests, documentation and deterministic QA. It is not a subscriber database and it contains no claim about current assignment, carrier, reachability or consent.
The distinction matters because four different questions are often collapsed into one word: “valid.” A string can be parseable, structurally possible, currently allocated and reachable, while ownership still remains unproven. GetPhoneNum documents only the first layers that can be supported by published numbering material.
Source hierarchy
- National regulator or numbering administrator: preferred for national formats, trunk rules and published creative-use examples.
- ITU numbering material: used when a regulator does not expose an accessible English reference or for international calling-plan context.
- Standards: ITU-T E.164 and RFC 3966 define the international representation and tel URI model.
- Maintained software metadata: useful for implementation checks, but never treated as proof that a subscriber owns a number.
Every dataset row links to the source used for that row. A source link is not decoration: it lets a reviewer reproduce the rule and detect when a national plan changes.
Safety classification
We separate documented creative-use examples from structural examples. 4 of the current 31 records use a published reserved, drama or creative-work example. The remaining 27 records are clearly labeled as structural and potentially assigned. We do not turn a regulator's numbering pattern into a fictional-range claim.
This is why the generator warns users not to call, text or use output for account verification. When no protected range is documented, safe automated testing also requires provider sandbox credentials, an internal allowlist and outbound delivery disabled.
Review checklist
- Confirm the calling code and whether it is shared with another country or territory.
- Record the domestic trunk prefix separately from the international value.
- Preserve significant leading digits instead of applying one global zero-removal rule.
- Check expected length and whether the plan is fixed or variable.
- Label the fixture as documented creative-use or structural.
- Run generation and normalization tests before publishing the generated pages and data files.
Reproducibility and change control
The public JSON, CSV and JSON Schema are generated from the same reviewed source data used by the browser tools. The site tests verify 31 records, stable field names, unique page metadata, canonical URLs and the absence of generated values from analytics events. A change to a calling rule must update the source record, generated files and related country guide together.
Corrections should identify the exact country, current output, expected output and an official source. The editorial team reviews the evidence before changing the fixture contract. The dataset changelog records material revisions instead of silently rewriting history.
Known limitations
Numbering plans change, regulator pages move and some official material is not available in English. The dataset does not enumerate every area code, carrier prefix, premium service or local dialing convention. It intentionally stays compact enough for tests and documentation. Production systems should use maintained numbering metadata and define separate workflows for reachability and user consent.