The five-claim model
| Claim | Evidence | Safe stored result | What it cannot prove |
|---|---|---|---|
| Parseable | Country-aware parser accepts the string | parsedAt, region, original input | Possible allocation or reachability |
| Structurally possible | Length and prefix fit maintained metadata | isPossible, metadata version | Currently assigned |
| Recognized allocation | Current numbering metadata recognizes the range | isValidRange, checked date | Live route or subscriber |
| Reachable | Consent-aware provider delivery result | Channel result and timestamp | Long-term ownership |
| User controlled | User completes an OTP or call challenge | verifiedAt, method, expiry | Future consent or identity |
Experiment 1: punctuation is not validity
Inputs such as (11) 98765-4321 and 11 98765 4321 can normalize to the same Brazilian fixture. A test should assert that punctuation is accepted and the canonical output is identical. It should not count punctuation removal as evidence of allocation.
Experiment 2: country context changes the result
The national string 06 39 98 12 34 only becomes the reviewed French fixture when the parser receives FR context. Treating every leading zero identically would break Italy's significant geographic zero rule. The negative test is not just “bad input”; it is “missing or incorrect region context.”
Experiment 3: a valid shape can still be unsafe
27 current records use structural examples that may coincide with assigned subscribers. A successful structure check must therefore leave reachable and verifiedAt empty. This prevents a formatting helper from accidentally authorizing SMS, voice or account-recovery actions.
Experiment 4: product rules are a separate layer
A structurally possible phone number may still be unsupported by a product. A service might accept mobile numbers but reject premium services, require one operating country or prohibit shared office lines. Store that outcome as a product-policy decision rather than rewriting the parser result.
This separation improves error messages. “The number format is not possible for FR” describes a numbering check, while “Our service is not available in this region” describes a business rule. Mixing them makes analytics misleading and encourages developers to hard-code product policy into reusable parsing code.
Interpreting failure without leaking personal data
Tests and production logs should record the region, validation stage, metadata version and error category. They usually do not need the full input. A masked suffix or internal record identifier is enough to correlate a failure while reducing exposure in analytics and error reporting.
The GetPhoneNum browser tools intentionally avoid sending generated or formatted phone values in analytics events. Event parameters describe the country, action and count, allowing feature measurement without turning test strings into tracking data.
Recommended record shape
{
"input": "06 39 98 12 34",
"region": "FR",
"phoneE164": "+33639981234",
"isPossible": true,
"metadataVersion": "2026-07-20",
"reachable": null,
"verifiedAt": null,
"consentRecordedAt": null
}Null values are deliberate: they preserve the difference between “not checked” and “false.” Do not let a parser populate verification or consent fields.
Regression checklist
- National input with explicit region.
- International input beginning with +.
- One digit short and one digit long.
- Shared calling-code ambiguity.
- Trunk zero removed and significant zero preserved.
- Extension stored separately.
- Metadata update changes reviewed before release.
- No phone value included in analytics events or URLs.