Clerk API (unofficial showcase)
POST/invitations/bulk

Create multiple invitations

Creates multiple invitations for the supplied email addresses. Include an email_address in each item; set ignore_existing to allow an existing invitation, but you cannot invite an address associated with an existing user. Send at most 10 invitations per request, and use notify to control whether invitation emails are sent.

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

7 body fields

An array of invitation details containing between 1 and 10 items.

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
The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations).
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_invitationDefault:invitation

3 status codes
200Returns an array of created invitation objects, including each invitation's identifier, email address, metadata, status, and timestamps.
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.
400Returned when the request is not successful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is unsuccessful, and a 422 is returned when request parameters are invalid. Each item must include email_address, and the array must contain 1 to 10 items. An email address must not belong to an existing user; ignore_existing can allow an existing invitation but cannot bypass this restriction.