Clerk API (unofficial showcase)
POST/invitations

Create an invitation

Creates a new invitation for the given email address and sends the invitation email. Keep in mind that you cannot create an invitation if there is already one for the given email address. Also, trying to create an invitation for an email address that already exists in your application will result to an error.

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

7 body fields

Required parameters

email_addressstringrequired
The email address the invitation will be sent to
public_metadataobjectoptional
Metadata that will be attached to the newly created invitation. The value of this property should be a well-formed JSON object. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.
redirect_urlstringoptional
Optional URL which specifies where to redirect the user once they click the invitation link. This is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components.
notifybooleanoptional
Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.
Default:true
ignore_existingbooleanoptional
Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.
Default:false
expires_in_daysintegeroptional
The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
template_slugstringoptional
The slug of the email template to use for the invitation email.
Allowed:invitationwaitlist_invitation

3 status codes
200Success
objectstringrequired
Allowed:invitation
idstringrequired
email_addressstringrequired
public_metadataobjectrequired
revokedbooleanoptional
statusstringrequired
Allowed:pendingacceptedrevokedexpired
urlstringoptional
expires_atintegeroptional
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
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 422 is returned: Invalid request parameters.