Skip to content
Docs

People & Access

Students

Provision students with a login email and license, map personal emails, suspend and reactivate.

How student accounts work#

Every institution student signs in with a generated login email of the form studentN.<code>@grout.user. One-time codes are delivered to the student's personal email, which is mapped on first login (or ahead of time by you). The personal email is never returned by the API.

Provisioning creates three things atomically: the users row, the institution email record, and a student license (365 days by default, 2 devices).

Create a student#

bash
curl -X POST $API/students -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "full_name": "Asha Rao",
  "student_id": "S-2026-0142",
  "personal_email": "[email protected]",
  "license_days": 365
}'
json
{ "success": true, "data": {
  "id": "u_…", "email": "[email protected]", "login_email": "[email protected]",
  "user_type": "institution_student", "full_name": "Asha Rao", "student_id": "S-2026-0142",
  "status": "pending", "personal_email_mapped": true,
  "license": { "id": "lic_…", "status": "active", "license_type": "student", "expires_at": "2027-09-14T…", "is_lifetime": false }
} }
FieldNotes
full_nameOptional; shown in the apps.
student_idYour SIS identifier; searchable via ?student_id=.
personal_emailOptional. When set, first login goes straight to the OTP screen.
license_days1–3650, default 365.

status is pending until the first successful sign-in, then active.

Bulk create#

POST /students/bulk takes { "students": [ …up to 200… ] } and returns per-item results:

json
{ "created": 198, "failed": 2, "results": [ { "index": 0, "id": "u_…", "login_email": "…" }, { "index": 7, "error": "…" } ] }

List and find#

bash
curl "$API/students?status=active&limit=200&page=1" -H "Authorization: Bearer $KEY"
curl "$API/students?student_id=S-2026-0142" -H "Authorization: Bearer $KEY"
curl "$API/students?group_id=grp_…" -H "Authorization: Bearer $KEY"

GET /students/{id} accepts the internal id or the login email.

Update, suspend, reactivate#

bash
curl -X PATCH $API/students/u_… -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "full_name": "Asha K. Rao", "personal_email": "[email protected]" }'
curl -X POST $API/students/u_…/suspend    -H "Authorization: Bearer $KEY"
curl -X POST $API/students/u_…/reactivate -H "Authorization: Bearer $KEY"

Suspending ends the student's sessions immediately; their license stays and resumes on reactivation.

Related reads#

  • GET /students/{id}/exams — assigned exams with submission and attempt state.
  • GET /students/{id}/guardians — linked guardians. See Guardians.

Events#

student.created, student.email_mapped, student.updated, license.generated. See Event Catalogue.

PreviousAgent-Readable SurfacesNextFaculty