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

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

Documentation Index

Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt

Use this file to discover all available pages before exploring further.

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 — +1-246-555-1234 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 +14155552671 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 -X GET 'https://api.countrystatecity.in/v1/phone/parse?number=%2B14155552671' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

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

​
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.