Sign in

v1

latestOpenAPI 3.1.02026-07-2295105298.6 KB
Team Management

Create Invite

Invites a user to your organization, a specific website, or a group. Use invite_method: "direct" to add the user immediately without sending any email — if the email has no existing account, a new user account is created automatically. Use invite_method: "email" to create a pending invite and send an invitation email that the recipient must accept. Group invites require a global API key.

post/api/v1/invites

Request body

type'organization' | 'website' | 'group' required

The type of invite. 'organization' grants org-wide access, 'website' grants access to a single website, 'group' grants access to all websites in a group. Group invites require a global API key.

invite_method'direct' | 'email' required

How to invite the user. 'direct' adds the user to the resource immediately without sending any email — if no account exists for the email, a new user account is created automatically (with emailVerified=false) and the membership is added. 'email' creates a pending invite record and sends an invitation email via Postmark; the user must accept the invite to gain access.

emailstring email required

Email address of the user to invite

role'admin' | 'viewer'

The role to assign to the invited user. Mutually exclusive with role_id.

role_idstring

Assign any role by ID — a system role or one of your organization's custom roles (see GET /api/v1/roles). Mutually exclusive with role. Returns 404 if the role does not exist or belongs to another organization. Defaults to Viewer when neither role nor role_id is given. System role IDs are GUID-shaped sentinels (e.g. 00000000-0000-0000-0000-000000000001), not RFC 4122 UUIDs.

website_idstring uuid

Required when type is 'website'. The ID of the website to grant access to

group_idstring uuid

Required when type is 'group'. The ID of the group to grant access to. Requires a global API key.

first_namestring

Optional first name of the invited user. Used when creating a new user account for 'direct' invites or populating the invite record for 'email' invites.

last_namestring

Optional last name of the invited user. Used when creating a new user account for 'direct' invites or populating the invite record for 'email' invites.

Example request

{
  "type": "organization",
  "invite_method": "email",
  "email": "user@example.com",
  "role": "viewer",
  "role_id": "789e0123-e89b-12d3-a456-426614174000",
  "website_id": "123e4567-e89b-12d3-a456-426614174000",
  "group_id": "456e7890-e89b-12d3-a456-426614174000",
  "first_name": "John",
  "last_name": "Doe"
}

Response

User added or invitation sent successfully

successboolean required

Whether the operation was successful

invite_idstring uuid

The ID of the created invite (only present for email invites)

user_idstring uuid

The ID of the user the invite targets. Present only for direct invites (the user is looked up or created immediately). Never returned for email-method invites to prevent cross-tenant account-existence enumeration.

messagestring required

A message describing the result

Example response

{
  "success": true,
  "invite_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "abc12345-e89b-12d3-a456-426614174000",
  "message": "Invitation sent"
}