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

Students

Update one of your students and give them access to this organization

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

Changes the fields you send and leaves the rest as they are: no field is required, and one you leave out is not cleared. It writes the student’s one record, the one getStudent returns and every organization shares, so a change made here shows everywhere.

Access to this organization. Leave activatedPlatformsThisSeason out and this organization’s slug is added to it, unless it already holds common. The student then shows in listOrgStudents and can be sent a link with createSigninLink. This is how you give a student access, so unlike the reads it does not need them to have it already, and an empty body, {}, does only that. If you do send activatedPlatformsThisSeason, the values you send are added to the stored list, and this organization is added only if you name it. The list only ever grows: nothing is removed, a value it already holds is not added twice, and [] adds nothing.

Fields follow registration’s rules: birth is a date that exists, as DD/MM/YYYY (31/02/2008 is refused), sex is m, f or n, country is an id from listCountries, and grade, city and school take an id or a name. A city name is looked up in the student’s country, and a school name in their country and city: the ones in this body, or else the stored ones. A name or id that matches nothing is refused; nothing is ever created. firstName, lastName, birth and sex can be changed but not cleared: an empty value or null is refused. phone is cleared with "". password is refused here: use setStudentPassword.

Email. A new address sets emailConfirmed back to false, since nobody has confirmed it yet. Sending the address the student already has, in any letter case, changes nothing. An address another student already has is refused.

Sending the same body again leaves the student as the first call did. Answers with the stored record, references as ids; read the student to have them resolved. Only students your account registered can be updated; another account’s student answers 404, like an unknown id.

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

  • firstNamestring

    The student’s first name. Printed on certificates and reports, followed by lastName.

    exampleJane

  • lastNamestring

    The student’s surname. Printed on certificates and reports after firstName. It cannot be empty.

    exampleDoe

  • birthstring

    Date of birth as DD/MM/YYYY, and a date that exists: 31/02/2008 is refused. An ISO date such as 2008-05-14 is refused.

    pattern^(0[1-9]|[12]\d|3[01])\/(0[1-9]|1[0-2])\/\d{4}$example14/05/2008

  • sexstring

    One of m, f or n.

    one ofmfn

    examplef

  • emailstring

    The student’s email address, stored in lower case. An address belongs to one student on the whole platform, so one already registered, by your account or another, is refused with 409.

    formatemailexamplejane.doe@example.com

  • email2string

    Leave this out. Any value but an empty one is refused with 400.

  • phonestring

    A phone number, stored as you send it. No format is checked. On an update, "" clears it.

    example+1 555 0100

  • countrystring

    The _id of a country, from listCountries (GET /v1/country). An id only: a name or an ISO code is refused. Its two-letter code starts the student’s username.

    pattern^[0-9a-fA-F]{24}$example6650a1b2c3d4e5f6a7b8c9d1

  • gradestring

    The _id of a grade, from listGrades (GET /v1/grade), or its name, 1 to 12. Either way the grade’s _id is what is stored. One that matches no grade is refused with 400. The grade decides which exams the student is offered.

    example10

  • schoolstring

    The _id of a school, or its name within country and city, matched without regard to case. There is no list of schools to look one up in: send the name your records hold. One that matches no school is refused with 400; no school is ever created.

    exampleSpringfield High School

  • citystring

    The _id of a city, or its name within country, matched without regard to case. There is no list of cities to look one up in: send the name your records hold. One that matches no city is refused with 400; no city is ever created.

    exampleSpringfield

  • activatedPlatformsThisSeasonarray of string

    Organization slugs, or 'common' for every organization, to add to the student's list. Nothing is ever removed: a value the list already holds is not added twice, and [] adds nothing. Leave it out to add this organization, which adds nothing if the list holds 'common'. Send it and only what you name is added, so this organization is added only if you name it.

    each one ofcommonstemhilinguaneogmathcoding

    max items6example["stem"]

Responses

200 OK

Success: message is "Student updated successfully.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleStudent updated successfully.

  • dataobject · StudentRecordResponserequired

    One of your students as stored, with country, city, school, grade, supervisor and partner as ids. What registration, the updates and setStudentPassword answer with; read the student to have them resolved.

    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

    • 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

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 updated 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": "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"
  }
}

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>' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "firstName": "Jane",
  "lastName": "Doe",
  "birth": "14/05/2008",
  "sex": "f",
  "email": "jane.doe@example.com",
  "email2": "<email2>",
  "phone": "+1 555 0100",
  "country": "6650a1b2c3d4e5f6a7b8c9d1",
  "grade": "10",
  "school": "Springfield High School",
  "city": "Springfield",
  "activatedPlatformsThisSeason": [
    "stem"
  ]
}
JSON

Search the API documentation

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