Phone Number Validation Test Cases: Formats & Edge Cases

Names taught us to distrust validation, and birthdays taught us to distrust arithmetic. The third field in this series looks the easiest. A phone number is digits, and an international standard, E.164, says exactly how to write one. Yet phone-number code fails constantly, in a particular way.

A name is stored and displayed, and a birthday is calculated against. A phone number is interpreted. The same ten digits mean different things depending on the country's plan, whether the person typed the domestic or the international form, and what a spreadsheet did to the leading zero. Every phone validator is a small parser of the world's numbering plans, and those plans were never designed to be parsed.

What E.164 actually specifies — and what it leaves out

E.164 is the ITU-T recommendation that defines the international numbering plan ^[itu-e164]. A number in international format is a plus sign, a country code of one to three digits, and the national number. The whole thing, country code included, may be at most 15 digits ^[e164-wiki]. There are no spaces, brackets, hyphens, trunk prefix or extension. That is the entire specification: a prefix, a maximum length and a plus.

The trouble lives in what E.164 leaves out. It sets no minimum length. It says nothing about which numbers exist, or how people in each country write them. It hands the national part to roughly two hundred national plans that disagree about almost everything. Is the length fixed? Does the domestic form start with a prefix that must be removed? Is a leading zero that prefix or a real digit? A validator that 'checks E.164' checks the envelope. Everything below opens the letter.

The edge cases that actually break systems

The leading zero is not always a prefix

Across most of Europe, Africa and Asia, a domestic number starts with a 0 that is not part of the number. It is the trunk prefix, which tells the exchange 'a full national number follows', and it is dropped in international format. That is the rule everyone learns. It is wrong for nearly a quarter of the countries our generator supports.

Italy is the famous exception. Since 1998 the leading 0 of an Italian landline has been a permanent part of the number, dialled from abroad too. A Rome number written 06 6982 1234 is +39 06 6982 1234, zero and all ^[italy-wiki]. Strip the zero and you get a shorter, still plausible, different number. Mexico joined the group on 3 August 2019, when the regulator abolished the 01, 044 and 045 prefixes and made every number a flat ten digits ^{[mexico-wiki]}. A validator built on the old rule became wrong overnight. Its tests kept passing, because the fixtures encoded the same rule.

Even where a trunk prefix exists, it is not always a single zero. Russia's is 8, left over from the Soviet plan ^{[russia-wiki]}. Hungary's is the two-digit 06 ^{[hungary-wiki]}. A strip-one-zero rule leaves the 6 behind and makes a wrong number of the right length. Brazil's domestic long-distance form is a 0 plus a two-digit code for the chosen carrier. Those three digits change from call to call, so no constant can match them.

Google's libphonenumber team keeps a list of falsehoods programmers believe about phone numbers. One of them reads: 'a leading zero in numbers formatted for domestic usage can always be discarded when dialing from abroad'. Italy is the worked example ^[falsehoods].

Length is fixed only in North America

The North American Numbering Plan gives every number exactly ten digits after the country code. That is why so much US-written software assumes a phone number has one length. Germany has an open plan: area codes and subscriber numbers both vary, and there is no single national length ^{[germany-wiki]}. Our plan table records German national numbers from 6 to 13 digits, and Austria's from 4 to 13. Hong Kong has no area codes and no trunk prefix, and every number is a flat eight digits.

Ukraine (+380), Bangladesh (+880) and Hong Kong (+852) have three-digit country codes. That breaks any parser that peels off 'the first one or two digits'. E.164's only length rule is the 15-digit ceiling, so a 16-digit string is definitely invalid. One of our own bugs produced exactly that, as we will see.

Length is not even stable for one number. On 6 October 2019, every landline in Metro Manila's area code 2 grew from seven digits to eight by regulatory order ^[ph-wiki]. On 22 April 2000, the UK's Big Number Change replaced London's 0171 and 0181 with a single 020 and lengthened local numbers to eight digits ^[bnc-wiki]. Stored numbers did not update themselves on either date. A validator that rejected the new length would have rejected every resident of the capital. Numbering plans are law, and law changes. A test suite pinned to today's plan is a snapshot, not a proof.

A country code is not a country

