Phone Format API: The Complete Guide to Phone Number Formatting

Need to display phone numbers consistently across your application? This guide covers everything you need to know about formatting phone numbers for any country via API, including international formats and implementation examples in multiple languages.

What is Phone Number Formatting?

Phone number formatting transforms raw digit strings into properly formatted, readable phone numbers according to regional conventions and international standards.

For example, "2025551234" can be formatted as "(202) 555-1234" for US display, or "+1 202 555 1234" for international use.

Format Types

Different formats serve different purposes:

E.164 (International Standard)

+14155552671 - Used for storage, APIs, and SMS services. Always starts with + and country code.

National Format

(415) 555-2671 - Formatted for display within the same country. No country code needed.

International Format

+1 415-555-2671 - Formatted for display across borders. Includes country code with spaces.

Using the Phone Format API

TinyFn provides a simple endpoint to format phone numbers:

GET https://api.tinyfn.io/v1/format/phone?number=2025551234&country=US
Headers: X-API-Key: your-api-key

{
  "input": "2025551234",
  "country": "US",
  "e164": "+12025551234",
  "national": "(202) 555-1234",
  "international": "+1 202-555-1234",
  "valid": true
}

Parameters

Code Examples

JavaScript / Node.js

// Format US phone number
const response = await fetch(
  'https://api.tinyfn.io/v1/format/phone?number=2025551234&country=US',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { national, international, e164 } = await response.json();
console.log(national);      // (202) 555-1234
console.log(international); // +1 202-555-1234
console.log(e164);          // +12025551234

// Format UK phone number
const ukResponse = await fetch(
  'https://api.tinyfn.io/v1/format/phone?number=02079460123&country=GB',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const uk = await ukResponse.json();
console.log(uk.national); // 020 7946 0123

Python

import requests

# Format US phone number
response = requests.get(
    'https://api.tinyfn.io/v1/format/phone',
    params={'number': '2025551234', 'country': 'US'},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(data['national'])      # (202) 555-1234
print(data['international']) # +1 202-555-1234
print(data['e164'])          # +12025551234

# Format German phone number
response = requests.get(
    'https://api.tinyfn.io/v1/format/phone',
    params={'number': '03012345678', 'country': 'DE'},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['national'])  # 030 12345678

cURL

# Format US phone number
curl "https://api.tinyfn.io/v1/format/phone?number=2025551234&country=US" \
  -H "X-API-Key: your-api-key"

# Format UK phone number
curl "https://api.tinyfn.io/v1/format/phone?number=02079460123&country=GB" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Contact Forms: Format user-entered phone numbers consistently
• CRM Systems: Standardize phone numbers for deduplication
• SMS Services: Convert to E.164 for SMS APIs (Twilio, etc.)
• International Apps: Display numbers in user's local format
• Data Import: Normalize phone numbers from various sources

Best Practices

1. Store in E.164: Universal format that works everywhere
2. Display in national format: Most familiar to local users
3. Validate before storing: Ensure numbers are actually valid
4. Handle country detection: Use IP geolocation or user preference

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-format": {
      "url": "https://api.tinyfn.io/mcp/format/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all formatting tools available via MCP in our Formatting MCP Tools for AI Agents guide.