List the exams open for applications

GET

/v1/{organizationId}/exam

Bearer token
Permissionexam/read
Per organization

Lists the organization’s exams that are open for applications, the soonest sitting first.

An exam is open for applications while all three hold: it is not closed to applications (preventApplication is not true), its sitting (session.date) is still to come, and its category is active. It stops being open at the moment its sitting starts. An exam that is not open is not listed, and getExam and createApplication refuse it too.

session, category, language, grades and countries come back as records rather than ids. An exam with no language is listed, but no student can apply to it.

This list is the same for every student: it does not look at grades, countries or what a student already applied for. To see what one of your students can actually apply to, call listAvailableExams.

A page holds 20 exams unless you ask for up to 100 with limit. A read only: nothing changes, and it is safe to repeat.

Parameters

Path parameters

Name	Type	Description
`organizationId`required	stringpattern `^[0-9a-f]{24}$`	The organization’s `_id`: 24 hexadecimal digits, as `listOrganizations` (`GET /v1/organization`) lists it. Example `64b7f0c2a1d3e4f5a6b7c8d9`

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 "Exams fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleExams 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 ExamResponserequired
14 fields of each item
- _idstringrequired
  The exam’s id: the examId that createApplication and moveApplication take.
  example6650a1b2c3d4e5f6a7b8c9e1
- sessionobject · ExamSessionResponserequired
  The sitting the exam is on.
  13 fields of session
  _idstringrequired
  The sitting’s id.
  example6650a1b2c3d4e5f6a7b8c9e2
  sessionNamestring
  The sitting’s name.
  exampleNovember 2026
  datestring
  When the sitting takes place. Its exams are open for applications until this moment, and not after.
  formatdate-timeexample2026-11-14T10:00:00.000Z
  startTimestring
  The start time as the organization wrote it. For the moment itself, read date.
  example10:00
  tzstring
  global: the sitting starts at one moment everywhere. local: it starts at the same clock time in each student’s own time zone, their country’s tz.
  one ofgloballocal
  exampleglobal
  sessionAliasstring
  A second name for the sitting, shown to students.
  exampleAutumn round
  sessionNotestring
  A note about the sitting, shown to students.
  examplePlease join ten minutes early.
  enableSimulationboolean
  Whether students get a practice run before the sitting.
  exampletrue
  simulationDatestring
  When the practice run opens.
  formatdate-timeexample2026-11-07T10:00:00.000Z
  simulationEndDatestring
  When the practice run closes.
  formatdate-timeexample2026-11-08T10:00:00.000Z
  relatedSessionstring
  Set on a make-up sitting: the id of the sitting it belongs to. An application to an exam on a make-up sitting is removed 6 hours after it is made.
  example6650a1b2c3d4e5f6a7b8c9e2
  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
- categoryobject · ExamCategoryResponserequired
  The exam’s category.
  9 fields of category
  _idstringrequired
  The category’s id.
  example6650a1b2c3d4e5f6a7b8c9e3
  namestring
  The category’s name, as students see it.
  exampleMathematics
  altNamestring
  A second name for the category, where one is set.
  exampleMaths
  ordernumber
  Where the category sorts among the others, lowest first. The available-exams tree is in this order.
  example1
  isActiveboolean
  Whether the category is live. No exam in an inactive category is open for applications.
  exampletrue
  nonAcceptedReplacementsarray of string
  Ids of the categories an application in this one may not be moved to: moveApplication refuses such a move.
  example["6650a1b2c3d4e5f6a7b8c9ea"]
  studyMaterialLinksarray of string
  Links to study material for the category.
  example["https://example.org/study/mathematics"]
  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
- languageobject · LanguageResponsenullable
  The language the exam is sat in. Absent or null when it has none: such an exam is listed, but not offered to students, and cannot be applied to.
  6 fields of language
  _idstringrequired
  The language’s id.
  example6650a1b2c3d4e5f6a7b8c9e4
  namestring
  The language’s name.
  exampleEnglish
  codestring
  A short language code.
  exampleen
  ordernumber
  Where the language sorts among the others, lowest first. The available-exams tree is in this order.
  example1
  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
- gradesarray of GradeResponserequired
  The grades that may sit the exam. A student in any other grade is not offered it and cannot apply to it.
  4 fields of each item
  _idstringrequired
  The grade’s id: what grade takes when you register or update a student. A grade has the same id in every organization.
  example6650a1b2c3d4e5f6a7b8c9d4
  namestring
  The grade, as a number in a string, 1 to 12. grade accepts this name as well as the id.
  example10
  createdAtstring
  When the record was created. The grade list is in this order.
  formatdate-timeexample2026-09-01T09:30:00.000Z
  updatedAtstring
  When the record last changed.
  formatdate-timeexample2026-09-02T14:05:00.000Z
- countriesarray of CountryResponserequired
  The countries the exam is restricted to; empty or absent, it is open to every country. These are the organization’s own country records, whose ids need not match the ones listCountries gives: compare them with a student’s country by iso2.
  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
- examTypestring
  standard or essay.
  one ofstandardessay
  examplestandard
- examTimenumber
  The time limit, in minutes, from when the student starts.
  example75
- durationnumber
  How many hours the exam can be started in, counted from the start of the sitting.
  example15
- questionCountnumber
  How many questions the exam has.
  example30
- pricenumber
  What an application costs, as a number; no currency is given. Absent when the exam has no price: an application to it is charged 0.
  example25
- preventApplicationboolean
  Whether the exam is closed to new applications. A closed exam is never listed, so on the exam reads this is false or absent.
  examplefalse
- 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": "Exams fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9e1",
      "session": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e2",
        "sessionName": "November 2026",
        "date": "2026-11-14T10:00:00.000Z",
        "startTime": "10:00",
        "tz": "global",
        "sessionAlias": "Autumn round",
        "sessionNote": "Please join ten minutes early.",
        "enableSimulation": true,
        "simulationDate": "2026-11-07T10:00:00.000Z",
        "simulationEndDate": "2026-11-08T10:00:00.000Z",
        "relatedSession": "6650a1b2c3d4e5f6a7b8c9e2",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "category": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e3",
        "name": "Mathematics",
        "altName": "Maths",
        "order": 1,
        "isActive": true,
        "nonAcceptedReplacements": [
          "6650a1b2c3d4e5f6a7b8c9ea"
        ],
        "studyMaterialLinks": [
          "https://example.org/study/mathematics"
        ],
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "language": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e4",
        "name": "English",
        "code": "en",
        "order": 1,
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "grades": [
        {
          "_id": "6650a1b2c3d4e5f6a7b8c9d4",
          "name": "10",
          "createdAt": "2026-09-01T09:30:00.000Z",
          "updatedAt": "2026-09-02T14:05:00.000Z"
        }
      ],
      "countries": [
        {
          "_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"
        }
      ],
      "examType": "standard",
      "examTime": 75,
      "duration": 15,
      "questionCount": 30,
      "price": 25,
      "preventApplication": false,
      "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 exam/read on the organization in the path, or a role denies it.

When

forbidden
The token is valid, but no role on your account allows exam/read on the organization in the path, 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.

404 Not found

not_found: organizationId is not the _id of an organization.

When

not_found
organizationId is not the _id of an organization.

Example

{
  "error": {
    "code": "not_found",
    "documentation_url": "https://hub.main-team.org/api/errors#not_found",
    "message": "Organization not found!",
    "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.

List the exams open for applications

Parameters

Path parameters

Query parameters

Responses

Example request

Try it