Clerk Sign Ups API

openapi: 3.2.0
info:
  title: Clerk Com Sign Ups API
  termsOfService: https://clerk.com/terms
  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
  version: '1.0'
  description: 'Operations tagged Sign Ups across 2 of this provider''s published API definitions: clerk-backend-api-openapi.yml, clerk-frontend-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clerk.com/v1
- url: https://{domain}.clerk.accounts.dev
  variables:
    domain:
      default: example-destined-camel-13
      description: Your Development Instance Frontend API Domain.
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'
      security:
      - bearerAuth: []
    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
                  - 'null'
                  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.'
                custom_action:
                  type:
                  - boolean
                  - 'null'
                  description: If true, the sign-up will be marked as a custom action.
      responses:
        '200':
          $ref: '#/components/responses/SignUp'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.clerk.com/v1
  /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
                  - 'null'
                password:
                  type:
                  - string
                  - 'null'
                first_name:
                  type:
                  - string
                  - 'null'
                last_name:
                  type:
                  - string
                  - 'null'
                username:
                  type:
                  - string
                  - 'null'
                email_address:
                  type:
                  - string
                  - 'null'
                phone_number:
                  type:
                  - string
                  - 'null'
                email_address_or_phone_number:
                  type:
                  - string
                  - 'null'
                unsafe_metadata:
                  type:
                  - string
                  - 'null'
                strategy:
                  type:
                  - string
                  - 'null'
                  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`'
                action_complete_redirect_url:
                  type:
                  - string
                  - 'null'
                redirect_url:
                  type:
                  - string
                  - 'null'
                ticket:
                  type:
                  - string
                  - 'null'
                web3_wallet:
                  type:
                  - string
                  - 'null'
                token:
                  type:
                  - string
                  - 'null'
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
                code:
                  type:
                  - string
                  - 'null'
                  description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies.
                captcha_token:
                  type:
                  - string
                  - 'null'
                captcha_error:
                  type:
                  - string
                  - 'null'
                captcha_widget_type:
                  type:
                  - string
                  - 'null'
                legal_accepted:
                  type:
                  - boolean
                  - 'null'
                  description: Has the value `true` if the user has accepted the legal requirements.
                oidc_login_hint:
                  type:
                  - string
                  - 'null'
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                oidc_prompt:
                  type:
                  - string
                  - 'null'
                  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.
      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'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /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'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    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
                  - 'null'
                first_name:
                  type:
                  - string
                  - 'null'
                last_name:
                  type:
                  - string
                  - 'null'
                username:
                  type:
                  - string
                  - 'null'
                email_address:
                  type:
                  - string
                  - 'null'
                phone_number:
                  type:
                  - string
                  - 'null'
                email_address_or_phone_number:
                  type:
                  - string
                  - 'null'
                unsafe_metadata:
                  type:
                  - string
                  - 'null'
                strategy:
                  type:
                  - string
                  - 'null'
                  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`'
                redirect_url:
                  type:
                  - string
                  - 'null'
                action_complete_redirect_url:
                  type:
                  - string
                  - 'null'
                ticket:
                  type:
                  - string
                  - 'null'
                web3_wallet:
                  type:
                  - string
                  - 'null'
                token:
                  type:
                  - string
                  - 'null'
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
                code:
                  type:
                  - string
                  - 'null'
                  description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies.
                legal_accepted:
                  type:
                  - boolean
                  - 'null'
                  description: 'Has the value `true` if the user has accepted the legal requirements.

                    '
                oidc_login_hint:
                  type:
                  - string
                  - 'null'
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                oidc_prompt:
                  type:
                  - string
                  - 'null'
                  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.
      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'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /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
                  - 'null'
                action_complete_redirect_url:
                  type:
                  - string
                  - 'null'
                oidc_login_hint:
                  type:
                  - string
                  - 'null'
                  description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
                oidc_prompt:
                  type:
                  - string
                  - 'null'
                  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.
      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'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /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:
                  type:
                  - string
                  - 'null'
                  description: The verification code
                signature:
                  type:
                  - string
                  - 'null'
                  description: The verification web3 signature
                token:
                  type:
                  - string
                  - 'null'
                  description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
      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'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
