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

Students

Register a student

POST
/v1/student
Try it in the sandbox

Creates a student under your account. From then on the student is one of yours: you can read and update them, send them a sign-in link, and apply them to exams.

What to look up first

  • country is the _id of a country from listCountries. A name or an ISO code is refused.
  • grade is the _id of a grade from listGrades, or its name, 1 to 12.
  • city is a city’s _id or its name within country, and school a school’s _id or its name within that country and city. There is no list of cities or schools: send the names your records hold. Names are matched without regard to case, and one that matches nothing is refused with 400. No country, grade, city or school is ever created.

What is set for you

  • username: the country’s two-letter code, a letter and a number, such as XXB1045 with a real code in place of XX. You cannot choose it, and it is how the student signs in and how support finds the account.
  • fullName, from firstName and lastName.
  • activatedPlatformsThisSeason: ["common"] unless you send a list.
  • emailConfirmed: false. Only the student can confirm their address.

A password is optional, and needs a second permission. Sending password needs auth/signin on mto as well as student/create; without it the request is refused with 403 before anything is read or written. It is stored hashed and never returned, and hashing is deliberately slow, so a registration that carries one takes a second or more longer. Leave it out to sign the student in with createSigninLink instead, or set one later with setStudentPassword.

Not idempotent. Registering an email address one of your students already has is refused with 409, and the message ends with that student’s _id, so a replayed batch can fetch the student rather than create a second one. An address another account registered is refused with 409 as well, without an id.

The answer has country, city, school and grade as ids; getStudent resolves them. An organization holds no record of the student until they have signed in there once, for instance through a link from createSigninLink, and until then createApplication on that organization is refused with 409.

Request body

application/jsonrequired

  • firstNamestringrequired

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

    exampleJane

  • lastNamestringrequired

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

    exampleDoe

  • birthstringrequired

    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

  • sexstringrequired

    One of m, f or n.

    one ofmfn

    examplef

  • emailstringrequired

    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

  • countrystringrequired

    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

  • gradestringrequired

    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

  • schoolstringrequired

    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

  • citystringrequired

    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

  • passwordstring

    The student’s sign-in password. Accepted only from an account that holds auth/signin on mto; from any other the registration is refused with 403. At least 5 characters, the minimum the sign-up form applies, and at most 72 bytes, and not containing the student’s own name or email address. Stored hashed, and never returned by any operation. Omit it to register the student without one.

    min length5examplecorrect horse battery staple

  • activatedPlatformsThisSeasonarray of string

    The organizations the student takes part in this season, by slug (as listOrganizations gives it, except mto: the core record, which every student is on), or common for every organization. Registration sets ["common"] when you leave it out; null is refused with 400. At most 6 entries.

    each one ofcommonstemhilinguaneogmathcoding

    max items6example["common"]

Responses

201 Created

Created: message is "User registered successfully.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleUser registered 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": "User registered 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 POST 'https://api.main-team.org/v1/student' \
  -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",
  "password": "correct horse battery staple",
  "activatedPlatformsThisSeason": [
    "common"
  ]
}
JSON

Search the API documentation

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