Skip to main content
POST
Create Invite

Authorizations

Authorization
string
header
required

Org API key as Token token=ei_live_...

Headers

Idempotency-Key
string | null

Body

application/json

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.

scope
enum<string>
required
Available options:
organization,
classroom,
group,
tutor_student,
parent
role
string | null

organization only: 'tutor' (default) | 'admin' | 'student'.

email
string | null

Required for the organization email path; optional elsewhere.

tutor_id
string | null

Required for scope=tutor_student.

classroom_id
string | null

Required for scope=classroom.

group_id
string | null

Required for scope=group.

student_id
string | null

Required for scope=parent (the child).

subject_id
string | null

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.

scope
string
required
id
string | null
role
string | null
target_id
string | null
email
string | null
token
string | null
join_url
string | null
expires_at
string | null
subject_id
string | null
emailed
boolean
default:false
created_at
string | null