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.

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.

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.