Clerk Invitations API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Invitations API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions).


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: Invitations
  description: Invitations allow you to invite someone to sign up to your application, via email.
  externalDocs:
    url: https://clerk.com/docs/authentication/invitations
paths:
  /invitations:
    post:
      operationId: CreateInvitation
      x-speakeasy-group: invitations
      x-speakeasy-name-override: create
      summary: Create an Invitation
      description: '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.'
      tags:
      - Invitations
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: string
                  description: The email address the invitation will be sent to
                public_metadata:
                  type: object
                  description: '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.'
                  additionalProperties: true
                redirect_url:
                  type: string
                  description: '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:
                  type: boolean
                  description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                    Defaults to `true`.'
                  nullable: true
                  default: true
                ignore_existing:
                  type: boolean
                  description: Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.
                  nullable: true
                  default: false
                expires_in_days:
                  type: integer
                  description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
                  nullable: true
                  minimum: 1
                  maximum: 365
                template_slug:
                  type: string
                  enum:
                  - invitation
                  - waitlist_invitation
                  description: The slug of the email template to use for the invitation email.
              required:
              - email_address
      responses:
        '200':
          $ref: '#/components/responses/Invitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      summary: List All Invitations
      x-speakeasy-group: invitations
      x-speakeasy-name-override: list
      description: Returns all non-revoked invitations for your application, sorted by creation date
      operationId: ListInvitations
      parameters:
      - in: query
        name: status
        required: false
        description: Filter invitations based on their status
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
      - in: query
        required: false
        name: query
        description: Filter invitations based on their `email_address` or `id`
        schema:
          type: string
      - name: order_by
        in: query
        required: false
        description: 'Allows to return invitations in a particular order.

          At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`.

          In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.

          For example, if you want invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied.

          Defaults to `-created_at`.'
        schema:
          type: string
          default: -created_at
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      tags:
      - Invitations
      responses:
        '200':
          $ref: '#/components/responses/Invitation.List'
  /invitations/bulk:
    post:
      operationId: CreateBulkInvitations
      x-speakeasy-group: invitations
      x-speakeasy-name-override: bulkCreate
      summary: Create Multiple Invitations
      description: 'Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the

        invitations as emails by setting the `notify` parameter to `true`. There cannot be an existing invitation for any

        of the email addresses you provide unless you set `ignore_existing` to `true` for specific email addresses. Please

        note that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed.


        This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.'
      tags:
      - Invitations
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: object
                additionalProperties: false
                properties:
                  email_address:
                    type: string
                    description: The email address the invitation will be sent to
                  public_metadata:
                    type: object
                    nullable: true
                    description: '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.'
                    additionalProperties: true
                  redirect_url:
                    type: string
                    nullable: true
                    description: 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).
                  notify:
                    type: boolean
                    description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                      Defaults to true.'
                    nullable: true
                    default: true
                  ignore_existing:
                    type: boolean
                    description: 'Whether an invitation should be created if there is already an existing invitation for this email

                      address, or it''s claimed by another user.'
                    nullable: true
                    default: false
                  expires_in_days:
                    type: integer
                    description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
                    nullable: true
                    minimum: 1
                    maximum: 365
                  template_slug:
                    type: string
                    enum:
                    - invitation
                    - waitlist_invitation
                    description: The slug of the email template to use for the invitation email.
                    default: invitation
                required:
                - email_address
      responses:
        '200':
          $ref: '#/components/responses/Invitation.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /invitations/{invitation_id}/revoke:
    post:
      operationId: RevokeInvitation
      x-speakeasy-group: invitations
      x-speakeasy-name-override: revoke
      summary: Revokes an Invitation
      description: 'Revokes the given invitation.

        Revoking an invitation will prevent the user from using the invitation link that was sent to them.

        However, it doesn''t prevent the user from signing up if they follow the sign up flow.

        Only active (i.e. non-revoked) invitations can be revoked.'
      tags:
      - Invitations
      parameters:
      - name: invitation_id
        in: path
        description: The ID of the invitation to be revoked
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Invitation.Revoked'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /v1/organizations/{organization_id}/invitations:
    post:
      summary: Create Organization Invitation
      description: 'Create an invitation for a user to join an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: createOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitation will be created.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: string
                  description: The email address the invitation will be sent to.
                  nullable: false
                role:
                  type: string
                  description: 'The role that will be assigned to the user after joining.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.'
                  nullable: false
              required:
              - email_address
              - role
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
    get:
      summary: Get All Organization Invitations
      description: 'Retrieve all invitations for an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: getOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitation will be retrieved.
      - in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
          - invalid
          - completed
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/organizations/{organization_id}/invitations/bulk:
    post:
      summary: Bulk Create Organization Invitations
      description: 'Create an invitation for a user to join an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: bulkCreateOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be created.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: array
                  description: An array of email addresses the invitations will be sent to.
                  nullable: false
                  items:
                    type: string
                role:
                  type: string
                  description: 'The role that will be assigned to each of the users after joining.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.'
                  nullable: false
              required:
              - email_address
              - role
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/organizations/{organization_id}/invitations/pending:
    get:
      summary: Get All Pending Organization Invitations
      deprecated: true
      description: 'Get a list of pending invitations for an organization.


        This endpoint is deprecated. Instead use the `/v1/organizations/{organization_id}/invitations`

        with a query parameter of `status=pending`.'
      operationId: getAllPendingOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be retrieved.
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/organizations/{organization_id}/invitations/{invitation_id}/revoke:
    post:
      summary: Revoke Pending Organization Invitation
      description: 'Revoke a pending organization invitation.


        The current user must have permissions to manage the members of the organization.'
      operationId: revokePendingOrganizationInvitation
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be retrieved.
      - in: path
        name: invitation_id
        required: true
        schema:
          type: string
        description: The ID of the invitation to revoke.
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
components:
  schemas:
    Stubs.Verification.GoogleOneTap:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_google_one_tap
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - google_one_tap
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.OrganizationInvitation:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - organization_invitation
        email_address:
          type: string
        role:
          type: string
        role_name:
          type: string
        organization_id:
          type: string
        public_organization_data:
          type: object
          allOf:
          - $ref: '#/components/schemas/Client.PublicOrganizationData'
        status:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - pending
          - revoked
          - accepted
          - expired
          - completed
        public_metadata:
          type: object
          additionalProperties: true
        url:
          type: string
          nullable: true
        expires_at:
          type: integer
          nullable: true
          format: int64
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
      required:
      - object
      - id
      - email_address
      - role
      - role_name
      - public_metadata
      - url
      - expires_at
      - created_at
      - updated_at
    Token:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - token
        jwt:
          type: string
          description: 'String representing the encoded JWT value.

            '
      required:
      - object
      - jwt
    Stubs.Verification.SAML:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_saml
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - saml
        external_verification_redirect_url:
          nullable: true
          type: string
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type: object
            nullable: true
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.PublicUserData:
      type: object
      additionalProperties: false
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        image_url:
          type: string
          nullable: true
        has_image:
          type: boolean
        identifier:
          type: string
        profile_image_url:
          type: string
          nullable: true
          deprecated: true
          description: Use `image_url` instead.
        user_id:
          type: string
          nullable: true
        username:
          type: string
          nullable: true
        banned:
          type: boolean
      required:
      - first_name
      - last_name
      - identifier
      - has_image
    Invitation:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - invitation
        id:
          type: string
        email_address:
          type: string
          format: email
        public_metadata:
          type: object
          additionalProperties: true
        revoked:
          type: boolean
          example: false
        status:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
          example: pending
        url:
          type: string
        expires_at:
          type: integer
          format: int64
          nullable: true
          description: 'Unix timestamp of expiration.

            '
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      required:
      - object
      - id
      - email_address
      - public_metadata
      - status
      - created_at
      - updated_at
    Stubs.Verification.Password:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_password
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - password
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.ClientWrappedOrganizationInvitations:
      type: object
      additionalProperties: false
      properties:
        response:
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/Client.OrganizationInvitation'
          - type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Client.OrganizationInvitation'
              total_count:
                type: integer
                format: int64
        client:
          type: object
          nullable: false
          allOf:
          - $ref: '#/components/schemas/schemas-Client.Client'
      required:
      - response
      - client
    Client.PhoneNumber:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - phone_number
        phone_number:
          type: string
        reserved_for_second_factor:
          type: boolean
        default_second_factor:
          type: boolean
        reserved:
          type: boolean
        verification:
          nullable: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        backup_codes:
          type: array
          items:
            type: string
          nullable: true
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - phone_number
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    Client.EmailAddress:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - email_address
        email_address:
          type: string
        reserved:
          type: boolean
        verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Invitation'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
          - $ref: '#/components/schemas/Stubs.Verification.FromOauth'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        matches_sso_connection:
          description: 'Indicates whether this email address domain matches an active enterprise connection.

            '
          type: boolean
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - email_address
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    Stubs.SignUpVerification.AdditionalFields:
      type: object
      properties:
        next_action:
          type: string
          enum:
          - needs_prepare
          - needs_attempt
          - ''
        supported_strategies:
          type: array
          items:
            type: string
      required:
      - next_action
      - supported_strategies
    schemas-Client.Session:
      allOf:
      - $ref: '#/components/schemas/schemas-Client.SessionBase'
      - type: object
        properties:
          last_active_organization_id:
            type: string
            nullable: true
          user:
            $ref: '#/components/schemas/Client.User'
          public_user_data:
            type: object
            nullable: true
            allOf:
            - $ref: '#/components/schemas/Client.PublicUserData'
          factor_verification_age:
            type: array
            description: Each item represents the minutes that have passed since the last time a first or second factor were verified.
            items:
              type: integer
          created_at:
            type: integer
            format: int64
            description: Unix timestamp of creation.
            example: 1700690400000
          updated_at:
            type: integer
            format: int64
            description: Unix timestamp of last update.
            example: 1700690400000
        required:
        - last_active_organization_id
        - public_user_data
        - factor_verification_age
        - created_at
        - updated_at
    Client.SAMLAccount:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - saml_account
        provider:
          type: string
        active:
          type: boolean
        email_address:
          type: string
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
          nullable: true
        enterprise_connection_id:
          type: string
          nullable: true
        last_authenticated_at:
          type: integer
          format: int64
          nullable: true
          description: 'Unix timestamp of last authentication.

            '
        public_metadata:
          type: object
          additionalProperties: true
        verification:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
        saml_connection:
          type: object
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Stubs.SAMLConnection.SAMLAccount'
      required:
      - id
      - object
      - provider
      - active
      - email_address
      - first_name
      - last_name
      - provider_user_id
      - public_metadata
      - saml_connection
      - verification
    schemas-Client.SessionBase:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - session
        status:
          type: string
          enum:
          - active
          - revoked
          - ended
          - expired
          - removed
          - abandoned
          - pending
        expire_at:
          type: integer
          format: int64
        abandon_at:
          type: integer
          format: int64
        last_active_at:
          type: integer
          format: int64
        last_active_token:
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/Token'
        actor:
          type: object
          nullable: true
          additionalProperties: true
        tasks:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Client.SessionTask'
      required:
      - id
      - object
      - status
      - expire_at
      - abandon_at
      - last_active_at
    Stubs.Verification.OTP:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_otp
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          typ

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-invitations-api-openapi.yml