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

# List Dial Codes

> List every country's international dial code, with optional reverse lookup by dial code

Return every country's international dial code in one call, or do the reverse — find every country that shares a given dial code (useful for NANP `+1` countries like the US and Canada).

Dial codes follow ITU-T E.164 and are returned with a leading `+`. For NANP countries with an area-code prefix in the underlying data (e.g. Barbados as `+1-246`), the area code is returned as a separate `area_code` field.

<Note>**Availability:** Supporter plan and above. Returns `403` on lower tiers.</Note>

<Info>Responses are cached server-side for 24 hours. Equivalent dial-code inputs (`+91`, `91`, `091`, `0091`) all resolve to the same cache slot.</Info>

## Authentication

<ParamField header="X-CSCAPI-KEY" type="string" required>
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="code" type="string">
  Optional. Restrict the response to countries with the given dial code. Accepts:

  * With or without leading `+` (`+91` or `91`)
  * 1–4 digits
  * Leading zeros are stripped (so `01`, `001`, `1` all match `+1`)
  * NANP area-code variants — `?code=+1` returns the US, Canada, and every NANP territory in one response

  Without this parameter, every country with a dial code is returned (sorted by ISO2 code).
</ParamField>

## Response

The response is **an array of phone entries**, even when the result is a single country.

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-2 code of the country (e.g. `"US"`). Convenience field equal to `iso2`.
</ResponseField>

<ResponseField name="dial_code" type="string">
  Dial code with leading `+` (e.g. `"+91"`).
</ResponseField>

<ResponseField name="area_code" type="string">
  Present only for NANP entries with a fixed area-code prefix in the underlying data (e.g. `"246"` for Barbados). Omitted when not applicable — do not assume the field exists.
</ResponseField>

<ResponseField name="iso2" type="string">
  ISO 3166-1 alpha-2 code (e.g. `"US"`).
</ResponseField>

<ResponseField name="iso3" type="string">
  ISO 3166-1 alpha-3 code (e.g. `"USA"`).
</ResponseField>

<RequestExample>
  ```bash cURL (all countries) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/phone' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (reverse lookup) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/phone?code=%2B1' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```bash cURL (without URL-encoded +) theme={null}
  curl -X GET 'https://api.countrystatecity.in/v1/phone?code=91' \
    -H 'X-CSCAPI-KEY: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.countrystatecity.in/v1/phone?code=' + encodeURIComponent('+44'),
    { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
  );

  const entries = await response.json();
  // entries: [{ country: "GB", dial_code: "+44", iso2: "GB", iso3: "GBR" }, ...]
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.countrystatecity.in/v1/phone',
    params={'code': '+1'},
    headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
  )

  nanp_countries = response.json()
  print(f"{len(nanp_countries)} countries share +1")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Reverse lookup (?code=+1) theme={null}
  [
    { "country": "AG", "dial_code": "+1", "area_code": "268", "iso2": "AG", "iso3": "ATG" },
    { "country": "AI", "dial_code": "+1", "area_code": "264", "iso2": "AI", "iso3": "AIA" },
    { "country": "BB", "dial_code": "+1", "area_code": "246", "iso2": "BB", "iso3": "BRB" },
    { "country": "BS", "dial_code": "+1", "area_code": "242", "iso2": "BS", "iso3": "BHS" },
    { "country": "CA", "dial_code": "+1",                    "iso2": "CA", "iso3": "CAN" },
    { "country": "US", "dial_code": "+1",                    "iso2": "US", "iso3": "USA" }
  ]
  ```

  ```json 200 - Single country (?code=+91) theme={null}
  [
    { "country": "IN", "dial_code": "+91", "iso2": "IN", "iso3": "IND" }
  ]
  ```

  ```json 400 - Empty code theme={null}
  {
    "error": "Invalid dial code. Provide a non-empty value (e.g., +1, 44)."
  }
  ```

  ```json 400 - Non-numeric / wrong length theme={null}
  {
    "error": "Invalid dial code format. Expected digits (e.g., 91, 1, 44)."
  }
  ```

  ```json 403 - Feature Restricted theme={null}
  {
    "error": "This feature is not available on your current plan.",
    "feature": "phoneDialCode",
    "upgradeUrl": "https://app.countrystatecity.in/pricing"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Get Dial Code by Country](/api/endpoints/get-dial-code-by-country) — one country at a time when you already know the country
* [Parse Phone Number](/api/endpoints/parse-phone-number) — given an E.164 number, identify the country