Clerk Waitlist Entries API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Waitlist Entries 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: Waitlist Entries
  description: Manage waitlist entries.
paths:
  /waitlist_entries:
    get:
      operationId: ListWaitlistEntries
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: list
      summary: List All Waitlist Entries
      description: 'Retrieve a list of waitlist entries for the instance.

        Entries are ordered by creation date in descending order by default.

        Supports filtering by email address or status and pagination with limit and offset parameters.'
      tags:
      - Waitlist Entries
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: query
        name: query
        description: Filter waitlist entries by `email_address` or `id`
        required: false
        schema:
          type: string
      - in: query
        name: status
        description: Filter waitlist entries by their status
        required: false
        schema:
          type: string
          enum:
          - pending
          - invited
          - completed
          - rejected
      - in: query
        name: order_by
        required: false
        description: 'Specify the order of results. Supported values are:

          - `created_at`

          - `email_address`

          - `invited_at`


          Use `+` for ascending or `-` for descending order. Defaults to `-created_at`.'
        schema:
          type: string
          default: -created_at
      responses:
        '200':
          $ref: '#/components/responses/WaitlistEntries'
    post:
      operationId: CreateWaitlistEntry
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: create
      summary: Create a Waitlist Entry
      description: 'Creates a new waitlist entry for the given email address.

        If the email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned.'
      tags:
      - Waitlist Entries
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email_address:
                  type: string
                  description: The email address to add to the waitlist
                notify:
                  type: boolean
                  description: 'Optional flag which denotes whether a confirmation email should be sent to the given email address.

                    Defaults to `true`.'
                  default: true
                  nullable: true
              required:
              - email_address
      responses:
        '200':
          $ref: '#/components/responses/WaitlistEntry'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /waitlist_entries/bulk:
    post:
      operationId: CreateBulkWaitlistEntries
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: bulkCreate
      summary: Create Multiple Waitlist Entries
      description: 'Creates multiple waitlist entries for the provided email addresses.

        You can choose whether to send confirmation emails by setting the `notify` parameter to `true` or `false` for each entry.

        If the `notify` parameter is omitted, it defaults to `true`.


        If an email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned.

        Duplicate email addresses within the same request are not allowed.


        This endpoint is limited to a maximum of 50 entries per API call. If you need to add more entries, please make multiple requests.'
      tags:
      - Waitlist Entries
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 50
              items:
                type: object
                additionalProperties: false
                properties:
                  email_address:
                    type: string
                    format: email
                    description: The email address to add to the waitlist
                  notify:
                    type: boolean
                    description: 'Optional flag which denotes whether a confirmation email should be sent to the given email address.

                      Defaults to `true`.'
                    nullable: true
                    default: true
                required:
                - email_address
      responses:
        '200':
          $ref: '#/components/responses/WaitlistEntry.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /waitlist_entries/{waitlist_entry_id}:
    delete:
      operationId: DeleteWaitlistEntry
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: delete
      summary: Delete a Pending Waitlist Entry
      description: Delete a pending waitlist entry.
      tags:
      - Waitlist Entries
      parameters:
      - name: waitlist_entry_id
        in: path
        description: The ID of the waitlist entry to delete
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /waitlist_entries/{waitlist_entry_id}/invite:
    post:
      operationId: InviteWaitlistEntry
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: invite
      summary: Invite a Waitlist Entry
      description: Send an invite to the email address in a waitlist entry.
      tags:
      - Waitlist Entries
      parameters:
      - name: waitlist_entry_id
        in: path
        description: The ID of the waitlist entry to invite
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                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
      responses:
        '200':
          $ref: '#/components/responses/WaitlistEntry'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /waitlist_entries/{waitlist_entry_id}/reject:
    post:
      operationId: RejectWaitlistEntry
      x-speakeasy-group: waitlistEntries
      x-speakeasy-name-override: reject
      summary: Reject a Waitlist Entry
      description: Reject a waitlist entry.
      tags:
      - Waitlist Entries
      parameters:
      - name: waitlist_entry_id
        in: path
        description: The ID of the waitlist entry to reject
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/WaitlistEntry'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
        external_id:
          type: string
      required:
      - object
      - deleted
    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
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    WaitlistEntry:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - waitlist_entry
        id:
          type: string
        email_address:
          type: string
          format: email
        status:
          type: string
          enum:
          - pending
          - invited
          - rejected
          - completed
          example: pending
        is_locked:
          type: boolean
          description: 'Indicates if the waitlist entry is locked. Locked entries are being processed in a batch action and are unavailable for other actions.

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

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

            '
        invitation:
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/Invitation'
      required:
      - object
      - id
      - email_address
      - status
      - created_at
      - updated_at
  responses:
    WaitlistEntry:
      description: A Waitlist Entry
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WaitlistEntry'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    WaitlistEntries:
      description: List of waitlist entries
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/WaitlistEntry'
              total_count:
                type: integer
                description: Total number of waitlist entries
            required:
            - data
            - total_count
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    WaitlistEntry.List:
      description: Array of waitlist entries
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/WaitlistEntry'
  parameters:
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true