> ## 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 (dashboard)

> Dashboard-facing twin of POST /api/v4/kyb/cases: creates (or reuses the in-flight) KYB case for a merchant identified by external_id, returning the public_id to embed in the widget flow. Same body and behavior as the API-key endpoint; the only difference is tenancy — the organization comes from the path (the web session must belong to it) and sandbox from the request (Ds-Sandbox header / host), not from an API key.



## OpenAPI

````yaml https://api.dataspike.io/openapi/kyb/public.json post /webapi/v4/kyb/organization/{organizationId}/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:
  /webapi/v4/kyb/organization/{organizationId}/cases:
    post:
      tags:
        - KYB Cases
      summary: Create a KYB case (dashboard)
      description: >-
        Dashboard-facing twin of POST /api/v4/kyb/cases: creates (or reuses the
        in-flight) KYB case for a merchant identified by external_id, returning
        the public_id to embed in the widget flow. Same body and behavior as the
        API-key endpoint; the only difference is tenancy — the organization
        comes from the path (the web session must belong to it) and sandbox from
        the request (Ds-Sandbox header / host), not from an API key.
      operationId: POST_/webapi/v4/kyb/organization/:organizationId/cases
      parameters:
        - description: Organization id.
          in: path
          name: organizationId
          required: true
          schema:
            type: string
      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:
        - Session: []
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:
    Session:
      description: Session cookie for web dashboard authentication.
      in: cookie
      name: ds-prod-session
      type: apiKey

````