Phone Number Format

Parse and format any international phone number with carrier, location, and flag data

The format endpoint parses any phone number (international or domestic) and returns comprehensive information including formatted outputs, carrier data, location details, and flag images.

Endpoint

GET /v1/format/:tn
GET /v1/format?tn=:tn

Authentication

Requires API key via one of:

• Authorization: Bearer <key> header (recommended)
• X-API-Key header
• apiKey query parameter

See Authentication for details.

Parameters

Path Parameters

Query Parameters

Input Formats

The endpoint accepts phone numbers in many formats:

Request Examples

International Number

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/format/+442087599036"

US Number

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/format/3055551234"

With Default Country

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/format/02087599036?defaultCountry=GB"

Force Fresh Lookup

curl -H "Authorization: Bearer your-api-key" \
  "https://api.telco.dev/v1/format/+13055551234?cache=false"

Response

Success Response - US Number (200 OK)

{
  "valid": true,
  "possible": true,
  "input": "+13055551234",
  "countryCode": "1",
  "countryCallingCode": "+1",
  "country": "US",
  "nationalNumber": "3055551234",
  "npa": "305",
  "nxx": "555",
  "nxxx": "1234",
  "formats": {
    "e164": "+13055551234",
    "international": "+1 305 555 1234",
    "national": "(305) 555-1234",
    "rfc3966": "tel:+1-305-555-1234"
  },
  "type": "FIXED_LINE_OR_MOBILE",
  "typeDescription": "Landline or Mobile",
  "location": {
    "rateCenter": "MIAMI",
    "state": "FL",
    "stateName": "Florida",
    "country": "US",
    "countryName": "United States"
  },
  "carrier": {
    "ocn": "9740",
    "name": "BELLSOUTH TELECOMM INC DBA SOUTHERN BELL TEL & TEL",
    "type": "ILEC"
  },
  "flags": {
    "country": {
      "name": "United States",
      "abbreviation": "US",
      "svg": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/us/us.svg",
      "png": {
        "small": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/us/us_48x32.png",
        "medium": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/us/us_240x160.png",
        "large": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/us/us_480x320.png"
      }
    },
    "state": {
      "name": "Florida",
      "abbreviation": "FL",
      "svg": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/us/fl/fl.svg",
      "png": {
        "small": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/us/fl/fl_48x32.png",
        "medium": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/us/fl/fl_240x160.png",
        "large": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/us/fl/fl_480x320.png"
      }
    }
  },
  "isNonGeographic": false
}

Success Response - International Number (200 OK)

{
  "valid": true,
  "possible": true,
  "input": "+442087599036",
  "countryCode": "44",
  "countryCallingCode": "+44",
  "country": "GB",
  "nationalNumber": "2087599036",
  "formats": {
    "e164": "+442087599036",
    "international": "+44 20 8759 9036",
    "national": "020 8759 9036",
    "rfc3966": "tel:+44-20-8759-9036"
  },
  "type": "FIXED_LINE",
  "typeDescription": "Landline",
  "location": {
    "country": "GB",
    "countryName": "United Kingdom"
  },
  "flags": {
    "country": {
      "name": "United Kingdom",
      "abbreviation": "GB",
      "svg": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/gb/gb.svg",
      "png": {
        "small": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/gb/gb_48x32.png",
        "medium": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/gb/gb_240x160.png",
        "large": "https://raw.githubusercontent.com/dodotdev/telco-dev-flags/master/flags/world/gb/gb_480x320.png"
      }
    }
  },
  "isNonGeographic": false
}

Invalid Number Response (200 OK)

{
  "valid": false,
  "possible": false,
  "input": "invalid"
}

Response Fields

Core Fields

NANP Fields (US/Canada only)

Formats

Number Type

Possible type values:

Location

Carrier (NANP only)

Flags

Metadata

Error Responses

Invalid Country Code (400)

{
  "error": "Bad Request",
  "message": "Invalid defaultCountry: XX. Must be a valid ISO 3166-1 alpha-2 country code."
}

Unauthorized (401)

{
  "error": "unauthorized",
  "message": "API key required."
}

Code Examples

JavaScript

async function formatNumber(number, options = {}) {
  const params = new URLSearchParams();
  if (options.defaultCountry) params.set('defaultCountry', options.defaultCountry);
  if (options.cache === false) params.set('cache', 'false');

  const url = `https://api.telco.dev/v1/format/${encodeURIComponent(number)}?${params}`;

  const response = await fetch(url, {
    headers: {
      "Authorization": `Bearer ${process.env.TELCO_API_KEY}`
    }
  });

  return response.json();
}

// Usage
const result = await formatNumber("+442087599036");
if (result.valid) {
  console.log(`Country: ${result.location.countryName}`);
  console.log(`International: ${result.formats.international}`);
  console.log(`Flag: ${result.flags.country.svg}`);
}

Python

import requests
import os
from urllib.parse import quote

def format_number(number, default_country=None, use_cache=True):
    params = {}
    if default_country:
        params['defaultCountry'] = default_country
    if not use_cache:
        params['cache'] = 'false'

    response = requests.get(
        f"https://api.telco.dev/v1/format/{quote(number)}",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['TELCO_API_KEY']}"}
    )
    return response.json()

# Usage
result = format_number("+442087599036")
if result.get('valid'):
    print(f"Country: {result['location']['countryName']}")
    print(f"International: {result['formats']['international']}")
    print(f"Flag: {result['flags']['country']['svg']}")