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

Students

Link one of your students to a supervisor on this organization

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

Attaches the student to a supervisor of this organization, found by supervisorUsername. Any supervisor of this organization can be linked.

The link is made on this organization only. Each organization keeps its own record of a student and the link is written there, so the student’s records on other organizations are left as they were. Neither getStudent nor getOrgStudent shows it: both read the record you registered. The link stays when the student signs in again. Linking another supervisor replaces the first on this organization, and repeating a link changes nothing.

The student has to have signed in to this organization once, with a link from createSigninLink. That first sign-in is when the organization creates its record of them, and before it there is nothing to link.

Every refusal is the same 404, Not found!: a student who is not yours, a student this organization has no record of yet, a username nobody has here, and one whose owner is not a supervisor here. The answer never says which, and never repeats the username. A malformed studentId, or a supervisorUsername that is missing or empty, is a 400; one of spaces only is the 404.

Answers with the organization’s slug; this organization’s record of the student after the link, whose _id is this organization’s own id for the student and whose mainId is the id you use everywhere else; and the supervisor’s id and username.

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.

Request body

application/jsonrequired

  • supervisorUsernamestringrequired

    The username of a supervisor on this organization, as they sign in with it. Letter case and surrounding spaces do not matter.

    exampleXXT1003

Responses

200 OK

Success: message is "Student linked to supervisor successfully.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleStudent linked to supervisor successfully.

  • dataobject · SupervisorLinkResponserequired

    A supervisor link, made on one organization only: the other organizations’ records of the student are left as they were.

    3 fields of data

    • organizationstringrequired

      The slug of the organization the link was made on.

      examplestem

    • studentobject · StudentRecordResponserequired

      The organization’s own copy of the student, after the link. Its _id is that organization’s id for the student, and mainId is the id you use everywhere else. supervisor is the supervisor’s id in the organization, and the other references are ids as that organization stores them.

      20 fields of student

      • _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

      • countrystring

        The id of the student’s country.

        example6650a1b2c3d4e5f6a7b8c9d1

      • citystring

        The id of the student’s city. A city you sent by name is stored as the id it resolved to.

        example6650a1b2c3d4e5f6a7b8c9d2

      • schoolstring

        The id of the student’s school. A school you sent by name is stored as the id it resolved to.

        example6650a1b2c3d4e5f6a7b8c9d3

      • gradestring

        The id of the student’s grade. A grade you sent by name is stored as the id it resolved to.

        example6650a1b2c3d4e5f6a7b8c9d4

      • supervisorstring

        The id of the student’s supervisor, when one is attached.

        example6650a1b2c3d4e5f6a7b8c9d5

      • partnerstring

        The id of the student’s partner, when one is attached.

        example6650a1b2c3d4e5f6a7b8c9d6

      • 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

    • supervisorobject · LinkedSupervisorResponserequired

      The supervisor the student is now linked to.

      2 fields of supervisor

      • _idstringrequired

        The supervisor’s id in this organization.

        example6650a1b2c3d4e5f6a7b8c9d5

      • usernamestringrequired

        The supervisor’s username, in capitals.

        exampleXXT1003

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 linked to supervisor successfully.",
  "data": {
    "organization": "stem",
    "student": {
      "_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": "6650a1b2c3d4e5f6a7b8c9d1",
      "city": "6650a1b2c3d4e5f6a7b8c9d2",
      "school": "6650a1b2c3d4e5f6a7b8c9d3",
      "grade": "6650a1b2c3d4e5f6a7b8c9d4",
      "supervisor": "6650a1b2c3d4e5f6a7b8c9d5",
      "partner": "6650a1b2c3d4e5f6a7b8c9d6",
      "activatedPlatformsThisSeason": [
        "common"
      ],
      "createdAt": "2026-09-01T09:30:00.000Z",
      "updatedAt": "2026-09-02T14:05:00.000Z"
    },
    "supervisor": {
      "_id": "6650a1b2c3d4e5f6a7b8c9d5",
      "username": "XXT1003"
    }
  }
}

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS -X PUT 'https://api.main-team.org/v1/<organizationId>/student/<studentId>/supervisor' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "supervisorUsername": "XXT1003"
}
JSON

Search the API documentation

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