components:
  schemas:
    SignUpVerification:
      type:
      - object
      - 'null'
      additionalProperties: true
      properties:
        next_action:
          type: string
          enum:
          - needs_prepare
          - needs_attempt
          - ''
        supported_strategies:
          type: array
          items:
            type: string
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    SignUpVerifications:
      type: object
      additionalProperties: false
      properties:
        email_address:
          $ref: '#/components/schemas/SignUpVerification'
        phone_number:
          $ref: '#/components/schemas/SignUpVerification'
        web3_wallet:
          $ref: '#/components/schemas/SignUpVerification'
        external_account:
          type:
          - object
          - 'null'
      required:
      - email_address
      - phone_number
      - web3_wallet
      - external_account
    SignUp:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - sign_up_attempt
        id:
          type: string
        status:
          type: string
          enum:
          - missing_requirements
          - complete
          - abandoned
        required_fields:
          type: array
          items:
            type: string
        optional_fields:
          type: array
          items:
            type: string
        missing_fields:
          type: array
          items:
            type: string
        unverified_fields:
          type: array
          items:
            type: string
        verifications:
          $ref: '#/components/schemas/SignUpVerifications'
        username:
          type:
          - string
          - 'null'
        email_address:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        web3_wallet:
          type:
          - string
          - 'null'
        password_enabled:
          type: boolean
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        unsafe_metadata:
          type: object
          additionalProperties: true
        public_metadata:
          type: object
          additionalProperties: true
        custom_action:
          type: boolean
        external_id:
          type:
          - string
          - 'null'
        created_session_id:
          type:
          - string
          - 'null'
        created_user_id:
          type:
          - string
          - 'null'
        abandon_at:
          type: integer
          format: int64
          description: 'Unix timestamp at which the user abandoned the sign up attempt.

            '
          example: 1700690400000
        legal_accepted_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp at which the user accepted the legal requirements.

            '
          example: 1700690400000
        locale:
          type:
          - string
          - 'null'
          description: The user locale preference for the sign-up specified as a BCP-47 language tag.
          example: en-US
        external_account:
          type: object
          deprecated: true
      required:
      - object
      - id
      - status
      - required_fields
      - optional_fields
      - missing_fields
      - unverified_fields
      - verifications
      - username
      - email_address
      - phone_number
      - web3_wallet
      - password_enabled
      - first_name
      - last_name
      - custom_action
      - external_id
      - created_session_id
      - created_user_id
      - abandon_at
      - legal_accepted_at
    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:
          type:
          - string
          - 'null'
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type:
            - object
            - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Link:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_email_link
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - email_link
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        verified_at_client:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Client.Passkey:
      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:
          - passkey
        name:
          type: string
        last_used_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp of when the passkey was last used.

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

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

            '
      required:
      - id
      - object
      - name
      - verification
    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
          - 'null'
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.BackupCode:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_backup_code
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - backup_code
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.FromOauth:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_from_oauth
        status:
          type: string
          enum:
          - verified
          - unverified
        strategy:
          type: string
          enum:
          - from_oauth_apple
          - from_oauth_google
          - from_oauth_mock
          - from_oauth_custom_mock
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      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.Admin:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_admin
        status:
          type: string
          enum:
          - verified
          - unverified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - admin
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    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
          - 'null'
          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
    ExternalAccountWithVerification:
      type: object
      additionalProperties: true
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - external_account
          - facebook_account
          - google_account
        id:
          type: string
        provider:
          type: string
        identification_id:
          type: string
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
        approved_scopes:
          type: string
        email_address:
          type: string
        email_address_verified:
          type:
          - boolean
          - 'null'
          description: 'Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified

            '
        first_name:
          type: string
        last_name:
          type: string
        avatar_url:
          type: string
          deprecated: true
          description: Please use `image_url` instead
        image_url:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        public_metadata:
          type: object
          additionalProperties: true
      

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