Countries

Access country reference data including country codes, names, and dialing prefixes.

List Countries

Get a list of all available countries.

Endpoint

GET /api/v1/countries

Authentication: Bearer token required

All records are returned in a single response. No pagination or query parameters are supported.

Response

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

Country Object

Field	Type	Description
id	number	Unique country identifier
name	string	Country common name
official_name	string	Country official/formal name
alpha_2	string	ISO 3166-1 alpha-2 code (2 letters)
alpha_3	string	ISO 3166-1 alpha-3 code (3 letters)
numeric_code	string	ISO 3166-1 numeric code
dialing_prefix	string	International dialing prefix

Error Responses

401 Unauthorized

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

500 Internal Server Error

{
  "error": {
    "name": "InternalServerError",
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Failed to retrieve countries"
  }
}

Examples

curl -X GET "{{host}}/api/v1/countries" \
  -H "Authorization: Bearer your_access_token"

<?php
function getCountries($accessToken) {
    $ch = curl_init('{{host}}/api/v1/countries');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}
?>

Get Country by ID

Get details for a specific country.

Endpoint

GET /api/v1/countries/{id}

Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
id	number	Yes	Country ID

Response

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

Error Responses

400 Bad Request

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid country ID"
  }
}

404 Not Found

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

Examples

curl -X GET "{{host}}/api/v1/countries/1" \
  -H "Authorization: Bearer your_access_token"

<?php
function getCountryById($accessToken, $countryId) {
    $ch = curl_init("{{host}}/api/v1/countries/{$countryId}");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 404) {
        throw new Exception("Country not found: {$countryId}");
    }

    return json_decode($response, true);
}
?>

Countries

On this page