Send a group’s finished work for one of your students

POST

/v1/{organizationId}/group-challenge/{challengeId}/group/{groupId}/final-submit

Bearer token
Permissiongroup-challenge/submit
Per organization

Sends a group’s finished work, once every step is submitted, for one of your students who is a member of the group, exactly as the student would in the panel. The group becomes completed. Read the group first: canFinalSubmit says whether this would be accepted now.

The body names the student you act for: { "studentId": "<studentId>" }. The group’s history records the submit as your account (partner) acting for them.

Checks, in order. The first that fails decides the answer, and nothing is written for any of them.

The student is yours (404), and has signed in to this organization once (409).
The challenge exists and is published or closed (404).
The group belongs to the challenge and the student is an active member of it (404).
The work has not been sent already. If it has, the answer is 200 with changed: false and "Group work already submitted.", and nothing changes, so a retry after a timeout is safe.
The challenge is published (409, challenge_closed) and now is between windowStart and windowEnd (409, window_closed).
The teacher has confirmed the group (409, payment_pending or group_not_confirmed).
Every step is submitted (409, steps_incomplete, with stepsSubmitted and stepCount in details).

Every 409 carries error.details.reason; branch on it, not on the message.

Side effects. The group becomes completed, and an entry is added to its history. Every member of the group and its teacher receive an e-mail saying the group has sent its work.

Busy. As for submitGroupChallengeStep: 503 with Retry-After: 1 and details.reason: busy when someone is changing the group at that moment; nothing was written, so send it again.

Parameters

Path parameters

Name	Type	Description
`organizationId`required	stringpattern `^[0-9a-f]{24}$`	The organization’s `_id`: 24 hexadecimal digits, as `listOrganizations` (`GET /v1/organization`) lists it. Example `64b7f0c2a1d3e4f5a6b7c8d9`
`challengeId`required	string	The group challenge’s `_id`, from `listGroupChallenges`.
`groupId`required	string	The group’s `_id`, from `listGroupChallengeGroups` or a student’s `group`.

Request body

application/jsonrequired

studentIdstringrequired
The student the submit is made for: their _id, as registerStudent returned it. They must be one of your students and an active member of the group; the group’s log records the submit as your account acting for them.
example6650a1b2c3d4e5f6a7b8c9d0

Responses

200 OK

Success: message is "Group work submitted.".

Or message is "Group work already submitted.": The work had already been sent, by anyone. changed is false and nothing changed.

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleGroup work submitted.
dataobject · GroupChallengeWorkSubmitResponserequired
A group’s work sent for one of your students.
4 fields of data
- groupIdstringrequired
  The group’s id.
  example6650a1b2c3d4e5f6a7b8c9ed
- groupStatusstringrequired
  The group’s state now: completed.
  one ofawaiting_paymentdraftfinalizedcompleted
  examplecompleted
- finalSubmittedAtstringnullablerequired
  When the work was sent: now, or the first time on a repeat.
  formatdate-timeexample2026-10-20T16:02:11.000Z
- changedbooleanrequired
  true when this request sent the work; false when it had already been sent, and nothing changed.
  exampletrue

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

{
  "data": {
    "changed": true,
    "finalSubmittedAt": "2026-10-20T16:02:11.000Z",
    "groupId": "6650a1b2c3d4e5f6a7b8c9ed",
    "groupStatus": "completed"
  },
  "message": "Group work submitted.",
  "success": true
}

400 Bad request

bad_request: The body is not valid JSON, breaks a field’s rules, or has a field this operation does not accept ("property <name> should not exist").
bad_request: challengeId is not 24 hexadecimal digits.
bad_request: groupId is not 24 hexadecimal digits.

When

bad_request
The body is not valid JSON, breaks a field’s rules, or has a field this operation does not accept ("property <name> should not exist").
bad_request
challengeId is not 24 hexadecimal digits.
bad_request
groupId is not 24 hexadecimal digits.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "The request was malformed or contained invalid parameters.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

401 Unauthorized

unauthorized: The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

When

unauthorized
The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

Example

