Invite
An invite allows users to join an organisation. Invites can be created with an expiry time, domain restrictions, and optional admin approval requirements.
Invite Object
| Field | Type | Description |
|---|---|---|
| organisation | organisation object | the organisation this invite is for |
| code | string | the invite code; only returned when email is empty, otherwise returns an empty string |
| string | the recipient's email address | |
| expires_at | ISO8601 timestamp? | when the invite expires |
| revoked | boolean | whether the invite has been revoked |
| domain | string | the domain this invite is valid for |
| auto_add | boolean | whether the invite automatically adds the user |
| approval | boolean | whether admin approval is required |
| status | invite status | the current status of the invite |
| created_by | user object or snowflake | the user who created the invite, or their ID if the user object is not available |
Invite Status
The status field on the invite object contains the invite status as a string.
| Value | Description |
|---|---|
| pending | The invite is pending |
| accepted | The invite has been accepted |
| rejected | The invite has been rejected |
| revoked | The invite has been revoked |
Get Invite
GET /invites/{invite.code}
Returns the invite object for the given invite code. Only non-expired invites are returned.
Error Responses
| Status Code | Description |
|---|---|
| 404 | Not found (invite does not exist or has expired) |
Update Invite
PATCH /invites/{invite.code}
Updates an invite's properties. Requires the CREATE_INVITE permission for the organisation. When a domain is provided, the invite will not expire and auto-add is only enabled if the domain is a verified organisation domain.
All parameters for this method are optional. Only the fields provided will be updated.
JSON Params
| Field | Type | Description |
|---|---|---|
| expires_at? | ISO8601 timestamp? | when the invite expires (default: unchanged) |
| approval? | boolean? | whether admin approval is required (default: unchanged; forced to true if organisation requires member approval) |
| domain? | string? | the domain this invite is valid for; setting this disables expiry and requires a verified domain for auto-add |
| auto_add? | boolean? | whether the invite automatically adds the user (default: false; only effective if domain is verified) |
Error Responses
| Status Code | Description |
|---|---|
| 404 | Not found (invite does not exist) |
| 403 | Forbidden (user lacks the CREATE_INVITE permission) |
Use Invite
POST /invites/{invite.code}
Uses the invite to join the organisation. If the invite requires admin approval, the membership will be pending until approved. If the invite has a domain restriction, the user must have a verified e-mail address matching that domain. The user must not be banned from the organisation, and the organisation must have available member quota. Returns 200 OK on success, 204 No Content if the user is already a member.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Bad request (invite organisation is invalid) |
| 403 | Forbidden (domain mismatch or user is banned) |
| 404 | Not found (invite does not exist, is revoked, or has expired) |
| 429 | Member quota exhausted for this organisation |
Revoke Invite
DELETE /invites/{invite.code}
Revokes the invite. Requires the REVOKE_INVITE permission for the organisation.
Error Responses
| Status Code | Description |
|---|---|
| 404 | Not found (invite does not exist) |
| 403 | Forbidden (user lacks the REVOKE_INVITE permission) |