Software loves to derive a country from a dial code, and that loses information both ways. Country code 1 is not the United States. The North American Numbering Plan spans twenty-five regions in twenty countries, so a +1 number may be in Jamaica, Bermuda or Guam ^[nanp-wiki]. Russia and Kazakhstan share code 7 ^{[russia-wiki]}. Code 44 also covers Guernsey, Jersey and the Isle of Man, none of which is in the United Kingdom, and 39 serves both Italy and Vatican City ^[cc-list].

The list of codes also grows. Kosovo's +383 only entered service in 2017 ^[cc-list]. A hardcoded list of country codes is a list of the countries that existed when the developer last looked. The libphonenumber falsehoods list includes 'each country calling code corresponds to exactly one country' and its twin, 'each country has only one country calling code' ^[falsehoods]. Both are false.

Digits that are not digits, and letters that are

1-800-FLOWERS is a real, dialable phone number. The letters map to digits through the keypad layout in ITU-T E.161 ^[e161]. So letters are legitimate input, and a system that rejects them rejects a number the network accepts. Extensions are the opposite problem. '415-555-0142 x204' is common in business contacts, but E.164 has no slot for an extension. The tel URI scheme in RFC 3966 gives it its own parameter, ';ext=', so it is never glued to the digits ^[rfc3966]. Store the extension in its own field. Never append it: +14155550142204 is a different, valid-looking 14-digit number.

Then there are digits that are not ASCII. In Egypt, phone numbers are often written in Arabic-Indic numerals. Japanese and Chinese keyboards produce full-width digits like １２３ ^[falsehoods]. Most cleaning code, including ours, deletes everything that is not 0 to 9. That is fine for generated output. For a user typing in Cairo, it deletes the whole number and reports the field as empty. If you have international users, convert Unicode digits before you strip, or at least fail with a message instead of a blank.

The spreadsheet eats the zero

Phone numbers spend a surprising share of their lives in spreadsheets, and a spreadsheet treats a column of digits as numbers. Leading zeros vanish: the UK drama number 07700 900123 becomes 7700900123. In Italy, where the zero matters, the damage is permanent. Long values switch to scientific notation, so 447700900123 shows as 4.477E+11 and may be exported that way.

Excel keeps 15 significant digits and rounds anything longer to zeros. Microsoft's own guidance lists phone numbers among values to store as text ^[excel]. E.164's 15-digit ceiling fits inside that limit with nothing to spare: one stray digit and the last becomes a zero. Any pipeline that passes contacts through a spreadsheet needs a fixture with a leading zero to prove it survives.

A phone number is not an identity

The deepest falsehood is the one data models encode: that a phone number identifies one person. Numbers are recycled. The FCC runs a Reassigned Numbers Database because disconnected numbers are reissued, and the new holder gets the old holder's messages ^[rnd]. With portability, the area code no longer reveals location or carrier, and a number can outlive several moves and phones ^[falsehoods].

Households share landlines. One person carries a work number, a personal number and one from a previous country. Short codes and emergency numbers like 911, 112 and 999 are valid to dial and invalid as contact details. A unique constraint on a phone column, or a login that treats 'same phone' as 'same person', is a bug waiting for the first recycled number.

Numbers that are safe to put in test data

Random digits are the one thing not to use. Most random ten-digit strings belong to someone, and a staging system that texts its whole contact table is a classic incident. Numbering authorities reserve ranges for this reason. North America has the 555-0100 to 555-0199 block with any real area code; the history is in why fake phone numbers start with 555. The UK has Ofcom's drama ranges, such as 020 7946 0xxx and 07700 900xxx ^{[fictitious-wiki]}.

Sandboxes publish their own. Twilio's test credentials treat +15005550006 as a valid, available number and +15005550001 as an invalid one, every time. An integration test can exercise both branches without a real line ^[twilio]. Every number in the table below comes from one of these ranges.

A phone-number fixture set worth copying

As with the birthday fixtures, run each row through the record's whole life, not just the form. Store it, show it in national and international format, export it, import it, and check that what comes back is what went in. The Italy, Hungary and Russia rows catch a strip-the-zero normaliser. The Germany and Hong Kong rows catch a length check. The full-width and letter rows catch a normaliser that deletes what it does not understand. The drama-range row catches the spreadsheet someone added after the tests were written.

