Docs

createInvitation()

Creates a new invitation for the given email address and sends the invitation email.

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.

function createInvitation: (params: CreateParams) => Promise<Invitation>;
  • Name
    emailAddress
    Type
    string
    Description

    The email address of the user to invite.

  • Name
    redirectUrl?
    Type
    string
    Description

    The URL to redirect the user to when they visit the invitation link.

  • Name
    publicMetadata?
    Type
    Record<string, unknown>
    Description

    Metadata saved on the invitation that is visible to both your Frontend and Backend APIs.

  • Name
    notify?
    Type
    boolean
    Description

    Optional flag to denote whether an email invitation should be sent to the given email address. Defaults to true.

  • Name
    ignoreExisting?
    Type
    boolean
    Description

    Optional flag to denote 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.

const response = await clerkClient.invitations.createInvitation({
  emailAddress: 'invite@example.com',
  redirectUrl: 'https://www.example.com/my-sign-up',
  publicMetadata: {
    "example": "metadata",
    "example_nested": {
      "nested": "metadata",
    },
  }
});

console.log(response);
/*
_Invitation {
  id: 'inv_2b6NfrkHKSU6mSYx2FwX4AtzeFi',
  emailAddress: 'invite@example.com',
  publicMetadata: { example: 'metadata', example_nested: [Object] },
  createdAt: 1705531674576,
  updatedAt: 1705531674576,
  status: 'pending',
  revoked: undefined
}
*/

Backend API (BAPI) endpoint

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

Feedback

What did you think of this content?