Applications

An application enters one student for one exam in one organization. It lives in that organization and always has a payment record attached. This page covers creating, moving, deleting and reading applications, with every rule the API enforces, in the order it enforces them.

Choose the exam first, from the exam picker. Every rule on this page that concerns the exam is the picker's rule, so a leaf from the picker is accepted.

Operations

Every permission's target is the organization in the path, or *. Each operation is its own permission, so your operator can grant an account creation without deletion. See Permissions.

Before you create one

Create an application

POST /v1/<organizationId>/application

Nothing else is accepted. Any other field, such as price or participated, is refused with 400 bad_request (property <name> should not exist).

curl -s -X POST "https://api.main-team.org/v1/<organizationId>/application" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "studentId": "652f1c9b8e4b2a0012a3c4d5", "examId": "66f1a2b3c4d5e6f708192a3b" }'

{
  "success": true,
  "message": "Application created successfully.",
  "data": {
    "_id": "6703d4e5f6a7b8c9d0e1f203",
    "exam": "66f1a2b3c4d5e6f708192a3b",
    "user": "66fa0b1c2d3e4f5a6b7c8d9e",
    "payment": "6703d4e5f6a7b8c9d0e1f204",
    "participated": false,
    "partners": [],
    "carriedPoints": 0,
    "uuid": "3fa-9c0-1be",
    "createdAt": "2026-09-15T10:42:07.512Z",
    "updatedAt": "2026-09-15T10:42:07.512Z"
  }
}

The examples on this page are trimmed: applications and payments come back with every stored field, so expect more than shown and ignore what you don't use.

A new application answers 201. In this response exam, user and payment are ids. user is the organization's id for the student, not the studentId you sent. Every organization keeps its own copy of a student under its own _id (see Identifiers). Match applications to your records by the studentId you sent, or by user.mainId when you read them back.

What is checked, in order

The first check that fails decides the answer.

Country names in these messages are upper case, as the platform stores them. Check 8 compares the student's country by name with the countries the organization knows. If the student has no country, or the organization has no country of that name, only exams open to every country pass.

If checks 5 to 9 ever disagree with the picker, the answer is a general 409 conflict: Exam is not available to this student. Only exams returned by GET /:organizationId/exam/available/:studentId can be applied to. You should never see it.

Why the rules exist:

• Open, grade, country, language (5 to 9). These are the picker's rules. An exam the student panel would never show a student can't be reached by passing its id either. The messages name the grades or countries the exam does accept, so you can act on them without looking anything up.
• One category per sitting (11). Nobody can sit two papers in the same category at the same time, and the second application would be a payment for something that can't happen. To change the language of an exam a student already holds, move the application.

Repeating a create is safe

Sending the same studentId and examId again doesn't create a second application. It answers 200 with Application already exists. and the application that is already there. That makes create safe to retry after a timeout: a 201 or a 200 both mean the student is entered.

One caveat: the exam checks (5 to 9) run before the repeat check (10). A repeat therefore returns 200 only while the exam is still offered to the student. After the sitting's date has passed, or if the student's grade changed, the same request answers 409. The existing application is untouched either way. If a retry gives you a 409, list the student's applications to see where you stand. See also Retries and idempotency.

What a new application contains

Creating an application also creates its payment record:

The student can see the application in the organization's panel straight away.

An application for a make-up sitting (a sitting whose relatedSession is set) is temporary. It is created with a removeAfter time six hours ahead, just like one made in the student panel. Don't treat it as permanent.

Code: create with every outcome handled

async function enterStudent(organizationId, studentId, examId) {
  const res = await fetch(`https://api.main-team.org/v1/${organizationId}/application`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${await getToken()}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ studentId, examId }),
  });
  const body = await res.json();

  if (res.status === 201) return { created: true, application: body.data };
  if (res.status === 200) return { created: false, application: body.data }; // already entered

  // 400, 404 and 409 are final: retrying the same request gives the same answer.
  // Show error.message to whoever chose the exam, because it says which rule failed.
  const { code, message, request_id } = body.error;
  throw Object.assign(new Error(message), { status: res.status, code, requestId: request_id });
}

<?php
function enterStudent(string $organizationId, string $studentId, string $examId): array
{
    $ch = curl_init("https://api.main-team.org/v1/{$organizationId}/application");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getToken(), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['studentId' => $studentId, 'examId' => $examId]),
    ]);
    $body = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($status === 201) return ['created' => true, 'application' => $body['data']];
    if ($status === 200) return ['created' => false, 'application' => $body['data']];

    $e = $body['error'];
    throw new RuntimeException("{$status} {$e['code']}: {$e['message']} (request {$e['request_id']})");
}

Payments

The API records what an application costs and whether it has been paid. It never takes, charges or refunds money. Payment happens on the platform, outside this API. That one fact explains most of the rules below.

Settled means status is paid and amount is greater than 0: someone actually paid money. A free exam's { "amount": 0, "status": "paid" } isn't settled, so it never blocks a move or a delete.

Move an application

PUT /v1/<organizationId>/application/<applicationId> points an existing application at a different exam. Use it to change the language, the sitting or, where the category allows it, the category. The application keeps its _id and its payment record, so it works like the "Update" button on the student's own exam card.

The body has one field, examId. It must be 24 hexadecimal characters, and it is usually a picker leaf's matchedExam._id. The student isn't in the body: the application already says whose it is, so sending studentId is refused with 400 bad_request (property studentId should not exist).

