GET/api/v6/tools/countries

List countries

Full country catalog with ISO code, calling code and MCC.

Scope

Any valid API key

Usage limit

60 requests per minute

Returns the full country catalog the API knows about, with ISO code, calling code, mobile country code (MCC) and names in English and Spanish. Use it to render country pickers, autodetect a country from a phone prefix, or resolve MCCs.

The catalog rarely changes. The response includes Cache-Control: public, max-age=3600 so your client and any intermediate CDN can amortize the traffic.

Languages

Names are provided only in English (en) and Spanish (es). Any other lang value falls back to English.

Query parameters

lang

stringoptional

ISO-639-1 code. When specified, each country returns a flat name in that locale instead of the full names map.

enes

callingCode

stringoptional

Filters countries by E.164 calling code (for example 57 for Colombia). An optional leading + is accepted.

search

stringoptional

Case-insensitive substring match on the country name in the requested locale. Minimum 2 characters.

Responses

200

Country catalog.

{
  "success": true,
  "data": [
    {
      "code": "CO",
      "code3": "COL",
      "callingCode": "57",
      "mcc": "732",
      "flag": "https://flagcdn.com/co.svg",
      "names": { "en": "Colombia", "es": "Colombia" }
    },
    {
      "code": "MX",
      "code3": "MEX",
      "callingCode": "52",
      "mcc": "334",
      "flag": "https://flagcdn.com/mx.svg",
      "names": { "en": "Mexico", "es": "México" }
    }
  ],
  "meta": {
    "requestId": "b9b1704baffab21150213c02fd853975",
    "timestamp": "2026-05-23T02:00:00+00:00",
    "responseTimeMs": 4.12
  }
}

401

Invalid or missing credentials.

429

Request limit exceeded.

503

Service temporarily unavailable.

Possible errors

Codes this endpoint can return in error.code. The full detail lives in the catalog.

401AUTH_REQUIREDNo Bearer token was sent, and every call requires one.401AUTH_INVALID_KEYThe API key is not recognized: wrong format, revoked or expired.429RATE_TPS_EXCEEDEDYou exceeded your organization quota for this endpoint.429RATE_DDOS_EXCEEDEDUnusually high volume from your source IP.503SERVICE_UNAVAILABLEGeneric 503: a service we depend on is not responding.

See the full catalog

Scope and limits

Languages

Query parameters

Responses

Possible errors