List the countries a student can be registered in

GET

/v1/country

Bearer token
Permissioncountry/read
Core record

Every country you can give as a student’s country, a page at a time (limit up to 100). Reference data: the same list whichever organization you work with.

country on the student operations takes the _id from here and nothing else: not the name, iso2 or iso3. A few countries are reserved for internal use; they are not listed, and a student cannot be registered in one.

An exam’s countries are the organization’s own records, whose ids need not match these: compare them by iso2.

The list is in no guaranteed order and rarely changes, so fetch it once and keep it.

Parameters

Query parameters

Name	Type	Description
`page`optional	number	Page number. Defaults to 1. Example `1`
`limit`optional	number	Items per page. Defaults to 20, max 100. Example `20`

Responses

200 OK

Success: message is "Countries fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleCountries fetched successfully.
paginationobject · PaginationMetarequired
Where one page sits in the whole list.
4 fields of pagination
- pagenumberrequired
  The page returned, counting from 1.
  min1example1
- limitnumberrequired
  Items per page: the limit you sent, 20 if you sent none, and never more than 100.
  min1max100example20
- totalnumberrequired
  Items across every page.
  min0example57
- totalPagesnumberrequired
  Pages at this limit: total / limit, rounded up.
  min0example3
dataarray of CountryResponserequired
9 fields of each item
- _idstringrequired
  The country’s id: what country takes when you register or update a student.
  example6650a1b2c3d4e5f6a7b8c9d1
- namestring
  The country’s name, in capitals.
  exampleUNITED STATES
- iso3string
  The ISO 3166-1 alpha-3 code, in capitals.
  exampleUSA
- iso2string
  The ISO 3166-1 alpha-2 code, in capitals. A student’s username starts with it.
  exampleUS
- tzstring
  The IANA time zone a sitting on local time is read in for students in this country (see tz on a sitting).
  exampleAmerica/New_York
- dialCodestring
  The international dialling code, with its +.
  example+1
- flagstring
  The country’s flag, as an emoji.
  example🇺🇸
- createdAtstring
  When the record was created.
  formatdate-timeexample2026-09-01T09:30:00.000Z
- updatedAtstring
  When the record last changed.
  formatdate-timeexample2026-09-02T14:05:00.000Z

Headers

X-RateLimit-Limit integer: Requests your account may make to this operation per window (100).
X-RateLimit-Remaining integer: Requests left in the current window.
X-RateLimit-Reset integer: Seconds until the current window ends.

Example

{
  "success": true,
  "message": "Countries fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9d1",
      "name": "UNITED STATES",
      "iso3": "USA",
      "iso2": "US",
      "tz": "America/New_York",
      "dialCode": "+1",
      "flag": "🇺🇸",
      "createdAt": "2026-09-01T09:30:00.000Z",
      "updatedAt": "2026-09-02T14:05:00.000Z"
    }
  ]
}

401 Unauthorized

unauthorized: The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

When

unauthorized
The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

Example

{
  "error": {
    "code": "unauthorized",
    "documentation_url": "https://hub.main-team.org/api/errors#unauthorized",
    "message": "Authentication is required or the provided credentials are invalid.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

403 Forbidden

forbidden: The token is valid, but no role on your account allows country/read on mto, the organization every operation without :organizationId acts on, or a role denies it.

When

forbidden
The token is valid, but no role on your account allows country/read on mto, the organization every operation without :organizationId acts on, or a role denies it.

Example

{
  "error": {
    "code": "forbidden",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "message": "Insufficient role permissions",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

429 Too many requests

too_many_requests: Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

When

too_many_requests
Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

Headers

Retry-After integer: Seconds to wait before sending again; a request sent sooner is refused too.

Example

{
  "error": {
    "code": "too_many_requests",
    "documentation_url": "https://hub.main-team.org/api/errors#too_many_requests",
    "message": "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

500 Internal error

internal_error: Something failed on our side. Retry later, and quote request_id if it goes on.

When

internal_error
Something failed on our side. Retry later, and quote request_id if it goes on.

Example

{
  "error": {
    "code": "internal_error",
    "documentation_url": "https://hub.main-team.org/api/errors#internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/country?page=1&limit=20' \
  -H "Authorization: Bearer $TOKEN"

const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/country?page=1&limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data, body.pagination);

<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/country?page=1&limit=20');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body['data']);
print_r($body['pagination']);