Parse Phone Number

Parse an E.164 phone number into its country and national parts

GET /v1/phone/parse

cURL (US number)

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B14155552671' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B919876543210' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B12465551234' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

const number = '[phone]';
const response = await fetch(
  `https://api.countrystatecity.in/v1/phone/parse?number=${encodeURIComponent(number)}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const parsed = await response.json();
// { country: "US", dial_code: "+1", iso2: "US", iso3: "USA",
//   national_number: "4155552671", e164: "[phone]" }

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/phone/parse',
  params={'number': '[phone]'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

parsed = response.json()
print(f"{parsed['country']} | {parsed['dial_code']} | national {parsed['national_number']}")

200 - US number

{
  "country": "US",
  "dial_code": "+1",
  "iso2": "US",
  "iso3": "USA",
  "national_number": "4155552671",
  "e164": "[phone]"
}

{
  "country": "BB",
  "dial_code": "+1",
  "area_code": "246",
  "iso2": "BB",
  "iso3": "BRB",
  "national_number": "2465551234",
  "e164": "[phone]"
}

{
  "country": "IL",
  "dial_code": "+972",
  "iso2": "IL",
  "iso3": "ISR",
  "national_number": "501234567",
  "e164": "[phone]"
}

{
  "error": "Missing required query parameter: number"
}

{
  "error": "Phone number must be in E.164 format starting with + (e.g., [phone])."
}

{
  "error": "Invalid phone number. Must contain 5-15 digits after the +."
}

{
  "error": "This feature is not available on your current plan.",
  "feature": "phoneDialCode",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

{
  "error": "Could not identify a country for the given phone number."
}

Given a phone number in E.164 format (+ followed by country code and national digits), identify the originating country and split out the national portion.

The matcher walks 3-digit → 2-digit → 1-digit ITU prefixes, so longer-prefix countries (like +972 Israel) win over shorter-prefix ones that share the leading digit. For NANP +1 numbers, the area code is matched against known territory area codes — [phone] resolves to Barbados (BB), not the US.

Availability: Supporter plan and above. Returns 403 on lower tiers.

The response echoes the phone number (e164 and national_number), so it’s PII. The endpoint returns Cache-Control: no-store and emits no ETag — Cloudflare, browsers, and intermediate proxies will not retain the response. Do not change this if you’re proxying through additional caching layers; the Cache-Control is intentional.

The internal phone-prefix index is cached server-side for 24 hours. The X-Parse-Index-Cache: HIT|MISS header reports whether that internal lookup was a cache hit — it does not describe the response body.

Authentication

X-CSCAPI-KEY · string · required

Your API key for authentication

Query Parameters

number · string · required

E.164-formatted phone number starting with + followed by 5–15 digits.

Both [phone] and the URL-decoded form 14155552671 (with a leading space, which is how some HTTP clients deliver an unencoded +) are accepted.

Response

country · string

ISO 3166-1 alpha-2 code of the matched country (e.g. "BB"). Convenience field equal to iso2.

dial_code · string

Country dial code with leading + (e.g. "+1").

area_code · string

Present only for NANP matches with a fixed area-code prefix (e.g. "246" for Barbados). Omitted when not applicable.

iso2 · string

ISO 3166-1 alpha-2 code.

iso3 · string

ISO 3166-1 alpha-3 code.

national_number · string

Digits remaining after stripping the country dial code (no +, no separators). For NANP numbers this includes the area code — the area code is part of the national format.

e164 · string

Echo of the normalized input (always starts with +).

cURL (US number)

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B14155552671' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B919876543210' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

curl -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B12465551234' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

const number = '[phone]';
const response = await fetch(
  `https://api.countrystatecity.in/v1/phone/parse?number=${encodeURIComponent(number)}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const parsed = await response.json();
// { country: "US", dial_code: "+1", iso2: "US", iso3: "USA",
//   national_number: "4155552671", e164: "[phone]" }

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/phone/parse',
  params={'number': '[phone]'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

parsed = response.json()
print(f"{parsed['country']} | {parsed['dial_code']} | national {parsed['national_number']}")

200 - US number

{
  "country": "US",
  "dial_code": "+1",
  "iso2": "US",
  "iso3": "USA",
  "national_number": "4155552671",
  "e164": "[phone]"
}

{
  "country": "BB",
  "dial_code": "+1",
  "area_code": "246",
  "iso2": "BB",
  "iso3": "BRB",
  "national_number": "2465551234",
  "e164": "[phone]"
}

{
  "country": "IL",
  "dial_code": "+972",
  "iso2": "IL",
  "iso3": "ISR",
  "national_number": "501234567",
  "e164": "[phone]"
}

{
  "error": "Missing required query parameter: number"
}

{
  "error": "Phone number must be in E.164 format starting with + (e.g., [phone])."
}

{
  "error": "Invalid phone number. Must contain 5-15 digits after the +."
}

{
  "error": "This feature is not available on your current plan.",
  "feature": "phoneDialCode",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

{
  "error": "Could not identify a country for the given phone number."
}

Notes on Matching

The matcher tries 3-digit, then 2-digit, then 1-digit ITU prefixes:

• +972... matches Israel (3-digit prefix), not Yemen (+967) or any 1-digit +9 country (none exist, but the logic generalizes).
• +44... matches the UK (2-digit prefix).
• +1... is the NANP — the next 3 digits are checked against known area codes (Barbados 246, Antigua 268, etc.). If no area code matches, the request falls back to the US.

When the data carries a +1-XXX area-code prefix for a country, the matcher prefers that more-specific entry over the bare +1.

Related Endpoints

• Get Dial Code by Country — when you already know the country
• List Dial Codes — every country plus reverse lookup