Onboard a student into one or more learning apps
For most apps, forwards the request to the onboarding orchestrator, which validates the student and each app, then enqueues each app to SQS (3× retry + DLQ). Incept, Mentava, and Happy Numbers are synchronous, in-repo exceptions and must each be requested alone. This endpoint validates the request structure; the orchestrator validates the values (valid app names, grade ranges, mathacademy course matching).
Payload
{
"email": "student@alpha.school", // required
"apps": [ // required, non-empty
{ "app": "<name>", "args": { "grade": 5 } }
]
}
- Each
appsentry is an object:app(routing key) + optionalargsbag. args.gradeis required for every app exceptgoogle.- Grade ranges below are generally enforced downstream. The synchronous in-repo exceptions enforce their own restrictions here before any provider write.
Supported apps
Expand an app to see its args and a sample entry.
anton — grade: any integer
{ "app": "anton", "args": { "grade": 5 } }
membean — grade: 4–12
Class is assigned from the student’s campus + level (not all campuses are configured).
{ "app": "membean", "args": { "grade": 7 } }
egumpp — grade: any integer
{ "app": "egumpp", "args": { "grade": 6 } }
clearfluency — grade: 1–2
{ "app": "clearfluency", "args": { "grade": 1 } }
freckle — grade: -1–12 (PreK–12)
Optional renaissance_class_id overrides the class assignment.
{ "app": "freckle", "args": { "grade": 3, "renaissance_class_id": "abc-123" } }
lalilo — grade: -1–12 (PreK–12)
Optional renaissance_class_id overrides the class assignment.
{ "app": "lalilo", "args": { "grade": 1 } }
mobymax — grade: 0–8 (K–8)
Optional: course (e.g. "reading"), account (string[]), subject.
{ "app": "mobymax", "args": { "grade": 4, "course": "reading", "subject": "math" } }
mathacademy — grade: 4–12 (course_name optional)
Each grade resolves to a default course (grades 9–12 default to the traditional track: Algebra I, Geometry, Algebra II, Precalculus). course_name is an optional override to select a different Math Academy catalog course (e.g. an Integrated Math (Honors) or SAT course).
{ "app": "mathacademy", "args": { "grade": 10 } }
incept - grades: 3-4 (Math). Runs the full Incept enrollment flow (same as the progression engine grade-3/4 Math base enrollment): rosters the student in Incept and provisions their individualized TimeBack Math base course.
Unlike the other apps, incept is validated and executed by THIS service (not the async orchestrator) and runs synchronously. It must be the only app in the request. Responses: 202 enrolled (or already enrolled), 207 enrollment failed (e.g. Incept/TimeBack desync), 404 no active student for the email, 409 the email matches multiple active users, 503 Incept not configured in this env, or Incept/TimeBack temporarily unavailable (retry).
{ "app": "incept", "args": { "grade": 4 } }
mentava — PK by default; non-PK requires Academics Reading approval. Runs synchronously through Bridge API.
class_id optionally overrides the configured current Mentava class UUID. The service always uses the approved starting level (letter_sounds, shown in Mentava as Letter Sounds only / no blending), sends the student’s TimeBack OneRoster sourcedId to Mentava, enrolls the Mentava Basics TimeBack course, and stores the standard learning-app credentials. Set approval_confirmed: true for non-PK students and whenever the student’s authoritative TimeBack grade is unavailable. The no-approval PK form is accepted only when TimeBack itself identifies the student as PK. The Bridge consumer used by this service must have mentava:read and mentava:roster:students:create (or mentava:roster:write) scopes. Device assignment/app installation remains an operational prerequisite outside this API.
{ "app": "mentava", "args": { "grade": -1 } }
{ "app": "mentava", "args": { "grade": -1, "approval_confirmed": true } }
{ "app": "mentava", "args": { "grade": 1, "class_id": "00000000-0000-4000-8000-000000000000", "approval_confirmed": true } }
edia — grade: 3–8
{ "app": "edia", "args": { "grade": 5 } }
vocabloco — grade: any integer
Word lists are auto-assigned by grade: G3 → Vocabulary + Spelling, G4 → Vocabulary + Spelling, G5 → Word List, G6+ → account only (no word lists).
{ "app": "vocabloco", "args": { "grade": 4 } }
zearn — grade: 0–3 (K–3)
{ "app": "zearn", "args": { "grade": 2 } }
happynumbers — Pre-K only
Resolves the active student roster record, provisions the student into Alpha, Alpha 2, and so on, rolling to a newly created class when the current class reaches 95 students, and stores the Happy Numbers identity mapping and TimeBack display-name/PIN credentials. It runs synchronously in this service through Bridge and must be the only app in the request. This is provider-roster onboarding only: it does not create or replace a TimeBack course enrollment. Normal progression assigns the TimeBack course separately. The TimeBack service identity must have Bridge happynumbers:read and happynumbers:roster:write scopes.
{ "app": "happynumbers", "args": { "grade": -1 } }
google — grade: optional
args may be omitted entirely. Optional google_password (system default if omitted); grade is only used for OU assignment.
{ "app": "google" }
{ "app": "google", "args": { "google_password": "CustomPass1!" } }
Responses
- 200 — Mentava course onboarding or Happy Numbers provider rostering completed synchronously; check
results[].status. - 202 — every app was queued.
- 207 — partial success; check each entry’s
queued/errorfield. - 400 — malformed body (here) or invalid app name / app-specific value validation (orchestrator).
- 404 — student not found for the given email.
Served by the onboard-student Lambda.
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
Student email — must exist in Timeback.
"student@alpha.school"
Apps to onboard the student into. Each entry is an object with app and an optional args bag. args.grade is required for every app except google. Structure is validated here; app/grade/course values are validated by the orchestrator.
1Request-level default: (re)write Timeback credentials even for existing accounts (per-app args.forceTimebackCredentials overrides this).
Response
Mentava enrollment or Happy Numbers provider rostering completed synchronously