> ## 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.

# Start / retry a person's KYC

> Creates a fresh KYC verification for the addressed person (personId, taken from the persons[] list in GET state — today the case representative) and points the case at it as the current attempt. Returns verification_url_id, which the widget renders as a QR/link for that person to complete KYC on mobile, plus the initial status to poll. Calling again while pending/passed returns the existing verification (200); after a failed/expired one it mints a new verification (201) — this is the "Try again" action. Uses the organization's default verification profile, unless an optional profile_id is sent in the body to override it (temporary). Authenticated solely by the public_id in the path.



## OpenAPI

````yaml https://api.dataspike.io/openapi/kyb/public.json post /api/v4/kyb/widget/{publicId}/persons/{personId}/kyc
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/widget/{publicId}/persons/{personId}/kyc:
    post:
      tags:
        - KYB Widget
      summary: Start / retry a person's KYC
      description: >-
        Creates a fresh KYC verification for the addressed person (personId,
        taken from the persons[] list in GET state — today the case
        representative) and points the case at it as the current attempt.
        Returns verification_url_id, which the widget renders as a QR/link for
        that person to complete KYC on mobile, plus the initial status to poll.
        Calling again while pending/passed returns the existing verification
        (200); after a failed/expired one it mints a new verification (201) —
        this is the "Try again" action. Uses the organization's default
        verification profile, unless an optional profile_id is sent in the body
        to override it (temporary). Authenticated solely by the public_id in the
        path.
      operationId: POST_/api/v4/kyb/widget/:publicId/persons/:personId/kyc
      parameters:
        - description: KYB case public id.
          in: path
          name: publicId
          required: true
          schema:
            type: string
        - description: KYC subject id (PersonKyc.person_id from GET state).
          in: path
          name: personId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonKycRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PersonKycRequest'
        description: Request body for kyb.PersonKycRequest
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonKyc'
            application/xml:
              schema:
                $ref: '#/components/schemas/PersonKyc'
          description: Existing KYC verification returned (already pending/passed).
        '201':
          content:
            application/json:
              schema:
                $ref: d5293a33-1d10-4aa2-8ff9-4a2c9a2d1e19
            application/xml:
              schema:
                $ref: d5293a33-1d10-4aa2-8ff9-4a2c9a2d1e19
          description: Created
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrCaseNotFound'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrCaseNotFound'
          description: Case or person not found (case_not_found / person_not_found).
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrCaseLocked'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrCaseLocked'
          description: >-
            Case is locked, or has no KYC subject (case_locked /
            no_kyc_subject).
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonKyc'
            application/xml:
              schema:
                $ref: '#/components/schemas/PersonKyc'
          description: Fresh KYC verification created.
components:
  schemas:
    PersonKycRequest:
      description: PersonKycRequest schema
      properties:
        profile_id:
          example: 0195c1f0-1234-7000-8000-0123456789ab
          nullable: true
          type: string
      type: object
    PersonKyc:
      description: PersonKyc schema
      properties:
        completed_at:
          format: date-time
          nullable: true
          type: string
        name:
          example: John Smith
          nullable: true
          type: string
        person_id:
          example: 0195c1f0-1234-7000-8000-0123456789ab
          type: string
        role:
          example: representative
          type: string
        status:
          example: not_started
          type: string
        verification_id:
          example: 0195c1f0-1234-7000-8000-0123456789ab
          nullable: true
          type: string
        verification_status:
          example: verified
          nullable: true
          type: string
        verification_url:
          example: https://verify.dataspike.io/vAbC0123456789
          nullable: true
          type: string
        verification_url_id:
          example: vAbC0123456789
          nullable: true
          type: string
      type: object
    ErrCaseNotFound:
      description: ErrCaseNotFound schema
      example:
        code: case_not_found
        message: Case not found
      properties:
        code:
          example: email_otp_expired
          type: string
        message:
          example: OTP has expired
          type: string
        param:
          nullable: true
          type: string
      type: object
    ErrCaseLocked:
      description: ErrCaseLocked schema
      example:
        code: case_locked
        message: Case is locked and cannot be modified
      properties:
        code:
          example: email_otp_expired
          type: string
        message:
          example: OTP has expired
          type: string
        param:
          nullable: true
          type: string
      type: object

````