> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svrn.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a customer and start SVRN onboarding



## OpenAPI

````yaml /contracts/svrn-integration-api.json post /onboarding
openapi: 3.0.3
info:
  title: SVRN Sequential Client API
  version: '2026-04-27'
  description: >-
    OpenAPI spec generated from scripts/dux_requests and the current Lambda
    handlers. This reflects the real sequential client flow used by DUX and
    corrects the main mismatches in the published docs: POST /auth authenticates
    with X-Client-Id and X-Client-Secret headers, POST
    /onboarding/{customer_id}/create-bank-account is the active bank-account
    route, POST /due-diligence/init returns a due_diligence_id plus
    contracts_preview while upload URLs are requested separately via POST
    /due-diligence/{due_diligence_id}/uploads, and due diligence signature
    confirmation is not a client API step because it is performed by the signer
    through an emailed link outside the integrator flow.
servers:
  - url: https://api.sandbox.svrn.digital
    description: Sandbox
  - url: https://api.svrn.digital
    description: Production
security:
  - bearerAuth: []
tags:
  - name: 01 Authentication
    description: Bearer token issuance for client integrations.
  - name: 02 Onboarding
    description: >-
      Customer onboarding, listing, verification resumption, and artist PIX
      registration.
  - name: 03 Due Diligence
    description: >-
      Case creation, file upload URL issuance, offer publication, and status
      polling. Signature confirmation happens out-of-band through emailed links.
  - name: 04 Reconciliation
    description: >-
      Contract reconciliation initialization, file upload URL issuance, and
      settlement tracking.
paths:
  /onboarding:
    post:
      tags:
        - 02 Onboarding
      summary: Create a customer and start SVRN onboarding
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateIndividualCustomerRequest'
                - $ref: '#/components/schemas/CreateBusinessCustomerRequest'
      responses:
        '201':
          description: Customer created and onboarding started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCreatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/BadGateway'
components:
  schemas:
    CreateIndividualCustomerRequest:
      type: object
      required:
        - type
        - role
        - name
        - tax_id
        - birth_date
        - email
        - country
      properties:
        type:
          type: string
          enum:
            - INDIVIDUAL
        role:
          type: string
          enum:
            - ARTIST
            - LABEL
        name:
          type: string
        tax_id:
          type: string
        birth_date:
          type: string
          format: date
        email:
          type: string
          format: email
        country:
          type: string
          example: BRA
        metadata:
          $ref: '#/components/schemas/Metadata'
        idempotency_key:
          type: string
      example:
        type: INDIVIDUAL
        role: ARTIST
        name: Test Artist
        tax_id: 123.456.789-00
        birth_date: '1995-09-18'
        email: artist@example.com
        country: BRA
        metadata:
          segment: artist-manual-test
    CreateBusinessCustomerRequest:
      type: object
      required:
        - type
        - role
        - legal_name
        - tax_id
        - incorporation_date
        - email
        - country
      properties:
        type:
          type: string
          enum:
            - BUSINESS
        role:
          type: string
          enum:
            - ARTIST
            - LABEL
        legal_name:
          type: string
        tax_id:
          type: string
        incorporation_date:
          type: string
          format: date
        email:
          type: string
          format: email
        country:
          type: string
          example: BRA
        metadata:
          $ref: '#/components/schemas/Metadata'
        idempotency_key:
          type: string
      example:
        type: BUSINESS
        role: LABEL
        legal_name: Label LTDA
        tax_id: 12.345.678/0001-99
        incorporation_date: '2020-06-01'
        email: label@example.com
        country: BRA
        metadata:
          segment: label-manual-test
    CustomerCreatedResponse:
      type: object
      required:
        - customer_id
        - partner_id
        - lumx_customer_id
        - type
        - role
        - customer_name
        - email
        - kyc_status
      properties:
        customer_id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        lumx_customer_id:
          type: string
        type:
          type: string
        role:
          type: string
        customer_name:
          type: string
        email:
          type: string
          format: email
        kyc_status:
          type: string
        verification_link:
          type: string
        default_wallet:
          type: string
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/Wallet'
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/Requirement'
    Metadata:
      type: object
      additionalProperties: true
    Wallet:
      type: object
      properties:
        address:
          type: string
        blockchain:
          type: string
        default:
          type: boolean
        isDefault:
          type: boolean
        blockExplorerUrl:
          type: string
          format: uri
      additionalProperties: true
    Requirement:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
      example:
        error: MISSING_FIELD
        message: artist.customer_id is required
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The request conflicts with the current workflow state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadGateway:
      description: Upstream provider error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.