Invite a person by email

POST

/api/v1/orgs/{id}/invitations

Classroom integration: 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.

Required standing: members.manage plus orgs:manage, narrowed to assignable class roles.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://handwrites.io/oauth/authorize

Token URL: https://handwrites.io/api/oauth/token

Refresh URL: https://handwrites.io/api/oauth/token

Scopes:

orgs:manage-Create, rename and delete teams and classrooms, manage members and invitations, join and leave

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢202

application/json

Always 202, whether or not the address has an account.

Headers

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠422Unprocessable

🟠429TooManyRequests

🔴500ServerError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/orgs//invitations' \
--header 'Idempotency-Key;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "user@example.com",
    "role": "owner"
}'

Response Example

202 - Example 1

{
    "invitation": {
        "id": "string",
        "email": "string",
        "role": "owner",
        "status": "pending",
        "invitedBy": "user:3f2b…",
        "createdAt": "2019-08-24T14:15:22.123Z",
        "expiresAt": "2019-08-24T14:15:22.123Z"
    }
}

Modified at 2026-10-26 13:12:44

List pending class invitations

Cancel a pending invitation