International Phone Number Formatting for Hashing

International phone formatting varies by country. Spaces, dashes, parentheses, and country code placement differ across regions. For consistent phone number hashing, you must normalize to a single canonical format. This guide covers international phone format standards, country code handling, and normalization rules for global phone hashing.

E.164 International Format

E.164 is the ITU-T international standard for telephone numbers. Format: +[country code][subscriber number] with no spaces, dashes, or other formatting. Examples:

• United States: +15551234567
• United Kingdom: +442071234567
• Germany: +49301234567
• Japan: +81312345678
• India: +919876543210

E.164 is unambiguous and globally unique. Use it as your canonical format for hashing. See our country code reference for a full list of codes.

National Format Variations

Before normalization, numbers may appear in national format:

• US/Canada: (555) 123-4567, 555-123-4567, 1-555-123-4567
• UK: 020 7123 4567, +44 20 7123 4567
• Germany: 030 12345678, +49 30 12345678
• International format for storage: always convert to E.164.

National formats often include a leading zero for domestic dialing (e.g., UK 0 before area code). When converting to E.164, drop that leading zero—the country code replaces it.

Country Code Handling

Country codes are 1–3 digits. Examples: +1 (US/Canada), +44 (UK), +49 (Germany), +81 (Japan), +91 (India). When normalizing:

1. Infer country if missing: Use user locale, IP geolocation, or require explicit selection. Defaulting to +1 for US users is common.
2. Strip formatting: Remove spaces, dashes, parentheses, dots.
3. Add + prefix: E.164 uses + to indicate international format.
4. Validate length: E.164 numbers are typically 10–15 digits including country code.

Ambiguity exists: 44 could be UK (+44) or another country. Always store and hash with the full E.164 form to avoid ambiguity.

Normalization Algorithm

High-level steps:

1. Remove all non-digit characters except leading +.
2. If no +, assume national format; prepend country code based on context.
3. Remove leading zeros that are part of national formatting (e.g., UK 0 after +44).
4. Prepend + if not present.
5. Validate against E.164 rules (length, valid country code).

Use a library like libphonenumber—manual regex often fails for edge cases (e.g., variable-length numbers, special service codes).

Edge Cases

• Short codes: 411, 911, etc. May not fit E.164. Define project-specific handling (exclude, hash as-is, or use a special prefix).
• Toll-free and premium: Same format as regular numbers; normalize normally.
• Extensions: E.164 does not include extensions (e.g., x123). Strip or store separately; don't include in hash input.
• Invalid numbers: Validate before hashing. Invalid numbers may produce hashes that don't match downstream systems.

Impact on Hash Lookup

If two systems use different international phone formatting, their hashes will not match. Example: System A hashes +15551234567, System B hashes 15551234567 (no +). Different hashes, same number. Establish a normalization contract with all integration partners. Our hash directory and reverse lookup use E.164 normalization. When onboarding new partners, include normalization in your integration checklist. Provide a test harness with sample numbers and expected hashes so partners can verify their implementation before going live. Document any partner-specific format requirements (e.g., some platforms require digits-only with no +). Maintain a partner format matrix: for each integration, record the expected format, normalization rules, and any special handling. Update the matrix when onboarding new partners or when partners change their requirements. Share the matrix with your integration and support teams. When support receives a report of failed matching, they can check the matrix to see if a format mismatch is likely. When onboarding a new partner, the integration team updates the matrix. Keep the matrix in a shared document or wiki that is easily discoverable. Version it when partners change requirements. Consider automating format validation in your partner onboarding pipeline using the matrix as the source of truth. When a new partner is onboarded, the system can look up their expected format from the matrix and run validation tests. If the partner's test hashes don't match expected values given their documented format, the onboarding fails with a clear error. This prevents format mismatches from reaching production and reduces manual verification burden on the integration team. Integrate the format matrix with your API documentation—when developers look up a partner's API, they see the expected format alongside endpoint details. Consider generating format-specific SDKs or client code from the matrix, reducing the chance of manual errors. Automate wherever possible; manual format verification is error-prone and doesn't scale.

Libraries for International Formatting

• libphonenumber (Google): Java, JavaScript, C++, Python. Handles parsing, validation, formatting for 200+ regions.
• phonenumbers (Python): Python port.
• giggsey/libphonenumber-for-php: PHP.

These libraries handle country-specific rules (e.g., valid lengths, area code patterns) that are difficult to implement manually.

Best Practices

• Standardize on E.164 for all hashing and storage.
• Document format in API contracts and integration guides.
• Validate before hashing to catch invalid or ambiguous numbers.
• Use established libraries for international handling.

Variable-Length Numbers

Some countries have variable-length national numbers. Germany, for example, has numbers from 4 to 11 digits after the country code. Validation requires country-specific rules. Libraries like libphonenumber encode these rules. Manual validation often fails for edge cases. When building international support, invest in a proper library rather than regex.

Number Portability and Format Changes

Phone numbers can be ported between carriers and, in some regions, between countries. Format does not change, but the underlying assignment might. For hashing, this is irrelevant—you hash the number string as presented. However, when correlating over time, be aware that a number may have changed ownership. Hashing does not solve identity resolution over time; it only enables matching at a point in time.

Summary

International phone formatting requires E.164 normalization, country-specific validation, and handling of edge cases. Use established libraries. Document your format in API contracts. For a full country code list, see our country code reference. For hash format details, see phone hash formats. To perform lookups, visit /hashes and /phones.