{
  "error": {
    "code": "unauthorized",
    "documentation_url": "https://hub.main-team.org/api/errors#unauthorized",
    "message": "Authentication is required or the provided credentials are invalid.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

403 Forbidden

forbidden: The token is valid, but no role on your account allows group-challenge/submit on the organization in the path, or a role denies it.

When

forbidden
The token is valid, but no role on your account allows group-challenge/submit on the organization in the path, or a role denies it.

Example

{
  "error": {
    "code": "forbidden",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "message": "Insufficient role permissions",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

404 Not found

not_found: organizationId is not the _id of an organization.
not_found: Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found: No student of yours has this id: it matches nobody, or another account registered the student.
not_found: No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.
not_found: No group of this challenge has this id with the student as an active member: a missing group, a deleted one and one the student is not in get the same answer.

When

not_found
organizationId is not the _id of an organization.
not_found
Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found
No student of yours has this id: it matches nobody, or another account registered the student.
not_found
No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.
not_found
No group of this challenge has this id with the student as an active member: a missing group, a deleted one and one the student is not in get the same answer.

Example

{
  "error": {
    "code": "not_found",
    "documentation_url": "https://hub.main-team.org/api/errors#not_found",
    "message": "Organization not found!",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

409 Conflict

conflict: The student has never signed in to this organization, so it holds no record of them yet. Send them a sign-in link (createSigninLink), and try again once they have used it.
conflict: The organizers have closed the challenge (status: closed).
conflict: Now is before windowStart or after windowEnd. details carries both.
conflict: The teacher is still preparing the group (status: awaiting_payment).
conflict: The teacher has not confirmed the group yet (status: draft), so it has no steps.
conflict: A step is not submitted yet. details counts them.

When

conflict
The student has never signed in to this organization, so it holds no record of them yet. Send them a sign-in link (createSigninLink), and try again once they have used it.
conflict
The organizers have closed the challenge (status: closed).
conflict
Now is before windowStart or after windowEnd. details carries both.
conflict
The teacher is still preparing the group (status: awaiting_payment).
conflict
The teacher has not confirmed the group yet (status: draft), so it has no steps.
conflict
A step is not submitted yet. details counts them.

Example

{
  "error": {
    "code": "conflict",
    "documentation_url": "https://hub.main-team.org/api/errors#conflict",
    "message": "The request conflicts with the current state of the resource.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

413 Payload too large

payload_too_large: The body is larger than 100 kB.

When

payload_too_large
The body is larger than 100 kB.

Example

{
  "error": {
    "code": "payload_too_large",
    "documentation_url": "https://hub.main-team.org/api/errors#payload_too_large",
    "message": "request entity too large",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

415 Unsupported media type

unsupported_media_type: The body declares a charset that is not a UTF one (send UTF-8), or a Content-Encoding other than gzip, deflate or br.

When

unsupported_media_type
The body declares a charset that is not a UTF one (send UTF-8), or a Content-Encoding other than gzip, deflate or br.

Example

{
  "error": {
    "code": "unsupported_media_type",
    "documentation_url": "https://hub.main-team.org/api/errors#unsupported_media_type",
    "message": "unsupported charset \"ISO-8859-1\"",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

429 Too many requests

too_many_requests: Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

When

too_many_requests
Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

Headers

Retry-After integer: Seconds to wait before sending again; a request sent sooner is refused too.

Example

{
  "error": {
    "code": "too_many_requests",
    "documentation_url": "https://hub.main-team.org/api/errors#too_many_requests",
    "message": "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

500 Internal error

internal_error: Something failed on our side. Retry later, and quote request_id if it goes on.

When

internal_error
Something failed on our side. Retry later, and quote request_id if it goes on.

Example

{
  "error": {
    "code": "internal_error",
    "documentation_url": "https://hub.main-team.org/api/errors#internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

503 Service unavailable

service_unavailable: Someone else — a member in the panel or the app, or another request of yours — is changing the group at this moment. Nothing was written. Wait the second in Retry-After and send the same request again.

When

service_unavailable
Someone else — a member in the panel or the app, or another request of yours — is changing the group at this moment. Nothing was written. Wait the second in Retry-After and send the same request again.

Headers

Retry-After integer: Seconds to wait before sending again; a request sent sooner is refused too.

Example

{
  "error": {
    "code": "service_unavailable",
    "details": {
      "reason": "busy"
    },
    "documentation_url": "https://hub.main-team.org/api/errors#service_unavailable",
    "message": "The group is being changed by someone else. Try again in a second.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

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/<organizationId>/group-challenge/<challengeId>/group/<groupId>/final-submit' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "studentId": "6650a1b2c3d4e5f6a7b8c9d0"
}
JSON

const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/final-submit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "studentId": "6650a1b2c3d4e5f6a7b8c9d0"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data);

<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/final-submit');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'studentId' => '6650a1b2c3d4e5f6a7b8c9d0',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body['data']);