Daniel D. Beck

A list of fictitious numbers, domains, and more

Sometimes there’s no other choice but to give a fake number or address.

Occasionally, you’ll need to show personal or identifying information—such as a phone number, payment card number, or IP address—in documentation, examples, demos, or tests. And you probably don’t want to use your own. That’s fair.

However, complete obfuscation, redaction, or removal might not be an option because of a desire for realism or practical constraints. For example, if you need to document an API call that consumes a telephone number, then you can’t reasonably provide sample code without a number.

You might be tempted to use random strings or sequential numbers, but this runs the risk of landing on valid details that belong to actual people. You don’t want to make the mistake of “867-5309/Jenny” and cause people to flee from their previously unremarkable telephone numbers.

Instead, use values that are intended for fiction and documentation, or values which are unlikely to impact innocent bystanders. To help with this, I’ve put together a list of resources for when you need to fake it.

Phone numbers

Most telephone systems have numbers that are guaranteed to not be connected, reserved for official use, or are otherwise unlikely to be assigned. You can often find these numbers on the website of your country’s telecommunications regulator.

Examples:

Credit card numbers

Payment processors publish lists of test numbers which are definitely not issued as real cards by any bank. These numbers are either strictly invalid or are effectively pre-compromised. Often, the numbers can be paired with arbitrary security codes and expiration dates.

Examples:

For more of these numbers, your payment processor may have a dashboard with test data that is guaranteed to fail in non-testing environments.

Domains and email addresses

Specific domains are reserved for use in documentation. Any domain in the following patterns is unassigned and will never route to a real, publicly available resource:

The domains example.com, example.org, and example.net are also reserved from use except as examples.

You can also use these patterns for example email addresses, such as allocating email addresses to fictional characters. Email to dgale@notkansas.example will harmlessly fail to deliver.

To learn more about reserved domains, read IETF RFC 2606: Reserved Top Level DNS Names.

IP addresses

Like domains, certain blocks of IP addresses are reserved for use in documentation. Well-behaved networks shouldn’t ever route to these IP address ranges:

To learn more about reserved IP addresses, read IETF RFCs 3849 and 5737: IPv4 Address Blocks Reserved for Documentation and IPv6 Address Prefix Reserved for Documentation.

Postal codes

Postal codes are harder to fake appropriately. Postal systems don’t routinely provide demonstration-only postcodes. But there are two reasonable practices you can follow:

  1. Borrow from the mail service’s own documentation.

    Every postal system publishes addressing standards; use their example addresses as your own. Even if they sometimes use real addresses, they’re often addresses under the control of the postal system (such as branch post offices) and won’t affect ordinary mail recipients. For examples, see:

  2. Use valid but famous values instead, which are more likely to be recognized as examples and not actually used for any real-world application.

    For example, use 20500, the ZIP code for the White House in Washington, DC, or SW1AA 1AA, the postcode for Buckingham Palace in London, England.