Countries

Access country reference data including country codes, names, and supported currencies.

List Countries

Get a list of all available countries.

Endpoint

GET /api/v1/countries

Authentication: Bearer token required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50, max: 10000)
page	number	No	Page number (default: 1)
search	string	No	Search countries by name or code

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,
    "code": "US",
    "name": "United States",
    "currency_code": "USD",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  {
    "id": 2,
    "code": "GB",
    "name": "United Kingdom",
    "currency_code": "GBP",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]

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
code	string	ISO 3166-1 alpha-2 country code
name	string	Country display name
currency_code	string	ISO 4217 currency code
is_active	boolean	Whether country is active/supported
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Examples

# Get all countries (use -i to see headers)
curl -X GET "{{host}}/api/v1/countries" -i \
  -H "Authorization: Bearer your_access_token"

# Search for specific countries with pagination headers
curl -X GET "{{host}}/api/v1/countries?search=united&limit=10" -i \
  -H "Authorization: Bearer your_access_token"

<?php
function getCountries($accessToken, $limit = 50, $page = 1, $search = null) {
    $params = [
        'limit' => $limit,
        'page' => $page
    ];

    if ($search) {
        $params['search'] = $search;
    }

    $url = '{{host}}/api/v1/countries?' . http_build_query($params);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);

    $response = curl_exec($ch);
    $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $headers = substr($response, 0, $header_size);
    $body = substr($response, $header_size);

    // Parse headers
    $headers_array = [];
    foreach (explode("\r\n", $headers) as $header) {
        if (strpos($header, 'X-') === 0) {
            list($key, $value) = explode(': ', $header, 2);
            $headers_array[$key] = $value;
        }
    }

    curl_close($ch);

    return [
        'data' => json_decode($body, true),
        'pagination' => [
            'page' => intval($headers_array['X-Page'] ?? 1),
            'per_page' => intval($headers_array['X-Per-Page'] ?? 50),
            'total_count' => intval($headers_array['X-Total-Count'] ?? 0),
            'total_pages' => intval($headers_array['X-Total-Pages'] ?? 0),
            'page_size' => intval($headers_array['X-Page-Size'] ?? 0),
            'has_more' => ($headers_array['X-Has-More'] ?? 'false') === '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,
  "code": "US",
  "name": "United States",
  "currency_code": "USD",
  "is_active": true,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

Error Responses

404 Not Found

{
  "error": "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