Skip to content
OTA-Pulse Docs

Invite Member

POST
/api/organizations/{organization_id}/invite
 
curl --request POST \
  --url https://example.com/api/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/invite \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "role": "admin" }'

Invite a person (with or without an account) to join by email.

Sends a single-use link ({APP_BASE_URL}/accept-invite?token=..., valid ORGANIZATION_INVITE_EXPIRE_DAYS, default 7) through the same SES path as verify-email. The raw token is never returned to the inviter — receiving it is what proves the invitee owns the mailbox. Re-inviting an address with a live invitation rotates its token + expiry (a “resend”).

Only ‘member’ or ‘viewer’ may be granted by invitation; promote afterwards via PATCH …/members/{id}. On a server with LOGIN_ALLOWLIST_ENABLED the address must already be admitted by LOGIN_ALLOWED_EMAILS / LOGIN_ALLOWED_EMAIL_DOMAINS, otherwise the invitee could never sign in.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
organization_id
required
Organization Id
string format: uuid

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media type application/json
OrganizationInvitationCreate

POST /organizations/{id}/invite — same shape the console’s organizationsApi.inviteUser() has always sent. Only member/viewer are accepted (enforced in the handler with a readable 422).

object
email
required
Email
string format: email
role
UserRole

User roles

string
default: member
Allowed values: admin owner member viewer

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Successful Response

Media type application/json
OrganizationInvitationResponse

A pending (or just-created) invitation. Never carries the token.

object
created_at
required
Created At
string format: date-time
email
required
Email
string
email_sent
Any of:
boolean
expired
Expired
boolean
expires_at
required
Expires At
string format: date-time
id
required
Id
string format: uuid
invited_by_email
Any of:
string
organization_id
required
Organization Id
string format: uuid
role
required
UserRole

User roles

string
Allowed values: admin owner member viewer
Example 
{
  "expired": false,
  "role": "admin"
}

422

Section titled “ 422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated 
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}