List your students’ applications in this organization

GET

/v1/{organizationId}/application

Bearer token
Permissionapplication/read
Per organization

Lists the applications of your students in this organization, with exam, payment and the student (user) resolved into records. Inside exam, session, category and language stay ids. Applications for closed and past exams are included.

A page at a time: limit is 20 by default and at most 100. No order is guaranteed, so to take a complete snapshot walk every page and remove duplicates by _id.

Your students are the ones your account registered. A student appears here only while they are activated for this organization (their activatedPlatformsThisSeason lists its slug or common) and once they have signed in to it. An application of a student no longer activated here is left out of this list, though listStudentApplications and getApplication still return it.

Match a row to your records by user.mainId, the id you registered the student with; user._id is the organization’s own id for them.

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

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleApplications 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 ApplicationResponserequired
16 fields of each item
- _idstringrequired
  The application’s id: what applicationId takes.
  example6650a1b2c3d4e5f6a7b8c9e5
- examobject · ExamRecordResponsenullablerequired
  The exam applied for. Its own session, category and language are ids. null if the exam no longer exists.
  14 fields of exam
  _idstringrequired
  The exam’s id: the examId that createApplication and moveApplication take.
  example6650a1b2c3d4e5f6a7b8c9e1
  sessionstring
  The id of the sitting the exam is on.
  example6650a1b2c3d4e5f6a7b8c9e2
  categorystring
  The id of the exam’s category.
  example6650a1b2c3d4e5f6a7b8c9e3
  languagestring
  The id of the language the exam is sat in, when it has one.
  example6650a1b2c3d4e5f6a7b8c9e4
  gradesarray of string
  The grades that may sit the exam. A student in any other grade is not offered it and cannot apply to it. Grade ids are the same in every organization.
  example["6650a1b2c3d4e5f6a7b8c9d4"]
  countriesarray of string
  The countries the exam is restricted to; empty or absent, it is open to every country. Ids of the organization’s own country records, which need not match the ones listCountries gives.
  example[]
  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
- userobject · StudentRefResponserequired
  The student the application is for.
  4 fields of user
  _idstringrequired
  The organization’s own id for the student. It differs from the id you registered them with: match on mainId.
  example6650a1b2c3d4e5f6a7b8c9e9
  mainIdstringrequired
  The student’s id: the one you registered them with, and what every studentId takes.
  example6650a1b2c3d4e5f6a7b8c9d0
  firstNamestring
  The student’s first name.
  exampleJane
  lastNamestring
  The student’s surname.
  exampleDoe
- paymentobject · PaymentResponsenullable
  The application’s payment. null if the stored reference no longer resolves; absent when none is set.
  8 fields of payment
  _idstringrequired
  The payment’s id.
  example6650a1b2c3d4e5f6a7b8c9e6
  statusstringrequired
  pending: not paid yet. paid: settled; a free exam’s payment is paid from the start, with amount 0. canceled: will not be paid. An application whose payment is paid with an amount above 0 cannot be deleted, and can move only to an exam of the same price.
  one ofpendingpaidcanceled
  examplepending
  amountnumber
  What is due, or was paid, as a number; no currency is given. 0 for a free exam. Moving an unpaid application to another exam changes it to that exam’s price.
  example25
  applicationstring
  The id of the application it pays for.
  example6650a1b2c3d4e5f6a7b8c9e5
  examstring
  The id of the exam it pays for.
  example6650a1b2c3d4e5f6a7b8c9e1
  forstring
  The organization’s own id for the student it is for.
  example6650a1b2c3d4e5f6a7b8c9e9
  createdAtstring
  When the payment was created.
  formatdate-timeexample2026-09-01T09:30:00.000Z
  updatedAtstring
  When the payment last changed.
  formatdate-timeexample2026-09-02T14:05:00.000Z
- partnersarray of ApplicationPartnerResponserequired
  On a team exam, the other members of the team. Empty for an exam sat alone.
  2 fields of each item
  userstring
  The team member’s id in this organization. Not one of your students’ ids, and not resolved.
  example6650a1b2c3d4e5f6a7b8c9d6
  acceptedboolean
  Whether they have accepted the invitation to the team.
  exampletrue
- participatedbooleanrequired
  Whether the student has started the exam. A started application cannot be moved to another exam.
  examplefalse
- examStartstring
  When the student started the exam; absent until then.
  formatdate-timeexample2026-11-14T10:04:12.000Z
- examSubmittedboolean
  Whether the student has handed the exam in. A handed-in application cannot be moved to another exam.
  examplefalse
- submitDatestring
  When the student handed the exam in; absent until then.
  formatdate-timeexample2026-11-14T11:12:40.000Z
- simulationStartedbooleanrequired
  Whether the student has started the practice run.
  examplefalse
- simulationStartstring
  When the student started the practice run; absent until then.
  formatdate-timeexample2026-11-07T10:00:00.000Z
- simulationSubmittedbooleanrequired
  Whether the student has handed the practice run in.
  examplefalse
- removeAfterstring
  Only on an application to an exam on a make-up sitting: when it will be removed, 6 hours after it was made.
  formatdate-timeexample2026-09-02T14:05:00.000Z
- uuidstringrequired
  A short reference code for the application.
  examplea3f-09c-7e1
- createdAtstringrequired
  When the application was made.
  formatdate-timeexample2026-09-01T09:30:00.000Z
- updatedAtstringrequired
  When the application 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": "Applications fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9e5",
      "exam": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e1",
        "session": "6650a1b2c3d4e5f6a7b8c9e2",
        "category": "6650a1b2c3d4e5f6a7b8c9e3",
        "language": "6650a1b2c3d4e5f6a7b8c9e4",
        "grades": [
          "6650a1b2c3d4e5f6a7b8c9d4"
        ],
        "countries": [],
        "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"
      },
      "user": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e9",
        "mainId": "6650a1b2c3d4e5f6a7b8c9d0",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "payment": {
        "_id": "6650a1b2c3d4e5f6a7b8c9e6",
        "status": "pending",
        "amount": 25,
        "application": "6650a1b2c3d4e5f6a7b8c9e5",
        "exam": "6650a1b2c3d4e5f6a7b8c9e1",
        "for": "6650a1b2c3d4e5f6a7b8c9e9",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "partners": [
        {
          "user": "6650a1b2c3d4e5f6a7b8c9d6",
          "accepted": true
        }
      ],
      "participated": false,
      "examStart": "2026-11-14T10:04:12.000Z",
      "examSubmitted": false,
      "submitDate": "2026-11-14T11:12:40.000Z",
      "simulationStarted": false,
      "simulationStart": "2026-11-07T10:00:00.000Z",
      "simulationSubmitted": false,
      "removeAfter": "2026-09-02T14:05:00.000Z",
      "uuid": "a3f-09c-7e1",
      "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 application/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 application/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 your students’ applications in this organization

Parameters

Path parameters

Query parameters

Responses

Example request

Try it