List Countries

An overview of the List Countries endpoint.

Endpoint Description

The List Countries endpoint provides the list of countries and the country codes which can be used when creating companies (subscriptions) or locations through the API that require a country code.

HTTP Method

GET /api/v2/system/countries

Request

Headers:

• Content-Type: application/json - Specifies that the request body format is JSON.

• Accept: application/json - Indicates that the client expects a JSON response.

• Authorization: Bearer {token} - A valid Bearer token must be provided to authenticate the request.

Query Parameters

• search (string, optional): Input a full or partial search term to filter against country names or country codes.

• page (Integer, Required): Specifies the page number in the pagination sequence to retrieve a specific set of results.

• limit (Integer, Required): Specifies the number of records to retrieve per page, controlling the volume of data returned.

Request Examples

Bash

curl --request GET \
    --get "http://r1discoverapi.local/api/v2/system/countries?search=united&page=1&limit=50" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "Authorization: Bearer {token}"

JavaScript

const url = new URL(
    "http://r1discoverapi.local/api/v2/system/countries"
);

const params = {
    "search": "united",
    "page": "1",
    "limit": "50",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

C# - Http

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.r1learning.com/api/v2/system/countries?search=united&page=1&limit=50");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer {token}");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

Meta:

Each List endpoint will contain a meta element which will describe the returned package. In this endpoint, the meta will provide the following information:

• total_items (Integer): The number of parent programs returned

• total pages (integer): The number of pages returned in the call to the endpoint. (Total Items / per_page limit)

• current_page (integer): Indicates the current page number of the results

• per_page (integer): Indicates the number of results (topics) that will be listed on a single page. The default is 50, the limit is 100.

Data Dictionary:

• code (string): The two digit code for the listed country

• name (String): The name of the country

Response Examples

200: OK

{
    "meta": {
        "total_items": 2,
        "total_pages": 1,
        "current_page": "1",
        "per_page": "50"
    },
    "country_list": [
        {
            "code": "GB",
            "name": "United Kingdom"
        },
        {
            "code": "US",
            "name": "United States"
        }
    ]
}

401: Unauthorized

{
    "error": 1,
    "message": "Unauthenticated",
    "details": "Authentication is required to access this resource."
}

403: Unauthorized

{
    "error": 1,
    "message": "Unauthorized",
    "details": "You do not have the necessary permissions to perform this action."
}

Postman Link

https://www.postman.com/fbomher/r1-discover-api/request/yhotk7l/list-countrieswww.postman.com

Link to the endpoint in Postman

Notes

• Authorization Required: Ensure the provided Bearer token is valid and has sufficient privileges to access the endpoint.

• Response Handling: Implement pagination to manage data effectively, especially when dealing with large datasets.