Invite somebody

POST

/orgs/{org}/invitations

curl --request POST \
  --url https://api.sloose.com/orgs/org_9f3c/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "role": "operator" }'

• Production

Sends an invitation to an email address with a role, valid for seven days. The person accepts it in the account app after signing in with that address — by Zoho or by magic link — and joins the organisation at that role.

You cannot grant a role above your own, or invite an address that already has an open invitation. Somebody who is already a member is not invited; change their role instead.

Authorizations

• sessionAuth

Parameters

Path Parameters

org

required

The organisation id the session was issued for. A token for one organisation can never read another.

string

Example

org_9f3c

The organisation id the session was issued for. A token for one organisation can never read another.

Request Body^required

Media typeapplication/json

object

email

required

The address to invite. The invitation is for this address only.

string format: email

role

string

default: operator

Allowed values: operator builder admin

Responses

201

Sent.

Media typeapplication/json

object

invitation

required

object

id

required

string

email

required

string

role

required

string

Allowed values: operator builder admin

status

required

string

Allowed values: pending accepted revoked expired

expiresAt

required

string

invitedByUserId

required

string

invitedByEmail

required

string

acceptedAt

required

string | null

revokedAt

required

string | null

createdAt

required

string

Example

{
  "invitation": {
    "role": "operator",
    "status": "pending"
  }
}

400

The request — its body or its query — did not match the schema. issues carries the Zod issue list.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

No bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

The bearer’s role is too low, it was issued for a different organisation, or the session is a staff member’s view of the organisation — a read-only one as on any write (code: IMPERSONATION_READ_ONLY), and a write-capable one too (code: IMPERSONATION_REFUSED), since an invitation would let somebody in after the view has ended, in the member’s name. Like every route behind a session: a session signed in but in no organisation is refused code: NO_ORG, a banned person code: BANNED, and a closed organisation code: ORG_CLOSED.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

409

The address already has an open invitation (code: ALREADY_INVITED) or is already a member (code: ALREADY_MEMBER); or the role is above yours (code: OUTRANKED).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

502

The invitation could not be emailed (code: INVITATION_NOT_SENT), so none was made: its link is in the message and nowhere else. Try again later.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

503

The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed value: MAINTENANCE

Example

{
  "code": "MAINTENANCE"
}

Headers

Retry-After

integer

Seconds until asking again is worth it (300 while the switch is on).