Deterministic output
Accept a caller-supplied seed and document the metadata version. The same seed, country and version should produce the same fixture on every test run.
API design reference
Designing a phone test-data API
A useful fixture API should return repeatable, versioned test data without pretending to provide live numbers, SMS reception or subscriber information.
No hosted GetPhoneNum API is currently offered. This page is a complete design reference. For working data today, use the downloadable dataset, browser tools or local package.
Explicit test intent
Label positive and negative cases separately. A wrong-length fixture should explain its intended failure instead of masquerading as a valid subscriber number.
Stable contracts
Return E.164, national, international and RFC 3966 fields under a versioned schema. Add fields compatibly or publish a new major version.
Example request contract
The following is an illustrative interface, not a live endpoint. It keeps country selection, quantity, output formats and reproducibility explicit.
POST /v1/fixtures
{
"countries": ["US", "GB"],
"quantity": 25,
"formats": ["E164", "NATIONAL"],
"seed": "checkout-tests",
"include_invalid_cases": true
}Example response shape
{
"schema_version": "1.0",
"metadata_version": "2026-07-20",
"seed": "checkout-tests",
"fixtures": [
{
"country": "US",
"case": "valid_format",
"e164": "+12025550123",
"national": "(202) 555-0123",
"rfc3966": "tel:+12025550123",
"safety": "Reserved fictional range"
}
]
}Validate requests
Set clear limits for quantity, supported countries and seed length. Reject unknown fields when strict reproducibility matters, and return row-level errors for mixed requests.
Separate format from reachability
Never label a structurally possible fixture as assigned, reachable or controlled by a user. Those claims require different data and consent-based workflows.
Protect real subscribers
Prefer regulator-reserved fictional ranges. Where none are published, disclose collision risk and disable outbound SMS or voice in automated environments.
Use the maintained local resources
The country format dataset provides JSON, CSV and a JSON Schema with official-source links. For one-off work, use the E.164 formatter or bulk fixture generator. These options avoid network dependencies and keep input in the browser.
For production validation architecture, read the phone number validation guide and responsible-use policy.
Implementation notes if you build your own endpoint
Keep the API boring and predictable. Accept explicit country codes, reject unsupported countries with a stable error, cap quantity, and return the dataset version that produced the response. A caller should be able to reproduce a failed test months later by using the same seed and metadata version. If a national numbering rule changes, publish a changelog entry instead of silently changing every fixture.
Do not collect user phone numbers to generate test data. The request should describe the fixture the developer wants, not upload real contacts. Analytics should record only safe parameters such as country, count and export format. Generated values should remain in the response body and local test files, not in URLs, tracking events, server logs or marketing systems.
Error model
Return separate errors for unsupported country, invalid count, unsupported format and unsafe request shape. Avoid a generic “invalid number” response when the request is really a fixture-generation problem.
Versioning
Include schema and metadata versions in every response. Add fields compatibly when possible, and use a new major version when response meaning changes.
Abuse prevention
Rate-limit public endpoints, block contact-enrichment use cases and make the documentation clear that the API would return test fixtures only, not reachable numbers.