Invite a person by email

POST /api/v1/orgs/{id}/invitations · Operation ID: inviteToOrg

Application use

Use a valid class role and verified-account invitation flow for human accounts. Teachers may invite class roles; co-teachers may invite students only. The response is always a pending invitation (202), whether the address has an account or not. Re-inviting updates the role and restarts the 14-day expiry. This does not create a student-pool login.

Authentication and permission

Bearer credential with orgs:manage. members.manage plus orgs:manage, narrowed to assignable class roles.

Scopes, membership, current role, effective policy and applicable plan checks all apply. A managed student token cannot grant organisation-management authority. A student-pool login JWT is not a public-API bearer credential. See Classroom identity and roles.

Example

Replace placeholders using an authorised disposable test class. Mutation examples change real data when run. Keep tokens on the server; never copy student credentials into diagnostics.

curl --fail-with-body -X POST 'https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/invitations' \
  -H "Authorization: Bearer $HANDWRITE_API_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"email":"teacher@example.com","role":"co-teacher"}'

Parameters

Name	In	Required	Details
`id`	path	Yes	An organisation ID (org_…).
`Idempotency-Key`	header	No	1–255 visible ASCII characters (a UUID per operation). A retry with the same key and identical request within 24 hours replays the first 2xx response with Idempotent-Replayed: true; a different request with the key gets 422 idempotency_mismatch; a retry while the first runs gets 409 idempotency_in_progress.

Request body

application/json (required).

Field	Required	Details
`email`	Yes	{"type":"string","format":"email","maxLength":320}
`role`	Yes	Team roles: owner, admin, billing, manager, developer, member. Class roles: teacher, co-teacher, billing, student.

Responses and recovery

Status	Meaning	Format
202	Always 202, whether or not the address has an account.	application/json
400	invalid_request (the message names the field), validation_failed.	application/json
401	unauthorized: no token, or it's invalid, revoked or expired.	application/json
403	insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).	application/json
404	not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).	application/json
422	limit_reached, idempotency_mismatch, unreadable_file, no_text, empty_document.	application/json
429	rate_limited (burst or daily cap) or quota_exceeded (no characters left).	application/json
500	internal_error.	application/json

The paired API reference holds the shared machine-readable schema. Additional role, policy, seat and plan failures are described in API specification notes. Do not parse 204 or 304 responses as JSON, and do not treat 403 as a transient retry.

README — POST /api/v1/orgs/{id}/invitations

Invite a person by email#

Application use#

Authentication and permission#

Example#

Parameters#

Request body#