Organization Invitations

Invite users to an organization.

Create and send an organization invitation

Creates a new organization invitation and sends an email to the provided email_address with a link to accept the invitation and join the organization. You can specify the role for the invited organization member.

New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee.

The request body supports passing an optional redirect_url parameter. When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided. Use this parameter to implement a custom invitation acceptance flow.

You must specify the ID of the user that will send the invitation with the inviter_user_id parameter. That user must be a member with administrator privileges in the organization. Only "admin" members can create organization invitations.

You can optionally provide public and private metadata for the organization invitation. The public metadata are visible by both the Frontend and the Backend whereas the private ones only by the Backend. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The ID of the organization for which to send the invitation

Request Body schema: application/json
required
email_address
required
string

The email address of the new member that is going to be invited to the organization

inviter_user_id
required
string

The ID of the user that invites the new member to the organization. Must be an administrator in the organization.

role
required
string

The role of the new member in the organization

public_metadata
object

Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.

private_metadata
object

Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.

redirect_url
string

Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.

Responses
200

An organization invitation

400

Request was not successful

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

post/organizations/{organization_id}/invitations
Request samples
application/json
{
  • "email_address": "string",
  • "inviter_user_id": "string",
  • "role": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "redirect_url": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_invitation",
  • "email_address": "string",
  • "role": "string",
  • "organization_id": "string",
  • "status": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Get a list of organization invitations

This request returns the list of organization invitations. Results can be paginated using the optional limit and offset query parameters. You can filter them by providing the 'status' query parameter, that accepts multiple values. The organization invitations are ordered by descending creation date. Most recent invitations will be returned first. Any invitations created as a result of an Organization Domain are not included in the results.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset. Must be an integer greater than zero and less than 500. By default, if not supplied, a limit of 10 is used.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

status
string

Filter organization invitations based on their status

Enum: "pending" "accepted" "revoked"
Responses
200

A list of organization invitations

400

Request was not successful

404

Resource not found

get/organizations/{organization_id}/invitations
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Bulk create and send organization invitations

Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization. You can specify a different role for each invited organization member. New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee. The request body supports passing an optional redirect_url parameter for each invitation. When the invited user clicks the link to accept the invitation, they will be redirected to the provided URL. Use this parameter to implement a custom invitation acceptance flow. You must specify the ID of the user that will send the invitation with the inviter_user_id parameter. Each invitation can have a different inviter user. Inviter users must be members with administrator privileges in the organization. Only "admin" members can create organization invitations. You can optionally provide public and private metadata for each organization invitation. The public metadata are visible by both the Frontend and the Backend, whereas the private metadata are only visible by the Backend. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

Request Body schema: application/json
required
Array
email_address
required
string

The email address of the new member that is going to be invited to the organization

inviter_user_id
required
string

The ID of the user that invites the new member to the organization. Must be an administrator in the organization.

role
required
string

The role of the new member in the organization.

public_metadata
object

Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.

private_metadata
object

Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.

redirect_url
string

Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.

Responses
200

A list of organization invitations

400

Request was not successful

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

post/organizations/{organization_id}/invitations/bulk
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Get a list of pending organization invitationsDeprecated

This request returns the list of organization invitations with "pending" status. These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet. Results can be paginated using the optional limit and offset query parameters. The organization invitations are ordered by descending creation date. Most recent invitations will be returned first. Any invitations created as a result of an Organization Domain are not included in the results.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset. Must be an integer greater than zero and less than 500. By default, if not supplied, a limit of 10 is used.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

Responses
200

A list of organization invitations

400

Request was not successful

404

Resource not found

get/organizations/{organization_id}/invitations/pending
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Retrieve an organization invitation by ID

Use this request to get an existing organization invitation by ID.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

invitation_id
required
string

The organization invitation ID.

Responses
200

An organization invitation

400

Request was not successful

403

Authorization invalid

404

Resource not found

get/organizations/{organization_id}/invitations/{invitation_id}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_invitation",
  • "email_address": "string",
  • "role": "string",
  • "organization_id": "string",
  • "status": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Revoke a pending organization invitation

Use this request to revoke a previously issued organization invitation. Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation. Only organization invitations with "pending" status can be revoked. The request needs the requesting_user_id parameter to specify the user which revokes the invitation. Only users with "admin" role can revoke invitations.

SecuritybearerAuth
Request
path Parameters
organization_id
required
string

The organization ID.

invitation_id
required
string

The organization invitation ID.

Request Body schema: application/json
required
requesting_user_id
required
string

The ID of the user that revokes the invitation. Must be an administrator in the organization.

Responses
200

An organization invitation

400

Request was not successful

403

Authorization invalid

404

Resource not found

post/organizations/{organization_id}/invitations/{invitation_id}/revoke
Request samples
application/json
{
  • "requesting_user_id": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "object": "organization_invitation",
  • "email_address": "string",
  • "role": "string",
  • "organization_id": "string",
  • "status": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}