List your students

GET

/v1/student

Bearer token
Permissionstudent/read
Core record

Lists the students your account registered, with country, city, school, grade, supervisor and partner resolved into records. A student another account registered never appears, even one with the same name.

Twenty students to a page unless you set limit, which is at most 100; a larger one is read as 100, and a page or limit that is not a number is read as the default rather than refused. pagination.total counts every one of your students, and pagination.totalPages says when to stop.

The students come in no guaranteed order, so a student registered while you page through can move others between pages. To find one student, keep the _id registerStudent answered with and call getStudent.

Find students by email address. email takes one address, or up to 100 separated by commas, and lists only your students who have one of them, matched exactly and without regard to case. Use it to find the _id of a student you registered earlier, such as after registerStudent answered 409 for an address that is already one of your students’. An address none of your students has matches nothing, whoever else holds it: the filter never looks beyond your own students. pagination.total counts the matches.

Parameters

Query parameters

Name	Type	Description
`email`optional	string	Only the students with one of these email addresses, separated by commas: at most 100. Matched exactly, without regard to case. An address none of your students has matches nothing. Refused with `400` when it is empty, given twice, holds a value that is not an address, or lists more than 100. Example `ada.lovelace@example.org,grace.hopper@example.org`
`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 StudentResponserequired
20 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

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

400 Bad request

bad_request: email is empty, is given twice, or holds a value that is not an email address.
bad_request: email lists more than 100 addresses.

When

bad_request
email is empty, is given twice, or holds a value that is not an email address.
bad_request
email lists more than 100 addresses.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "email must be given once, as one or more email addresses separated by commas",
    "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 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 student/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.

List your students

Parameters

Query parameters

Responses

Example request

Try it