Fake Phone Number API

Q: Which countries can I generate for?

The 8 supported locales set the country (e.g. locale=ja gives +81); countryCode in the response tells you which plan was used.

MOCK DATA

Fake, correctly formatted phone numbers in E.164, international and national forms of the same number, using real country codes and lengths across 8 locales.

Generated test data for fixtures and development

Base URL: /api/phones
Category: People
Capabilities: 1 route Seedable 8 locales
Last updated: July 30, 2026

GET /api/phones Generate fake phone numbers in every representation Returns a list

Live requestRuns against the public API

No key required

GET/api/phones?count=3&seed=42

Request parameters

No route-specific input is required.

Advanced response options8 options

countdefault 10

How many records to generate (1–100).

seed

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

localedefault en

Locale for the generated data (names, addresses, …).

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 8 params · 5 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/phones?count=3&seed=42"

const res = await fetch("https://randomapi.dev/api/phones?count=3&seed=42");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/phones?count=3&seed=42").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/phones?count=3&seed=42"
), true);
$data = $json["data"];

Universal parameters Shared response and formatting options 8

Parameter	Type	Default & allowed	Description
`count`	int	default: 10 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`locale`	enum	default: en allowed: en \| da \| de \| fr \| es \| it \| pt \| ja example: da	Locale for the generated data (names, addresses, …).
`fields`	list	example: e164,international	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: countryCode	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

How many records to generate (1–100).

default: 10

allowed: 1 – 100

example: count=3

seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42

locale enum

Locale for the generated data (names, addresses, …).

default: en

allowed: en | da | de | fr | es | it | pt | ja

example: locale=da

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=e164,international

exclude list

Return all fields except these (comma-separated).

example: exclude=countryCode

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 5

Field	Type	Description	Example
`e164`	string (E.164)	The number in E.164: '+', the country calling code, then the national digits — no spaces. Always matches ^\+[1-9]\d{6,14}$.	+12125550134
`international`	string	Human-readable international form: the same digits as e164, spaced with the country's conventional grouping.	+1 212 555 0134
`national`	string	National significant number with the country's digit grouping — no calling code and no domestic trunk prefix, so its digits equal the e164 digits after the calling code.	212 555 0134
`countryCallingCode`	string	The country calling code with its leading '+'.	+1
`countryCode`	string (ISO 3166-1 alpha-2)	Country whose numbering plan the record follows — determined by ?locale=.	US

e164 string (E.164)

The number in E.164: '+', the country calling code, then the national digits — no spaces. Always matches ^\+[1-9]\d{6,14}$.

example: +12125550134

international string

Human-readable international form: the same digits as e164, spaced with the country's conventional grouping.

example: +1 212 555 0134

national string

National significant number with the country's digit grouping — no calling code and no domestic trunk prefix, so its digits equal the e164 digits after the calling code.

example: 212 555 0134

countryCallingCode string

The country calling code with its leading '+'.

example: +1

countryCode string (ISO 3166-1 alpha-2)

Country whose numbering plan the record follows — determined by ?locale=.

example: US

Documented examples

Build-generated requests and complete responses 3

Three reproducible US numbers /api/phones?count=3&seed=42

GET /api/phones?count=3&seed=42

