---
title: "Create an invitation"
method: POST
path: "/invitations"
tags: ["Invitations"]
---

# Create an invitation

`POST /invitations`

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.

## Request body

- object
  - `email_address` string, required — The email address the invitation will be sent to
  - `public_metadata` object — 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_url` string — 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.
  - `notify` boolean, nullable — Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.
  - `ignore_existing` boolean, nullable — Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.
  - `expires_in_days` integer, nullable — The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
  - `template_slug` 'invitation' | 'waitlist_invitation' — The slug of the email template to use for the invitation email.

## Response `200`

Success

- Invitation
  - `object` 'invitation', required
  - `id` string, required
  - `email_address` string, email, required
  - `public_metadata` object, required
  - `revoked` boolean
  - `status` 'pending' | 'accepted' | 'revoked' | 'expired', required
  - `url` string
  - `expires_at` integer, nullable — Unix timestamp of expiration.
  - `created_at` integer, required — Unix timestamp of creation.
  - `updated_at` integer, required — Unix timestamp of last update.

## Other responses

- `400` — Request was not successful
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/cf036e7951d3/schema)