Skip to main content

createInvitationBulk()

Caution

This endpoint is rate limited to 25 requests per hour per application instance.

Creates multiple invitations for the given email addresses, and sends the invitation emails.

If an email address has already been invited or already exists in your application, trying to create a new invitation will return an error. To bypass this error and create a new invitation anyways, set ignoreExisting to true.

Returns an array of each created Invitation object.

function createInvitationBulk(params: CreateBulkParams): Promise<Invitation[]>

CreateBulkParams

  • Name
    emailAddress
    Type
    string
    Description

    The email address of the user to invite.

  • Name
    expiresInDays?
    Type
    number
    Description

    The number of days until the invitation expires. Defaults to 30.

  • Name
    ignoreExisting?
    Type
    boolean
    Description

    Whether an invitation should be created if there is already an existing invitation for this email address, or if the email address already exists in the application. Defaults to false.

  • Name
    notify?
    Type
    boolean
    Description

    Whether an email invitation should be sent to the given email address. Defaults to true.

  • Name
    publicMetadata?
    Type
    UserPublicMetadata
    Description

    Metadata that can be read and set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata (User.publicMetadata).

  • Name
    redirectUrl?
    Type
    string
    Description

    The full URL or path where the user will land after accepting the invitation. See the custom flow guide for handling application invitations.

  • Name
    templateSlug?
    Type
    "invitation" | "waitlist_invitation"
    Description

    The template slug to use for the invitation. Defaults to invitation.

Usage

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

// Each object in the array represents a single invitation
const params = [
  {
    emailAddress: 'invite@example.com',
    redirectUrl: 'https://www.example.com/my-sign-up',
    publicMetadata: {
      example: 'metadata',
      example_nested: {
        nested: 'metadata',
      },
    },
  },
  {
    emailAddress: 'invite2@example.com',
    redirectUrl: 'https://www.example.com/my-sign-up',
    publicMetadata: {
      example: 'metadata',
      example_nested: {
        nested: 'metadata',
      },
    },
  },
]

const response = await clerkClient.invitations.createInvitationBulk(params)

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint POST/invitations/bulk. See the BAPI reference for more information.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub