Fetch one of your students’ eligibility and group for a group challenge

GET

/v1/{organizationId}/group-challenge/{challengeId}/student/{studentId}

Bearer token
Permissiongroup-challenge/read
Per organization

Where one of your students stands in the challenge: the same answer as one row of listGroupChallengeStudents, for a student activated for this organization or not.

Your students are the ones your account registered: anyone else’s answers 404, exactly as an unknown id does. A student who has never signed in to this organization answers 409.

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`.
`studentId`required	string	The student’s `_id`, as `registerStudent` returned it.

Responses

200 OK

Success: message is "Student fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleStudent fetched successfully.
dataobject · GroupChallengeStudentResponserequired
One of your students, and where they stand in a group challenge.
10 fields of data
- studentIdstringrequired
  The student’s _id, as registerStudent returned it.
  example6650a1b2c3d4e5f6a7b8c9d0
- firstNamestringrequired
  Their first name, as the organization holds it.
  exampleAda
- lastNamestringrequired
  Their last name.
  exampleLovelace
- gradeobject · GroupChallengeStudentGradeResponsenullablerequired
  Their grade in the organization, or null when none is set.
  2 fields of grade
  _idstringrequired
  The grade’s id.
  example6650a1b2c3d4e5f6a7b8c9d4
  nameobjectnullablerequired
  Its name.
  example10
- eligiblebooleanrequired
  Whether their grade is in one of the challenge’s grade groups.
  exampletrue
- gradeGroupobject · GroupChallengeGradeGroupRefResponsenullablerequired
  The grade group their grade belongs to, or null.
  2 fields of gradeGroup
  _idstringrequired
  The grade group’s id within the challenge.
  example6650a1b2c3d4e5f6a7b8c9ec
  labelstringrequired
  Its name.
  exampleGroup 7-8-9
- teacherLinkedbooleanrequired
  Whether a teacher is linked to them in this organization. Only a teacher can put a student in a group; link one with linkStudentSupervisor.
  exampletrue
- statestringrequired
  not_eligible: their grade is in no grade group. not_in_group: eligible, in no group yet. group_pending: in a group the teacher has not confirmed. group_active: in a confirmed group, working through the steps. group_completed: their group has sent its work. A group wins over the grade: a student in a group shows it even if their grade changed since. New values may be added.
  one ofnot_eligiblenot_in_groupgroup_pendinggroup_activegroup_completed
  examplegroup_active
- groupobject · GroupChallengeStudentGroupResponsenullablerequired
  The group they are an active member of, or null.
  3 fields of group
  _idstringrequired
  The group’s id: the groupId of the group operations.
  example6650a1b2c3d4e5f6a7b8c9ed
  displayNamestringrequired
  The group’s name, or "Group" and its short code when it has none.
  exampleGroup 7KQ2MX
  statusstringrequired
  awaiting_payment and draft while the teacher prepares it; finalized once they have confirmed it and its steps are open; completed once its work has been sent. New values may be added.
  one ofawaiting_paymentdraftfinalizedcompleted
  examplefinalized
- panelPathstringrequired
  Where the challenge’s page is on the organization’s panel. Send it as redirect to createSigninLink to take the student straight there: {userId} is filled in for you.
  example/stadia/{userId}/group-challenges/6650a1b2c3d4e5f6a7b8c9eb

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 fetched successfully.",
  "data": {
    "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "grade": {
      "_id": "6650a1b2c3d4e5f6a7b8c9d4",
      "name": "10"
    },
    "eligible": true,
    "gradeGroup": {
      "_id": "6650a1b2c3d4e5f6a7b8c9ec",
      "label": "Group 7-8-9"
    },
    "teacherLinked": true,
    "state": "group_active",
    "group": {
      "_id": "6650a1b2c3d4e5f6a7b8c9ed",
      "displayName": "Group 7KQ2MX",
      "status": "finalized"
    },
    "panelPath": "/stadia/{userId}/group-challenges/6650a1b2c3d4e5f6a7b8c9eb"
  }
}

400 Bad request

bad_request: challengeId is not 24 hexadecimal digits.
bad_request: studentId is not 24 hexadecimal digits.

When

bad_request
challengeId is not 24 hexadecimal digits.
bad_request
studentId is not 24 hexadecimal digits.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "Invalid value for 'challengeId': expected ObjectId.",
    "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/read 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/read 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.

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.

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.

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.

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.

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.

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/student/<studentId>' \
  -H "Authorization: Bearer $TOKEN"

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>/student/<studentId>', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
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>/student/<studentId>');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    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']);