docs.do.dev
telco.devApi

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

ParameterTypeRequiredDescription
tnstringYesPhone number (telephone number) in any format

Query Parameters

ParameterTypeRequiredDescription
tnstringYes*Phone number. *Required when not using path parameter.
defaultCountrystringNoISO 3166-1 alpha-2 country code (default: US). Used when number has no country code.
cachestringNoSet to false to bypass cache and force fresh lookup.

Input Formats

The endpoint accepts phone numbers in many formats:

InputNormalized To
+442087599036+442087599036
+1 (305) 555-1234+13055551234
011442087599036+442087599036 (US intl prefix)
00442087599036+442087599036 (EU intl prefix)
3055551234+13055551234 (with defaultCountry=US)

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

FieldTypeDescription
validbooleanWhether the number is a valid phone number
possiblebooleanWhether the number could be valid (correct length/format)
inputstringThe normalized input after processing
countryCodestringCountry calling code without + (e.g., 1, 44)
countryCallingCodestringCountry calling code with + (e.g., +1, +44)
countrystringISO 3166-1 alpha-2 country code (e.g., US, GB)
nationalNumberstringNational number without country code

NANP Fields (US/Canada only)

FieldTypeDescription
npastringArea code (first 3 digits)
nxxstringExchange code (middle 3 digits)
nxxxstringSubscriber number (last 4 digits)

Formats

FieldTypeDescription
formats.e164stringE.164 format: +13055551234
formats.internationalstringInternational format: +1 305 555 1234
formats.nationalstringNational format: (305) 555-1234
formats.rfc3966stringRFC 3966 URI: tel:+1-305-555-1234

Number Type

FieldTypeDescription
typestringNumber type code
typeDescriptionstringHuman-readable type description

Possible type values:

TypeDescription
FIXED_LINELandline
MOBILEMobile
FIXED_LINE_OR_MOBILELandline or Mobile
TOLL_FREEToll-Free
PREMIUM_RATEPremium Rate
SHARED_COSTShared Cost
VOIPVoIP
PERSONAL_NUMBERPersonal Number
PAGERPager
UANUniversal Access Number
VOICEMAILVoicemail

Location

FieldTypeDescription
location.rateCenterstringRate center name (NANP only)
location.statestringState/province code (NANP only)
location.stateNamestringFull state/province name (NANP only)
location.countrystringCountry code
location.countryNamestringFull country name

Carrier (NANP only)

FieldTypeDescription
carrier.ocnstringOperating Company Number
carrier.namestringCarrier name
carrier.typestringCarrier type (ILEC, CLEC, WIRELESS, etc.)

Flags

FieldTypeDescription
flags.countryobjectCountry flag images
flags.stateobjectState flag images (US only)
flags.*.svgstringSVG image URL
flags.*.png.smallstring48x32 PNG
flags.*.png.mediumstring240x160 PNG
flags.*.png.largestring480x320 PNG

Metadata

FieldTypeDescription
isNonGeographicbooleanWhether the number is non-geographic (toll-free, etc.)

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']}")

Carriers

List and look up carrier information by Operating Company Number (OCN)

Health & Stats

Check API health and get database statistics

On this page

EndpointAuthenticationParametersPath ParametersQuery ParametersInput FormatsRequest ExamplesInternational NumberUS NumberWith Default CountryForce Fresh LookupResponseSuccess Response - US Number (200 OK)Success Response - International Number (200 OK)Invalid Number Response (200 OK)Response FieldsCore FieldsNANP Fields (US/Canada only)FormatsNumber TypeLocationCarrier (NANP only)FlagsMetadataError ResponsesInvalid Country Code (400)Unauthorized (401)Code ExamplesJavaScriptPython