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

Students

Update one of your students

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

Changes the fields you send on one of your students and leaves every other field as it is. Every field is optional here, and each one you send follows the same rules as in registerStudent. password is not accepted (400): use setStudentPassword.

  • A city or school sent by name is looked up within the student’s country and city: the ones in this request, or else the ones already stored.
  • Changing firstName or lastName updates fullName.
  • firstName, lastName, birth and sex can be changed but not cleared: an empty value or null is refused. phone is cleared with "". birth has to be a date that exists: 31/02/2008 is refused.
  • activatedPlatformsThisSeason is added to the stored list, never written over it: nothing is removed, a value already there is not added twice, and [] adds nothing.
  • Changing email to a different address sets emailConfirmed back to false. The student has to confirm the new address, and until they do setStudentPassword accepts a password for them again. Sending the address already stored, in any case, is not a change.

A student another account registered answers 404, exactly like one that does not exist. Sending the same body twice has the effect of sending it once. The answer has country, city, school, grade, supervisor and partner as ids; getStudent resolves them.

Parameters

Path parameters

NameTypeDescription
studentIdrequiredstring

The student’s _id, as registerStudent returned it: 24 hexadecimal digits. A student another account registered answers exactly like one that does not exist.

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 and the list stays as it is.

    each one ofcommonstemhilinguaneogmathcoding

    max items6example["neo"]

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/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": [
    "neo"
  ]
}
JSON

Search the API documentation

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