# List Countries

## Endpoint Description <a href="#endpoint-description" id="endpoint-description"></a>

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**

{% tabs %}
{% tab title="Bash" %}

```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}"
```

{% endtab %}

{% tab title="JavaScript" %}

```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());
```

{% endtab %}

{% tab title="C# - Http" %}

```csharp
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());
```

{% endtab %}
{% endtabs %}

## **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&#x20;
* **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

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "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"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

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

{% endtab %}

{% tab title="403: Unauthorized" %}

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

{% endtab %}
{% endtabs %}

## Postman Link

{% embed url="<https://www.postman.com/fbomher/r1-discover-api/request/yhotk7l/list-countries>" %}
Link to the endpoint in Postman
{% endembed %}

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.discover.r1learning.com/global-endpoints-system/list-countries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.