Skip to content
Olympiads Hub
API documentation
View as MarkdownOpen in Claude

Students

Fetch one of your students, if they can use this organization

GET
/v1/{organizationId}/student/{studentId}
Try it in the sandbox

Returns one student your account registered, if they can use this organization (their activatedPlatformsThisSeason holds its slug or common), with the references resolved as listOrgStudents returns them.

An unknown id, a student registered by another account and a student of yours without access to this organization all answer 404 not_found, the same way. A malformed id is a 400.

To give a student access, use updateOrgStudent.

Parameters

Path parameters

NameTypeDescription
organizationIdrequiredstringpattern ^[0-9a-f]{24}$

The organization’s _id: 24 hexadecimal digits, as listOrganizations (GET /v1/organization) lists it.

Example 64b7f0c2a1d3e4f5a6b7c8d9

studentIdrequiredstring

The student’s id (_id), as registerStudent returned it.

Responses

200 OK

Success: message is "Student fetched successfully".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleStudent fetched successfully

  • dataobject · StudentResponserequired

    One of your students, with country, city, school, grade, supervisor and partner resolved into records. What the student reads answer with.

    20 fields of data

    • _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": "Student fetched successfully",
  "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"
  }
}

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/<organizationId>/student/<studentId>' \
  -H "Authorization: Bearer $TOKEN"

Search the API documentation

Guides, endpoints by name, path or permission, and error codes such as not_found.