Skip to main content
POST
cURL
Invites a single person to your organization. The same call also resends an existing invitation: posting an address that already has a live invitation resends it rather than creating a second one. Inviting someone provisions them immediately as a pending member of the organization. With workspaces, the same call also places them in workspaces, each with a role, so you can add them to permission groups and grant them access in those workspaces before they accept. See Pending users and pre-granted invitations below.

Request body

Organization owners and admins are admins of every workspace. When organization_role is owner or admin, omit workspaces, or list every active workspace of the organization with the admin role. Any other list is rejected with 400 (workspaces_inconsistent_with_role).
The invitation belongs to the organization even when it names workspaces: it is listed and revoked through the organization’s invitations.

Response

Returns the Organization invitation object. The status code tells you which of the two things happened:
  • 201 Created: a new invitation was created.
  • 200 OK: an existing invitation was resent.
The response includes user, the id of the pending user the invitation created. You can use it immediately as a grant or group target.

Example

Resending and role changes

Sending the same address again is safe and is how you chase someone who has not accepted. Nobody is duplicated: the existing invitation is resent with a fresh expiry, and the invitee’s existing groups and grants are untouched. If organization_role differs from the outstanding invitation, the resend is a role change: it moves the person on both the invitation and their pending membership.
Moving an existing admin or owner invitee to another role requires an owner. This is the same ceiling that applies to changing the role of an accepted member.

Pending users and pre-granted invitations

Because an invitation provisions the person right away, they exist as a pending member the moment the call succeeds:
  • Grant access before acceptance. In every workspace the invitee was placed in, a pending member is a normal target for every permission-assign endpoint, and can be added to a permission group with no separate flow.
  • Pending is not inactive. In the member list a pending member carries its own status; it is not the same as a deactivated user.
  • They cannot log in until they accept. The invitation token is the only proof that the person controls the address.
  • Revoking is destructive. Revoking removes the invitee’s workspaces, groups, and grants, not just the email.
The invitation email expires after 7 days; the pre-granted access does not. An admin resends and nothing has to be re-granted.

Authentication

This endpoint requires an API key in the x-api-key header. Only an organization owner or admin can invite, and nobody can invite somebody to an organization role above their own. For an API key, that ceiling is read from the organization role of the user who created the key. An API key belongs to one workspace, so through a key workspaces can only name the key’s own workspace. Any other workspace is rejected with 400.

Errors

Authorizations

x-api-key
string
header
required

API Key authentication. Format: 'x-api-key: api_key'

Body

An invitation as organization/invitations/ answers it: invitations/'s fields, plus the user it created (pending in the organization until they accept) and the workspace it was issued in (a workspace invitation, specs/workspaces.md §4.9a; null for an organization one). created_by, user and workspace are ids, each expandable. organization_role is the role in the organization the invitation grants, invitations/'s role.

email
string<email>
required
Maximum string length: 254
first_name
string
Maximum string length: 150
last_name
string
Maximum string length: 150
organization_role
enum<string>
default:member

The invitee's role in the organization. Defaults to member. You cannot invite somebody to a role above your own, and on the Free plan only owners can be invited.

  • owner - Owner
  • admin - Admin
  • member - Member
Available options:
owner,
admin,
member
functional_area
  • data_analytics - Data & Analytics
  • sales - Sales
  • customer_support - Customer Support
  • operations - Operations
  • marketing - Marketing
  • finance - Finance
  • product_development - Product Development
  • growth - Growth
  • executive_leadership - Executive Leadership
  • other - Other
Available options:
data_analytics,
sales,
customer_support,
operations,
marketing,
finance,
product_development,
growth,
executive_leadership,
other
other_functional_area
string | null
Maximum string length: 128
workspaces
object[]
write-only

Workspaces to place the invitee in right away, each with their role there; the invitation still belongs to the organization. An owner or admin is an admin of every workspace: omit workspaces for them, or list every workspace as admin. No workspace twice.

Response

201 - application/json

An invitation as organization/invitations/ answers it: invitations/'s fields, plus the user it created (pending in the organization until they accept) and the workspace it was issued in (a workspace invitation, specs/workspaces.md §4.9a; null for an organization one). created_by, user and workspace are ids, each expandable. organization_role is the role in the organization the invitation grants, invitations/'s role.

id
string<uuid>
required
read-only
email
string<email>
required
Maximum string length: 254
sent_at
string<date-time>
required
read-only
expires_at
string<date-time>
required
read-only
accepted_at
string<date-time> | null
required
read-only
revoked_at
string<date-time> | null
required
read-only
created_at
string<date-time>
required
read-only
created_by
integer
required
read-only

The user who sent the invitation. (Expandable)

user
integer | null
required
read-only

The user the invitation created, pending in the organization until they accept. (Expandable)

workspace
string<uuid> | null
required
read-only

The workspace the invitation was issued in; null for an organization invitation. (Expandable)

first_name
string
Maximum string length: 150
last_name
string
Maximum string length: 150
organization_role
enum<string>
default:member

The invitee's role in the organization. Defaults to member. You cannot invite somebody to a role above your own, and on the Free plan only owners can be invited.

  • owner - Owner
  • admin - Admin
  • member - Member
Available options:
owner,
admin,
member
functional_area
  • data_analytics - Data & Analytics
  • sales - Sales
  • customer_support - Customer Support
  • operations - Operations
  • marketing - Marketing
  • finance - Finance
  • product_development - Product Development
  • growth - Growth
  • executive_leadership - Executive Leadership
  • other - Other
Available options:
data_analytics,
sales,
customer_support,
operations,
marketing,
finance,
product_development,
growth,
executive_leadership,
other
other_functional_area
string | null
Maximum string length: 128