Skip to main content
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>

CreateParams

  • Name
    emailAddress
    Type
    string
    Description

    The email address of the user to invite.

  • Name
    redirectUrl?
    Type
    string
    Description

    The full URL or path 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.

  • Name
    publicMetadata?
    Type
    UserPublicMetadataJavaScript Icon
    Description

    Metadata that can be read from both the Frontend API and Backend API, but can be 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.

  • Name
    notify?
    Type
    boolean
    Description

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

  • 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
    expiresInDays?
    Type
    number
    Description

    The number of days the invitation will be valid for. By default, the invitation expires after 30 days.

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

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

Usage

Note

Using clerkClient varies based on your framework. Refer to the JS Backend SDK overview for usage details, including guidance on how to access the userId and other properties.

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',
    },
  },
})

Example

app/api/example/route.ts
import { clerkClient } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'

export async function GET() {
  try {
    const client = await clerkClient()
    const invitation = await client.invitations.createInvitation({
      emailAddress: 'invite@example.com',
      redirectUrl: 'https://www.example.com/my-sign-up',
      publicMetadata: {
        example: 'metadata',
        example_nested: {
          nested: 'metadata',
        },
      },
    })
    return NextResponse.json({ message: 'Invitation created', invitation })
  } catch (error) {
    console.log(error)
    return NextResponse.json({ error: 'Error creating invitation' })
  }
}
src/api/example.ts
import type { APIRoute } from 'astro'
import { clerkClient } from '@clerk/astro/server'

export const GET: APIRoute = async (context) => {
  await clerkClient(context).invitations.createInvitation({
    emailAddress: 'invite@example.com',
    redirectUrl: 'https://www.example.com/my-sign-up',
    publicMetadata: {
      example: 'metadata',
      example_nested: {
        nested: 'metadata',
      },
    },
  })

  return new Response(JSON.stringify({ success: true }), { status: 200 })
}
public.ts
import { getAuth, clerkClient } from '@clerk/express'

app.post('/createUser', async (req, res) => {
  await clerkClient.invitations.createInvitation({
    emailAddress: 'invite@example.com',
    redirectUrl: 'https://www.example.com/my-sign-up',
    publicMetadata: {
      example: 'metadata',
      example_nested: {
        nested: 'metadata',
      },
    },
    password: 'password',
  })

  res.status(200).json({ success: true })
})
app/routes/example.tsx
import { clerkClient } from '@clerk/react-router/server'
import type { Route } from './+types/example'

export async function loader(args: Route.LoaderArgs) {
  await clerkClient.invitations.createInvitation({
    emailAddress: 'invite@example.com',
    redirectUrl: 'https://www.example.com/my-sign-up',
    publicMetadata: {
      example: 'metadata',
      example_nested: {
        nested: 'metadata',
      },
    },
  })

  return { success: true }
}
app/routes/api/example.tsx
import { json } from '@tanstack/react-start'
import { createFileRoute } from '@tanstack/react-router'
import { clerkClient } from '@clerk/tanstack-react-start/server'

export const ServerRoute = createFileRoute('/api/example')({
  server: {
    handlers: {
      GET: async () => {
        await clerkClient().invitations.createInvitation({
          emailAddress: 'invite@example.com',
          redirectUrl: 'https://www.example.com/my-sign-up',
          publicMetadata: {
            example: 'metadata',
            example_nested: {
              nested: 'metadata',
            },
          },
        })

        return json({ success: true })
      },
    },
  },
})

Backend API (BAPI) endpoint

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

Here's an example of making a request directly to the endpoint using cURL.

terminal
curl https://api.clerk.com/v1/invitations -X POST -d '{"email_address": "email@example.com"}' -H "Authorization:Bearer YOUR_SECRET_KEY" -H 'Content-Type:application/json'

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on