Clerk API (unofficial showcase)
POST/organizations/{organization_id}/invitations

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 can 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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 8 body fields
organization_idstringrequired
The ID of the organization for which to send the invitation
email_addressstringrequired
The email address of the new member that is going to be invited to the organization
inviter_user_idstringoptional
The ID of the user that invites the new member to the organization. Must be an administrator in the organization.
rolestringrequired
The role of the new member in the organization
public_metadataobjectoptional
Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.
private_metadataobjectoptional
Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.
redirect_urlstringoptional
Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.
expires_in_daysintegeroptional
The number of days the invitation will be valid for. By default, the invitation has a 30 days expire.
notifybooleanoptional
Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.
Default:true

6 status codes
200An organization invitation
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:organization_invitation
idstringrequired
email_addressstringrequired
rolestringrequired
role_namestringrequired
organization_idstringoptional
inviter_idstringrequired
public_inviter_dataobjectrequired
An organization inviter's public user data
statusstringoptional
public_metadataobjectrequired
private_metadataobjectoptional
urlstringrequired
expires_atintegerrequired
Unix timestamp of expiration.
created_atintegerrequired
Unix timestamp of creation.
updated_atintegerrequired
Unix timestamp of last update.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
402Payment required
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 402 is returned: Payment required. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.