Clerk Sign Ups API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Sign Ups 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: Sign Ups
  description: Sign-up objects track the progress of a sign-up attempt and store any field collected from user input.
  externalDocs:
    url: https://clerk.com/docs/references/javascript/sign-up
paths:
  /sign_ups/{id}:
    get:
      operationId: GetSignUp
      x-speakeasy-group: signUps
      x-speakeasy-name-override: get
      summary: Retrieve a Sign-up by ID
      description: Retrieve the details of the sign-up with the given ID
      tags:
      - Sign Ups
      parameters:
      - name: id
        in: path
        description: The ID of the sign-up to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SignUp'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
    patch:
      operationId: UpdateSignUp
      x-speakeasy-group: signUps
      x-speakeasy-name-override: update
      summary: Update a Sign-up
      description: Update the sign-up with the given ID
      tags:
      - Sign Ups
      parameters:
      - name: id
        in: path
        description: The ID of the sign-up to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id:
                  type: string
                  description: 'The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution.

                    This will be copied to the resulting user when the sign-up is completed.'
                  nullable: true
                custom_action:
                  type: boolean
                  description: If true, the sign-up will be marked as a custom action.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/SignUp'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
  /v1/client/sign_ups:
    post:
      summary: Create Sign-up
      description: Creates or replaces the sign-up on the current Client object.
      tags:
      - Sign Ups
      operationId: createSignUps
      parameters:
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                transfer:
                  type: boolean
                  nullable: true
                password:
                  type: string
                  nullable: true
                first_name:
                  type: string
                  nullable: true
                last_name:
                  type: string
                  nullable: true
                username:
                  type: string
                  nullable: true
                email_address:
                  type: string
                  nullable: true
                phone_number:
                  type: string
                  nullable: true
                email_address_or_phone_number:
                  type: string
                  nullable: true
                unsafe_metadata:
                  type: string
                  nullable: true
                strategy:
                  type: string
                  description: 'Strategy used to sign up.

                    Can be one of `email_code`, `email_link`, `enterprise_sso`, `google_one_tap`, `oauth_[provider]`, `oauth_token_[provider]`, `phone_code`, `saml`, `ticket`, `web3_[provider]_signature`'
                  nullable: true
                action_complete_redirect_url:
                  type: string
                  nullable: true
                redirect_url:
                  type: string
                  nullable: true
                ticket:
                  type: string
                  nullable: true
                web3_wallet:
                  type: string
                  nullable: true
                token:
                  type: string
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
                  nullable: true
                code:
                  type: string
                  description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies.
                  nullable: true
                captcha_token:
                  type: string
                  nullable: true
                captcha_error:
                  type: string
                  nullable: true
                captcha_widget_type:
                  type: string
                  nullable: true
                legal_accepted:
                  type: boolean
                  nullable: true
                  description: Has the value `true` if the user has accepted the legal requirements.
                oidc_login_hint:
                  type: string
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                  nullable: true
                oidc_prompt:
                  type: string
                  description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SignUp'
        '307':
          description: Redirect, no body.
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sign_ups/{sign_up_id}:
    get:
      summary: Get Sign-up
      description: Returns the sign-up by ID. Must be associated with the current Client object.
      tags:
      - Sign Ups
      operationId: getSignUps
      parameters:
      - in: path
        name: sign_up_id
        required: true
        schema:
          type: string
        description: The sign up unique identifier.
      responses:
        '200':
          $ref: '#/components/responses/Client.SignUp'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
    patch:
      summary: Update Sign-up
      description: Updates the sign-up object specified by ID, with the supplied parameters.
      tags:
      - Sign Ups
      operationId: updateSignUps
      parameters:
      - in: path
        name: sign_up_id
        required: true
        schema:
          type: string
        description: The sign up unique identifier.
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                password:
                  type: string
                  nullable: true
                first_name:
                  type: string
                  nullable: true
                last_name:
                  type: string
                  nullable: true
                username:
                  type: string
                  nullable: true
                email_address:
                  type: string
                  nullable: true
                phone_number:
                  type: string
                  nullable: true
                email_address_or_phone_number:
                  type: string
                  nullable: true
                unsafe_metadata:
                  type: string
                  nullable: true
                strategy:
                  type: string
                  description: 'Strategy used to sign up.

                    Can be one of `email_code`, `email_link`, `enterprise_sso`, `google_one_tap`, `oauth_[provider]`, `oauth_token_[provider]`, `phone_code`, `saml`, `ticket`, `web3_[provider]_signature`'
                  nullable: true
                redirect_url:
                  type: string
                  nullable: true
                action_complete_redirect_url:
                  type: string
                  nullable: true
                ticket:
                  type: string
                  nullable: true
                web3_wallet:
                  type: string
                  nullable: true
                token:
                  type: string
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
                  nullable: true
                code:
                  type: string
                  description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies.
                  nullable: true
                legal_accepted:
                  type: boolean
                  nullable: true
                  description: 'Has the value `true` if the user has accepted the legal requirements.

                    '
                oidc_login_hint:
                  type: string
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                  nullable: true
                oidc_prompt:
                  type: string
                  description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SignUp'
        '307':
          description: Redirect, no body.
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sign_ups/{sign_up_id}/prepare_verification:
    post:
      summary: Prepare Sign-up Identification Verification
      description: 'Prepares verification for the sign-up specified by `{id}`.


        Depending on the given strategy, the API will prepare the verification for the current sign-up.

        In particular,

        * for `email_code`, the API will send a verification email to the email address currently load up in the sign-up

        * for `phone_code`, the API will send a verification SMS to the phone number currently load up in the sign-up

        '
      tags:
      - Sign Ups
      operationId: prepareSignUpsVerification
      parameters:
      - in: path
        name: sign_up_id
        required: true
        schema:
          type: string
        description: The sign up unique identifier.
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                strategy:
                  type: string
                  description: 'The verification strategy


                    - email_code

                    - email_link

                    - phone_code

                    - web3_metamask_signature

                    - web3_base_signature

                    - web3_coinbase_wallet_signature

                    - web3_okx_wallet_signature

                    - saml

                    - oauth'
                redirect_url:
                  type: string
                  nullable: true
                action_complete_redirect_url:
                  type: string
                  nullable: true
                oidc_login_hint:
                  type: string
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                  nullable: true
                oidc_prompt:
                  type: string
                  description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SignUp'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
        '429':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sign_ups/{sign_up_id}/attempt_verification:
    post:
      summary: Attempt Sign-up Identification Verification
      description: Attempts to verify the identification that corresponds to the given strategy using the given verification code.
      tags:
      - Sign Ups
      operationId: attemptSignUpsVerification
      parameters:
      - in: path
        name: sign_up_id
        required: true
        schema:
          type: string
        description: The sign up unique identifier.
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                strategy:
                  type: string
                  description: The verification strategy
                  enum:
                  - email_code
                  - email_link
                  - phone_code
                  - web3_metamask_signature
                  - web3_base_signature
                  - web3_coinbase_wallet_signature
                  - web3_okx_wallet_signature
                  - web3_solana_signature
                  - google_one_tap
                code:
                  nullable: true
                  type: string
                  description: The verification code
                signature:
                  nullable: true
                  type: string
                  description: The verification web3 signature
                token:
                  type: string
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SignUp'
        '307':
          description: Redirect, no body.
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
        '429':
          $ref: '#/components/responses/ClerkErrors'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Client.SignUp:
      description: Returns the sign up object, as well as the updated session object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Client.ClientWrappedSignUp'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    SignUp:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignUp'
  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
    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
    Client.ClientWrappedSignUp:
      type: object
      additionalProperties: false
      properties:
        response:
          $ref: '#/components/schemas/Client.SignUp'
        client:
          $ref: '#/components/schemas/schemas-Client.Client'
      required:
      - response
      - client
    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.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
    SignUpVerification:
      type: object
      nullable: true
      additionalProperties: true
      properties:
        next_action:
          type: string
          enum:
          - needs_prepare
          - needs_attempt
          - ''
        supported_strategies:
          type: array
          items:
            type: string
    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:
          type: string
          enum:
          - phone_code
          - email_code
          - reset_password_email_code
          - reset_password_phone_code
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
      required:
      - status
      - strategy
      - expire_at
    Stubs.SignInFactor:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
          - ticket
          - password
          - email_code
          - email_link
          - phone_code
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
          - totp
          - backup_code
          - oauth_apple
          - oauth_google
          - oauth_facebook
          - oauth_hubspot
          - oauth_github
          - oauth_mock
          - oauth_custom_mock
          - oauth_token_mock
          - saml
          - enterprise_sso
          - reset_password_email_code
          - reset_password_phone_code
          - passkey
          - google_one_tap
        safe_identifier:
          type: string
        enterprise_connection_id:
          type: string
        enterprise_connection_name:
          type: string
        email_address_id:
          type: string
        phone_number_id:
          type: string
        web3_wallet_id:
          type: string
        passkey_id:
          type: string
        primary:
          type: boolean
          nullable: true
        external_verification_redirect_url:
          nullable: true
          type: string
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.Ticket:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_ticket
        status:
          type: string
          enum:
          - unverified
          - verified
          - expired
        strategy:
          type: string
          enum:
          - ticket
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Stubs.Verification.Invitation:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_invitation
        status:
          type: string
          enum:
          - verified
        strategy:
          type: string
          enum:
          - invitation
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    SignUp:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - sign_up_attempt
        id:
          type: string
        status:
          type: string
          enum:
          - missing_requirements
          - complete
         

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