Countries

Access country reference data: names and ISO 3166-1 codes.

List Countries

Get a list of all available countries.

Endpoint

GET /api/v1/countries

Authentication: API Key + Secret required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50, min: 1, max: 10000). `page_size` is accepted as an alias.
page	number	No	Page number (default: 1)
name	string	No	Exact match on the country `name`

Response

Headers

X-Page: 1
X-Per-Page: 50
X-Total-Count: 195
X-Total-Pages: 4
X-Page-Size: 50
X-Has-More: true

Body

[
  {
    "id": 1,
    "name": "United States",
    "official_name": "United States of America",
    "alpha_2": "US",
    "alpha_3": "USA",
    "numeric_code": "840",
    "dialing_prefix": "+1"
  },
  {
    "id": 2,
    "name": "United Kingdom",
    "official_name": "United Kingdom of Great Britain and Northern Ireland",
    "alpha_2": "GB",
    "alpha_3": "GBR",
    "numeric_code": "826",
    "dialing_prefix": "+44"
  }
]

Pagination Headers

Header	Type	Description
X-Page	number	Current page number
X-Per-Page	number	Items per page
X-Total-Count	number	Total number of items
X-Total-Pages	number	Total number of pages
X-Page-Size	number	Actual items in current page
X-Has-More	boolean	Whether more pages are available

Country Object

Field	Type	Description
id	number	Unique country identifier
name	string	Common country name
official_name	string	Official country name
alpha_2	string	ISO 3166-1 alpha-2 country code
alpha_3	string	ISO 3166-1 alpha-3 country code
numeric_code	string	ISO 3166-1 numeric country code (empty string if not set)
dialing_prefix	string	International dialing prefix (empty string if not set)

Country objects do not carry a currency. Use Currencies for currency data.

Examples

# Get all countries (use -i to see headers)
curl -X GET "{{host}}/api/v1/countries" -i \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# Second page of 10 countries, with pagination headers
curl -X GET "{{host}}/api/v1/countries?limit=10&page=2" -i \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

Get Country by ID

Get details for a specific country.

Endpoint

GET /api/v1/countries/{id}

Authentication: API Key + Secret required

Path Parameters

Parameter	Type	Required	Description
id	number	Yes	Country ID

Response

{
  "id": 1,
  "name": "United States",
  "official_name": "United States of America",
  "alpha_2": "US",
  "alpha_3": "USA",
  "numeric_code": "840",
  "dialing_prefix": "+1"
}

Error Responses

404 Not Found

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Country not found",
    "messages": {}
  }
}

A non-numeric, zero, or out-of-range id returns 400 with the message Invalid country ID.

Examples

curl -X GET "{{host}}/api/v1/countries/1" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

Countries

On this page