How our generator handles phone numbers — including the bugs we shipped

Every profile from our identity generator has a phone number in its country's national display format. Next to it sits a phoneE164 field for anyone who needs a standard value. The first version built that field the way most code does: strip the non-digits, add the dial code. Two bugs shipped together. A British number that faker produced as 0865 907 8593 became +4408659078593, trunk prefix still inside. A German number already in international form, +49-9019-07665907, became +4949901907665907. That is the country code twice and sixteen digits, over E.164's ceiling.

How common is that? We ran the retired shortcut over today's sample of 14,400 numbers outside North America. It produces 501 values over 15 digits, 3,627 with the country code repeated, and 6,566 with the trunk prefix left inside.

The obvious fix, stripping a leading zero before adding the dial code, would have been worse. It is wrong for eleven of our 38 countries: the nine where the leading digit matters and the two in North America with no zero at all. It also mishandles Russia's 8, Hungary's 06 and Brazil's carrier code. What shipped instead is a plan per country: the trunk prefix, if any, and the allowed range of national lengths, taken from each regulator's plan as filed with the ITU ^[itu-plans].

The converter tries candidates and checks them, instead of transforming and hoping. It builds every reading the digits could have: already international, with a trunk prefix, bare, or with a zero and a carrier code. It accepts the first reading that fits the country's lengths. If none fits, it leaves the field empty.

That empty-field rule is what caught the second bug. A Swedish number faker emitted as +46182195 has a six-digit national part, one short of the plan's minimum. The international reading failed, so the converter fell through to the bare reading. It added the country code to a string that already had it, producing +4646182195. Re-run over today's sample, that retired converter would get 33 Swedish, 50 Belgian, 28 Italian and 1 South Korean number wrong.

The fix was a rule about ambiguity. An explicit plus sign or a leading 00 says, without doubt, that what follows is international. If that reading does not fit the plan, there is no other reading to try. The honest description is that faker's template produced something Sweden's plan does not allow, and there is no correct E.164 for it.

Today's measurement covers 400 generated identities for each of our 38 countries, 15,200 phone numbers in all. 93.5% carry an E.164 value, and 32 countries convert fully. No value exceeds 15 digits, repeats its country code or falls outside its plan's length range. Six countries fall short:

In every case the cause is upstream, in faker's locale data. We leave the field empty rather than launder those numbers into something that looks right. A consumer can handle a missing value. A plausible wrong one spreads into fixtures nobody rechecks. The full results, country by country, are in the measurement file.

The honest limit: valid structure is not the exact right digits. A length range cannot catch a strip that removes one digit too many. For Britain, Italy or Germany, that turns a legal ten-digit number into a legal nine-digit one, and Austria's 4-to-13 range barely limits anything. What pins the conversion is a verified national-to-E.164 example per country. The test suite round-trips 23 of them, and all pass. A worked example is the only check that catches a real mis-conversion.

The industry answer to exact digits is libphonenumber, whose metadata models what our schema cannot, such as Brazil's carrier codes. We chose not to use it for two reasons that matter to a fixture generator. Its metadata changes between releases, so the same seed would silently produce a different number after an upgrade and break the determinism this site guarantees. And it would add roughly half a megabyte to pages we keep small.

Use libphonenumber for richer parsing. Neither it nor we can prove a number is assigned or reachable. Our US phone tool uses the 555 fiction block, but other countries' format examples are not a guarantee that every output is unassigned.

The conclusion is the one this series keeps reaching: validate less, test more. Accept the letters, the full-width digits, the Arabic-Indic numerals and the thirteen-digit German number. Reject only what no plan on earth allows. Spend the effort you save on fixtures that walk each country's rules, and on totals that catch what row checks never will: how many numbers exceed 15 digits, and how many repeat their own country code.

For the earlier fields in this series, start with names and birthdays. For email inputs, download the fixed validation cases (JSON). For North American rules in depth, see how US area codes work. For more US fiction-range samples, the phone number generator offers state and area-code selection, three output formats and batches of up to 100. Use the API documentation for programmatic profiles. The downloadable cases above are fixed formatting checks, not a live-number verification service.