Create Invite
Mint a join link or code for a chosen scope, org-scoped to the API key’s org.
Scopes: organization (recruit a tutor/admin by email, or get a reusable org
join link), tutor_student (1-on-1), classroom, group, parent. Supply
email to invite a specific person (creates an invite row; EquateIt emails them
where the platform already does); omit email for a reusable shareable
link/code. Cross-org targets return 404. Honours Idempotency-Key.
Authorizations
Org API key as Token token=ei_live_...
Headers
Body
POST /v1/invites → mint a join link or code for a chosen scope.
Delivery is decided by email + scope (there is no send_email flag): supply
email to invite a specific person — this creates an invite row and ClassQuill
queues them an email where the platform already does (organization always, via
a DB trigger; tutor_student when an email is given). Omit email to get a
reusable shareable link/code. Per-scope required/irrelevant fields are validated
server-side (422). organization_id, tokens, and timestamps are always
server-set; the invite RPCs are never called (they are auth.uid()-gated).
emailed: true in the response means the invite email was QUEUED, not that it
was delivered — queueing happens synchronously in this request, but the actual
send is async (a 1-minute-cadence cron drains the queue via Resend). Treat
join_url as the reliable fallback: surface it to the caller/inviter rather
than assuming the email will arrive.
organization, classroom, group, tutor_student, parent organization only: 'tutor' (default) | 'admin' | 'student'.
Required for the organization email path; optional elsewhere.
Required for scope=tutor_student.
Required for scope=classroom.
Required for scope=group.
Required for scope=parent (the child).
Optional, scope=tutor_student only — echoed back + audited.
Response
Successful Response
A minted invite. token carries the invite token (organization/tutor_student)
or the code (parent / org-join-code scopes). join_url is null for parent (the
code is entered manually).
emailed is true when ClassQuill queued an email for this invite (organization,
or tutor_student with an email) — it does NOT confirm delivery. The actual send
is async: a background job drains the queue and calls Resend, which can still
fail, bounce, or land in spam after this response returns. Callers should
surface join_url as a fallback rather than relying on the email arriving.