curl -s -X PUT "https://api.main-team.org/v1/<organizationId>/application/6703d4e5f6a7b8c9d0e1f203" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "examId": "66f1a2b3c4d5e6f708192a3c" }'

{
  "success": true,
  "message": "Application updated successfully.",
  "data": {
    "_id": "6703d4e5f6a7b8c9d0e1f203",
    "exam": "66f1a2b3c4d5e6f708192a3c",
    "user": "66fa0b1c2d3e4f5a6b7c8d9e",
    "payment": "6703d4e5f6a7b8c9d0e1f204",
    "participated": false,
    "partners": [],
    "createdAt": "2026-09-15T10:42:07.512Z",
    "updatedAt": "2026-09-16T08:05:51.004Z"
  }
}

The application being moved doesn't count against itself. You can move it to another language on the same sitting, which is the most common move. Every other application the student holds still counts.

What is checked, in order

A move onto a make-up sitting makes the application temporary, exactly as creating one there does (see What a new application contains). A move off a make-up sitting makes it permanent again.

The AI Challenge rule

Students in the AI Challenge category have an image quota, which they use up as they train. Once a student has used any of their quota in an organization, none of their applications whose current exam is in the AI Challenge category can be moved there. What they used can't be carried to another exam, and moving the application would leave no record of it.

• The rule looks at the category the application is moving from. Moving an application into AI Challenge isn't affected.
• It applies whether or not the application has been paid for.
• A student who hasn't used any quota yet can be moved like anyone else.

A paid application can move

Paid applications aren't frozen. Changing the language of an exam that has already been paid for, at the same price, is an ordinary move. What the API refuses is a move that would change what the money bought (check 11). If the price differs, the student has to arrange it on the platform, or you can wait for an equal-price option.

The Change an application tutorial walks through a language swap and each 409.

Delete an application

DELETE /v1/<organizationId>/application/<applicationId> withdraws the student from the exam.

Why a settled application can't be deleted: deleting refunds nothing. The payment would be left pointing at an application that no longer exists, and the money would have bought nothing anyone can find. Canceling a paid sitting is a refund, and refunds happen outside this API.

Deleting a second time answers 404 not_found, Application not found!. The application is already gone, so treat that as success when you retry.

Payment is the only state the delete checks. It doesn't check whether the student has started the exam, or whether the sitting is still ahead, so look at participated and examSubmitted before you delete. If your integration should never delete, ask your operator to leave application/delete off your account's roles.

Read applications

Three lists and one single read. All of them resolve references, so a row is usable on its own:

The student summary is deliberately short: _id, mainId, firstName and lastName. Match on mainId, which is the core id you registered the student with. _id is the organization's own id for them. For the full profile, call GET /v1/student/<mainId>.

On exam-applications/<examId> the exam stays an id because you already named it in the path, and every row would repeat the same document. On a team application, each entry in partners names its co-participant by user, and that user always stays an id. Co-participants can be other accounts' students, and the API only returns details of your own.

curl -s "https://api.main-team.org/v1/<organizationId>/application/student-applications/652f1c9b8e4b2a0012a3c4d5" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Applications fetched successfully.",
  "data": [
    {
      "_id": "6703d4e5f6a7b8c9d0e1f203",
      "exam": {
        "_id": "66f1a2b3c4d5e6f708192a3c",
        "session": "66e0c1d2e3f4a5b6c7d8e9f0",
        "category": "64b7e1f0a1b2c3d4e5f60711",
        "language": "64a1f0b2c9d8e7f60011889a",
        "grades": ["630e01826836e67ec53dc7a6", "630e01826836e67ec53dc7a7"],
        "price": 25
      },
      "user": {
        "_id": "66fa0b1c2d3e4f5a6b7c8d9e",
        "mainId": "652f1c9b8e4b2a0012a3c4d5",
        "firstName": "Ada",
        "lastName": "Lovelace"
      },
      "payment": {
        "_id": "6703d4e5f6a7b8c9d0e1f204",
        "application": "6703d4e5f6a7b8c9d0e1f203",
        "exam": "66f1a2b3c4d5e6f708192a3c",
        "for": "66fa0b1c2d3e4f5a6b7c8d9e",
        "amount": 25,
        "status": "paid",
        "createdAt": "2026-09-15T10:42:07.498Z",
        "updatedAt": "2026-09-15T11:20:13.220Z"
      },
      "participated": false,
      "partners": [],
      "createdAt": "2026-09-15T10:42:07.512Z",
      "updatedAt": "2026-09-16T08:05:51.004Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Inside a resolved exam, the session, category and language are ids. To show their names, use the open exam list or the exam categories. A past exam no longer appears there, but its category still does.

Who appears in the lists

All three lists include applications for closed and past exams. exam-applications/<examId> doesn't check that the exam exists: an unknown id returns an empty list, and it works for past sittings too. An <examId> or <studentId> that isn't 24 hexadecimal characters answers 400 bad_request.

Lists are paginated with page and limit (default 20, at most 100) and have no documented order. To take a complete snapshot, walk every page and remove duplicates by _id. See Pagination.

A single application

The two 404s have different messages, but they mean the same thing to you: this application isn't available to your account. Branch on the status and error.code, never on the message.

The 409s at a glance

None of these changes on a retry. Fix the cause first. The conflict error page and Troubleshooting cover them too.

Related

• Exams and the exam picker
• Register a student and apply
• Change an application
• Sign-in links
• Retries and idempotency