List your students who can use this organization

GET

/v1/{organizationId}/student

Bearer token
Permissionstudent/read
Per organization

Lists the students your account registered who can use this organization: those whose activatedPlatformsThisSeason holds its slug or common. A student of yours without access is left out until you grant it with updateOrgStudent. Students registered by other accounts are never listed.

Each student is the record you registered, the same one getStudent returns, with country, city, school, grade, supervisor and partner resolved into records. A supervisor linked with linkStudentSupervisor does not show here: that link is kept on this organization’s own record of the student.

Signed in or not. Each student also carries signedIn: whether they have signed in to this organization at least once. The organization keeps its own record of a student from that first sign-in, and createApplication and linkStudentSupervisor there need it. Send signedIn=false to list the students who still have to sign in, to send each a link from createSigninLink, and signedIn=true for the students ready for applications. The filter narrows pagination.total too, and anything but true or false is refused with 400.

Paginated: page starts at 1, and limit is 20 unless you ask for between 1 and 100. A value that is not a number falls back to the default, and one out of range to the nearest bound; neither is refused.

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
`signedIn`optional	boolean	`true` for only the students who have signed in to this organization at least once, `false` for only those who have not. Leave it out for both. Anything but `true` or `false` is refused with `400`. Example `false`
`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 "Students fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleStudents 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 OrgStudentResponserequired
21 fields of each item
- _idstringrequired
  The student’s id: what every studentId path parameter and body field takes.
  example6650a1b2c3d4e5f6a7b8c9d0
- mainIdstring
  Only on an organization’s own copy of a student, which linkStudentSupervisor answers with: there it is the student’s id, and _id is the organization’s own. Absent on every other operation.
  example6650a1b2c3d4e5f6a7b8c9d0
- usernamestringrequired
  Issued at registration, never chosen by you: the country’s two-letter code, a letter, then a number. It is how the student signs in and how support refers to the account.
  exampleXXB1045
- firstNamestringrequired
  The student’s first name.
  exampleJane
- lastNamestringrequired
  The student’s surname.
  exampleDoe
- fullNamestringrequired
  firstName and lastName joined by a space, kept in step when either changes.
  exampleJane Doe
- emailstringrequired
  The student’s email address, in lower case.
  examplejane.doe@example.com
- emailConfirmedbooleanrequired
  Whether the student has confirmed email. It starts false, only the student can make it true, and changing email sets it back to false. Once it is true, setStudentPassword is refused: the account is the student’s.
  examplefalse
- phonestring
  A phone number, as you sent it.
  example+1 555 0100
- birthstring
  Date of birth, DD/MM/YYYY.
  example14/05/2008
- sexstring
  m, f or n.
  one ofmfn
  examplef
- countryobject · CountryResponsenullable
  The student’s country. null if the stored reference no longer resolves; absent when none is set.
  9 fields of country
  _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
- cityobject · CityResponsenullable
  The student’s city. null if the stored reference no longer resolves; absent when none is set.
  6 fields of city
  _idstringrequired
  The city’s id.
  example6650a1b2c3d4e5f6a7b8c9d2
  namestring
  The city’s name, in capitals.
  exampleSPRINGFIELD
  countrystring
  The id of the country the city is in, where one is recorded.
  example6650a1b2c3d4e5f6a7b8c9d1
  stateCodestring
  A state or region code, where one is recorded.
  exampleIL
  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
- schoolobject · SchoolResponsenullable
  The student’s school. null if the stored reference no longer resolves; absent when none is set.
  6 fields of school
  _idstringrequired
  The school’s id.
  example6650a1b2c3d4e5f6a7b8c9d3
  namestring
  The school’s name, in capitals.
  exampleSPRINGFIELD HIGH SCHOOL
  countrystring
  The id of the school’s country, where one is recorded.
  example6650a1b2c3d4e5f6a7b8c9d1
  citystring
  The id of the school’s city, where one is recorded.
  example6650a1b2c3d4e5f6a7b8c9d2
  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
- gradeobject · GradeResponsenullable
  The student’s grade, which decides the exams they are offered. null if the stored reference no longer resolves; absent when none is set.
  4 fields of grade
  _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
- supervisorobject · PersonRefResponsenullable
  The supervisor the student is attached to across the platform. A supervisor you link with linkStudentSupervisor is set on that one organization’s copy of the student, and does not appear here. null if the stored reference no longer resolves; absent when none is set.
  6 fields of supervisor
  _idstringrequired
  Their id.
  example6650a1b2c3d4e5f6a7b8c9d5
  mainIdstring
  Their main id, when this is an organization’s own copy of them. Absent otherwise.
  example6650a1b2c3d4e5f6a7b8c9d5
  firstNamestring
  Their first name.
  exampleJohn
  lastNamestring
  Their surname.
  exampleSmith
  fullNamestring
  Their first name and surname, joined by a space.
  exampleJohn Smith
  usernamestring
  Their username, in capitals. For a supervisor, the value linkStudentSupervisor takes.
  exampleXXT1003
- partnerobject · PersonRefResponsenullable
  The partner the student is attached to. null if the stored reference no longer resolves; absent when none is set.
  6 fields of partner
  _idstringrequired
  Their id.
  example6650a1b2c3d4e5f6a7b8c9d5
  mainIdstring
  Their main id, when this is an organization’s own copy of them. Absent otherwise.
  example6650a1b2c3d4e5f6a7b8c9d5
  firstNamestring
  Their first name.
  exampleJohn
  lastNamestring
  Their surname.
  exampleSmith
  fullNamestring
  Their first name and surname, joined by a space.
  exampleJohn Smith
  usernamestring
  Their username, in capitals. For a supervisor, the value linkStudentSupervisor takes.
  exampleXXT1003
- activatedPlatformsThisSeasonarray of stringrequired
  The organizations the student is active on this season, by slug; common means every organization. Registration sets common unless you send a list. The organization-scoped student operations see a student only when this lists that organization or common, and updating a student through one adds that organization.
  example["common"]
- createdAtstringrequired
  When the student was registered.
  formatdate-timeexample2026-09-01T09:30:00.000Z
- updatedAtstringrequired
  When the record last changed.
  formatdate-timeexample2026-09-02T14:05:00.000Z
- signedInbooleanrequired
  Whether the student has signed in to this organization at least once. The organization keeps its own record of a student from that first sign-in, and until then createApplication and linkStudentSupervisor there are refused. Send them a link from createSigninLink to change it.
  exampletrue

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": "Students fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9d0",
      "mainId": "6650a1b2c3d4e5f6a7b8c9d0",
      "username": "XXB1045",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "email": "jane.doe@example.com",
      "emailConfirmed": false,
      "phone": "+1 555 0100",
      "birth": "14/05/2008",
      "sex": "f",
      "country": {
        "_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"
      },
      "city": {
        "_id": "6650a1b2c3d4e5f6a7b8c9d2",
        "name": "SPRINGFIELD",
        "country": "6650a1b2c3d4e5f6a7b8c9d1",
        "stateCode": "IL",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "school": {
        "_id": "6650a1b2c3d4e5f6a7b8c9d3",
        "name": "SPRINGFIELD HIGH SCHOOL",
        "country": "6650a1b2c3d4e5f6a7b8c9d1",
        "city": "6650a1b2c3d4e5f6a7b8c9d2",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "grade": {
        "_id": "6650a1b2c3d4e5f6a7b8c9d4",
        "name": "10",
        "createdAt": "2026-09-01T09:30:00.000Z",
        "updatedAt": "2026-09-02T14:05:00.000Z"
      },
      "supervisor": {
        "_id": "6650a1b2c3d4e5f6a7b8c9d5",
        "mainId": "6650a1b2c3d4e5f6a7b8c9d5",
        "firstName": "John",
        "lastName": "Smith",
        "fullName": "John Smith",
        "username": "XXT1003"
      },
      "partner": {
        "_id": "6650a1b2c3d4e5f6a7b8c9d5",
        "mainId": "6650a1b2c3d4e5f6a7b8c9d5",
        "firstName": "John",
        "lastName": "Smith",
        "fullName": "John Smith",
        "username": "XXT1003"
      },
      "activatedPlatformsThisSeason": [
        "common"
      ],
      "createdAt": "2026-09-01T09:30:00.000Z",
      "updatedAt": "2026-09-02T14:05:00.000Z",
      "signedIn": true
    }
  ]
}

400 Bad request

bad_request: signedIn is given, and is neither true nor false.

When

bad_request
signedIn is given, and is neither true nor false.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "signedIn must be true or false",
    "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.

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 student/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 student/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 who can use this organization

Parameters

Path parameters

Query parameters

Responses

Example request

Try it