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

# Create a KYB case

> Creates a KYB case for a merchant identified by external_id. The backend owns the business applicant: it creates an empty Organization applicant bound to external_id (or reuses the existing one). If that applicant already has a `draft` case, that case is returned with 200 instead of creating a new one; a case mid-remediation is NOT reused, because an officer is waiting on it. Optional `fields` prefills the widget form values grouped by section, e.g. {"business": {"legal_name": "..."}}; keys must match the catalog (GET widget), unknown keys are ignored. Tenant (org + sandbox) comes from the caller's auth. Returns the public_id the customer embeds in the widget flow.



## OpenAPI

````yaml https://api.dataspike.io/openapi/kyb/public.json post /api/v4/kyb/cases
openapi: 3.1.0
info:
  description: Know Your Business (KYB) — case creation and the embedded onboarding widget.
  title: Dataspike KYB API
  version: '1.0'
servers: []
security: []
paths:
  /api/v4/kyb/cases:
    post:
      tags:
        - KYB Cases
      summary: Create a KYB case
      description: >-
        Creates a KYB case for a merchant identified by external_id. The backend
        owns the business applicant: it creates an empty Organization applicant
        bound to external_id (or reuses the existing one). If that applicant
        already has a `draft` case, that case is returned with 200 instead of
        creating a new one; a case mid-remediation is NOT reused, because an
        officer is waiting on it. Optional `fields` prefills the widget form
        values grouped by section, e.g. {"business": {"legal_name": "..."}};
        keys must match the catalog (GET widget), unknown keys are ignored.
        Tenant (org + sandbox) comes from the caller's auth. Returns the
        public_id the customer embeds in the widget flow.
      operationId: POST_/api/v4/kyb/cases
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCaseRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateCaseRequest'
        description: Request body for kyb.CreateCaseRequest
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
          description: Existing in-flight case reused for this external_id.
        '201':
          content:
            application/json:
              schema:
                $ref: d5293a33-1d10-4aa2-8ff9-4a2c9a2d1e19
            application/xml:
              schema:
                $ref: d5293a33-1d10-4aa2-8ff9-4a2c9a2d1e19
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrExternalIDRequired'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrExternalIDRequired'
          description: external_id is required or the body is invalid.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
          description: KYB case created.
      security:
        - ApiKey: []
components:
  schemas:
    CreateCaseRequest:
      description: CreateCaseRequest schema
      properties:
        external_id:
          example: bolt-merchant-123
          type: string
        fields:
          additionalProperties:
            additionalProperties:
              nullable: true
            nullable: true
            type: object
          nullable: true
          type: object
      type: object
    CreateCaseResponse:
      description: CreateCaseResponse schema
      example:
        id: 019f179b-0fa7-72c8-818e-819652540477
        public_id: KYBC8274B9CF4907859
        applicant_id: 019f1383-8f38-7d31-b921-39310a19b444
        external_id: bolt-merchant-123
        status: draft
      properties:
        applicant_id:
          example: 0195c1f0-1234-7000-8000-0123456789ab
          type: string
        external_id:
          example: bolt-merchant-123
          type: string
        id:
          example: 0195c1f0-1234-7000-8000-0123456789ab
          type: string
        public_id:
          example: KYB0123456789abcdef
          type: string
        status:
          example: draft
          type: string
      type: object
    ErrExternalIDRequired:
      description: ErrExternalIDRequired schema
      example:
        code: external_id_required
        message: external_id is required
      properties:
        code:
          example: email_otp_expired
          type: string
        message:
          example: OTP has expired
          type: string
        param:
          nullable: true
          type: string
      type: object
  securitySchemes:
    ApiKey:
      description: API token passed in the request header.
      in: header
      name: ds-api-token
      type: apiKey

````