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

Students

Check a registration without registering the student

POST
/v1/student/check
Try it in the sandbox

Runs the checks registerStudent makes before it creates anything, on the same body without password, and tells you what they found. Nothing is created or changed and no username is issued, so sending it any number of times has no effect. Use it to validate a batch before you register it.

The body follows registerStudent’s rules, and one that breaks a rule is refused the same way, with 400: a missing or malformed field, null for phone or activatedPlatformsThisSeason, or a property the operation does not accept, password included.

The answer is 200 whatever the lookups found. data.valid is true when the registration would pass every check made here:

  • data.duplicate.sameAccount is true when one of your students already has this email address, and data.duplicate.studentId is that student’s _id: registerStudent would answer 409. Nothing else is looked up then, as registration does not look further either.
  • data.problems lists every country, grade, city and school that matches nothing, each as { field, message } with the message registerStudent would answer 400 with, where registration names only the first. A city or school named inside a country or city that matched nothing is not looked up, so fix the field above it first. A country whose students cannot be given a username is listed as well.
  • data.resolved has the _id each of the four resolved to, what registration would store, or null.

Only your own students are checked for the email address. An address a student on another account holds is not looked for and not reported, so valid: true is not a promise: registerStudent still answers 409 for such an address, without saying whose it is. Nor can the check foresee a student registered, or reference data changed, between the check and the registration.

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

  • 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

200 OK

Success: message is "Registration checked. Nothing was created.".

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleRegistration checked. Nothing was created.

  • dataobject · RegistrationCheckResponserequired

    What checkStudentRegistration found: whether registerStudent with the same body would pass the checks it makes before it writes, and why not.

    4 fields of data

    • validbooleanrequired

      true when no student of yours has the email address and every reference resolved: duplicate.sameAccount is false and problems is empty.

      examplefalse

    • problemsarray of RegistrationProblemResponserequired

      Every reference field that matched nothing, in the order country, grade, city, school, and the country again when its students cannot be given a username. A city or school name inside a country or city that matched nothing is not looked up, so not listed. Empty when the email address is one of your students’.

      2 fields of each item

      • fieldstringrequired

        The field: country, grade, city or school.

        one ofcountrygradecityschool

        exampleschool

      • messagestringrequired

        The message registerStudent answers 400 bad_request with for this field.

        exampleschool is not a known school. This API does not create reference data.

    • resolvedobject · ResolvedReferencesResponserequired

      The _id each reference resolved to. All four are null when the email address is one of your students’: nothing is looked up then.

      4 fields of resolved

      • countrystringnullablerequired

        The country’s _id; null if it matched nothing or was not looked up.

        example6650a1b2c3d4e5f6a7b8c9d1

      • gradestringnullablerequired

        The grade’s _id, also when you sent its name; null if it matched nothing or was not looked up.

        example6650a1b2c3d4e5f6a7b8c9d4

      • citystringnullablerequired

        The city’s _id, also when you sent its name; null if it matched nothing or was not looked up.

        example6650a1b2c3d4e5f6a7b8c9d2

      • schoolstringnullablerequired

        The school’s _id, also when you sent its name; null if it matched nothing or was not looked up.

        example6650a1b2c3d4e5f6a7b8c9d3

    • duplicateobject · RegistrationDuplicateResponserequired

      Whether one of your students already has the address.

      2 fields of duplicate

      • sameAccountbooleanrequired

        true when one of your students already has this email address, so registerStudent would answer 409 conflict.

        examplefalse

      • studentIdstring

        That student’s _id, only when sameAccount is true: the student to use instead of registering a second one.

        example6650a1b2c3d4e5f6a7b8c9d0

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": "Registration checked. Nothing was created.",
  "data": {
    "valid": false,
    "problems": [
      {
        "field": "school",
        "message": "school is not a known school. This API does not create reference data."
      }
    ],
    "resolved": {
      "city": "6650a1b2c3d4e5f6a7b8c9d2",
      "country": "6650a1b2c3d4e5f6a7b8c9d1",
      "grade": "6650a1b2c3d4e5f6a7b8c9d4",
      "school": null
    },
    "duplicate": {
      "sameAccount": false
    }
  }
}

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/check' \
  -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": [
    "common"
  ]
}
JSON

Search the API documentation

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