{
  "data": [
    {
      "e164": "+15654500479",
      "international": "+1 565 450 0479",
      "national": "565 450 0479",
      "countryCallingCode": "+1",
      "countryCode": "US"
    },
    {
      "e164": "+12046912567",
      "international": "+1 204 691 2567",
      "national": "204 691 2567",
      "countryCallingCode": "+1",
      "countryCode": "US"
    },
    {
      "e164": "+18135505018",
      "international": "+1 813 550 5018",
      "national": "813 550 5018",
      "countryCallingCode": "+1",
      "countryCode": "US"
    }
  ],
  "meta": {
    "endpoint": "phones",
    "count": 3,
    "seed": 42,
    "locale": "en",
    "params": {},
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Danish formats (+45, 8 digits) /api/phones?locale=da&count=5

GET /api/phones?locale=da&count=5

{
  "data": [
    {
      "e164": "+4556535004",
      "international": "+45 56 53 50 04",
      "national": "56 53 50 04",
      "countryCallingCode": "+45",
      "countryCode": "DK"
    },
    {
      "e164": "+4520459125",
      "international": "+45 20 45 91 25",
      "national": "20 45 91 25",
      "countryCallingCode": "+45",
      "countryCode": "DK"
    },
    {
      "e164": "+4581345050",
      "international": "+45 81 34 50 50",
      "national": "81 34 50 50",
      "countryCallingCode": "+45",
      "countryCode": "DK"
    },
    {
      "e164": "+4535019863",
      "international": "+45 35 01 98 63",
      "national": "35 01 98 63",
      "countryCallingCode": "+45",
      "countryCode": "DK"
    },
    {
      "e164": "+4587420698",
      "international": "+45 87 42 06 98",
      "national": "87 42 06 98",
      "countryCallingCode": "+45",
      "countryCode": "DK"
    }
  ],
  "meta": {
    "endpoint": "phones",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

German E.164 list as CSV /api/phones?locale=de&fields=e164&format=csv&count=10

GET /api/phones?locale=de&fields=e164&format=csv&count=10

e164
+4917053500479
+491514591256
+491773450501
+4915501986319
+4917742069882
+491513204974
+491526753729
+4917749847670
+491706174001
+4917975940427

About this API

Coverage, behavior and common use cases

Coverage & behavior

Every record is one phone number in every representation you have to parse, store or display: e164 (+12125550134), a human-spaced international form (+1 212 555 0134) and the national form (212 555 0134), plus the countryCallingCode and countryCode on their own. The representations always agree digit-for-digit — strip the spaces and the calling code and all three contain identical digits — so parser and formatter tests can assert exact equality instead of "looks right".

?locale= selects the national numbering plan:

locale	country	code	calling code	national digits	style
`en`	United States	`US`	`+1`	10	NANP — area code and exchange both start 2–9, never an x11 service code
`da`	Denmark	`DK`	`+45`	8	8 digits starting 2–9 (a leading 1 is reserved for short codes)
`de`	Germany	`DE`	`+49`	10 or 11	mobile — a real 15x/16x/17x network prefix plus 7–8 subscriber digits
`fr`	France	`FR`	`+33`	9	mobile — starts 6 or 7 (the domestic trunk 0 is never included)
`es`	Spain	`ES`	`+34`	9	mobile (6x/7x) or landline (9x)
`it`	Italy	`IT`	`+39`	9 or 10	mobile — 3xx prefix plus 6–7 digits
`pt`	Brazil	`BR`	`+55`	10 or 11	2-digit area code, then mobile (9 + 8 digits) or landline (2–5 + 7 digits)
`ja`	Japan	`JP`	`+81`	10	mobile — 90/80/70 prefix plus 8 digits (the domestic trunk 0 is never included)

The numbers are mock: the calling code, number length and leading digits/prefixes follow each country's real plan, but the remaining subscriber digits are random — a generated number may be unassignable or belong to nobody, and must never be dialed or messaged. national is the national significant number, so domestic trunk prefixes (the leading 0 you would dial inside Germany, France, Brazil or Japan) are never included — that is what keeps all representations digit-identical. Every e164 value matches ^\+[1-9]\d{6,14}$.

With a seed the same query returns byte-identical numbers forever; fields=e164&format=csv turns it into a plain importable list.

Do not confuse this with /api/phone-numbers. The names are close and the promises are opposite: this endpoint generates mock numbers for 8 locales, while /api/phone-numbers parses, formats and validates a number you supply against a pinned snapshot of libphonenumber's numbering-plan metadata for 254 territories. A number generated here follows its country's plan but is not guaranteed to pass that validator — so use /api/phone-numbers when you need the verdict, and this endpoint when you need the fixture.

Use it for

Test phone-input parsing and normalization: assert your parser round-trips national → E.164 to the exact same digits
Seed CRM and contact-list fixtures with locale-correct phone formats (?locale=de)
Check UI layout and truncation against real-world lengths — from 8-digit Danish numbers to 11-digit Brazilian mobiles

Frequently asked questions

Practical answers about this endpoint 3

Are the formats actually valid?

The country calling code and number length follow the real national plan, and each record shows the same number as e164, international and national — three formats, one number.

Will these numbers ring somebody?

They're not guaranteed unassigned, so don't call or text them — use them for parsing, formatting and UI tests only.

Which countries can I generate for?

The 8 supported locales set the country (e.g. locale=ja gives +81); countryCode in the response tells you which plan was used.

Standards & references

Primary sources behind the contract

ITU-T E.164 — international numbering plan

Useful next tools in the catalog

Random User Data API MOCK DATA

Complete fake people — name, age-consistent birth date, email, phone, job and address — with working filters for gender, age range and email domain.

Fake Address API MOCK DATA

Locale-aware fake postal addresses — street, city, state, zip, country and coordinates that all agree, plus a one-line formatted form in the local layout.

Random Name Generator API MOCK DATA

Random person names — first, last and full — with a strict gender filter, locale-aware name pools in 8 languages and seed-reproducible output.

Fake Email Address API MOCK DATA

Fake email addresses with name-derived usernames on guaranteed non-deliverable domains (example.com/net/org and .test) — or stamp your own with ?domain=.

Phone Number Parsing & Validation API (libphonenumber Data) REAL DATA

Parse and validate phone numbers from libphonenumber's numbering-plan metadata: E.164, national and RFC 3966 forms, number type, possible vs valid. No key.