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

# Get a KYB verification

> Returns the full detail for one KYB verification: the widget-collected `application` data, the flat `checks` list (registry, TIN, document verification, doc-manipulation per file, AML per person, company AML, cross-check, KYC, business risk score, agentic verification), and the `documents` and `persons` grouping slices.

The `risk` block and the top-level `decision` field are reserved for the KYB risk scoring service and are `null` until it runs — the risk-driven outcome currently surfaces in `status` (`approved` / `manual_review` / `rejected`).

The path id is the KYB case id (the `id` returned by the list). The organization scope is taken from the API key.




## OpenAPI

````yaml /api-reference/dataspike_openapi.yaml get /api/v4/kyb/verifications/{verification_id}
openapi: 3.1.0
info:
  title: Dataspike API
  description: >
    # Introduction


    Welcome to the Dataspike API! You can use our API to access AML and Docver
    API endpoints.


    **Production API endpoint**: [api.dataspike.io](https://api.dataspike.io)


    **Sandbox API endpoint**:
    [sandboxapi.dataspike.io](https://sandboxapi.dataspike.io)


    All API requests must contain header `Content-Type: application/json`


    For both endpoints API Key is required and can be generated at
    [dash.dataspike.io](https://dash.dataspike.io/api) Developer section


    You have to include API Key in each request using `ds-api-token` Header name
  version: v3
servers:
  - url: https://api.dataspike.io
    description: Production
  - url: https://sandboxapi.dataspike.io
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: AML Screening
    description: >
      ### PEP & Sanctions Screening API


      **Key Features:**


      1. **Real-time Screening**: Perform instant screenings against constantly
      updated PEP and sanctions databases, ensuring you have the most current
      information at your fingertips.


      2. **Customizable Workflow**: Tailor the screening process to your
      specific needs, setting up thresholds and alerts that suit your risk
      appetite.


      3. **Easy Integration**: Our API is designed with simplicity in mind,
      making integration into your applications a seamless experience.


      4. **Data Security**: We prioritize data security and compliance,
      implementing industry-leading measures to protect your sensitive
      information.
  - name: Applicants
    description: >
      ### Applicant API


      The Applicant API provides a powerful and flexible solution for creating
      new applicants, conducting AML (Anti-Money Laundering) checks, performing
      document verifications, and enabling customizable applicant monitoring
      settings. This API is designed to seamlessly integrate with your existing
      systems, allowing you to efficiently manage applicant data and compliance
      processes.


      **Key Features:**


      1. **Create New Applicants**: The Applicant API enables you to
      programmatically create new applicant profiles by providing essential
      details such as name or identification data.

      2. **AML Checks**: Efficiently conduct Anti-Money Laundering checks on
      applicants to ensure compliance with regulatory requirements and prevent
      fraudulent activities. The API leverages industry-leading AML databases to
      screen applicants against sanctions lists and other watchlists.

      3. **Customizable Monitoring Settings**: With the Applicant API, you have
      the freedom to tailor applicant monitoring settings according to your
      specific compliance needs. You can configure the frequency of screening
      applicants against sanctions lists, enabling you to stay up-to-date with
      any changes in their status.
  - name: Verifications
    description: >
      ### Verification API


      The Document Verification API offers a cutting-edge and secure solution
      for verifying the authenticity and validity of identity documents
      submitted by applicants within application or platform. This powerful API
      leverages advanced document recognition and verification technologies to
      streamline the verification process and improve overall user onboarding
      experience.


      **Key Features:**


      1. **Identity Document Validation**: The API supports various types of
      identity documents, such as passports, driver's licenses and more. It
      automatically extracts relevant information from these documents, ensuring
      seamless and reliable validation.

      2. **Biometric Verification**: For added security and fraud prevention,
      the API can perform biometric verification by comparing the photo on the
      identity document with a selfie or live photo provided by the applicant.

      3. **Real-Time Verification Results**: Verification results are provided
      in real-time, enabling swift decision-making in onboarding processes and
      other critical operations.
  - name: Verification profiles
    description: >
      ### Verification profiles API


      Verification profiles is designed to configure verification flow.


      **Key Features:**


      1. Setup which documents, countries are valid for verification.

      2. Enable or disable required checks for verification. For example
      disable/enable cross check verification.

      3. Any other custom settings. Please contact us to negotiate required
      custom behaviour.
  - name: File management
    description: >
      ### File Management API


      File Management API combines essential file management functionalities,
      including file upload, preview, and download, to facilitate efficient and
      secure handling of documents submitted for verification purposes.


      **Key Features:**


      1. **File Upload**: The API enables seamless file upload, allowing
      end-users to submit various types of documents, such as passports,
      driver's licenses, identity cards, and other relevant identification
      papers.

      2. **File Preview**: This functionality assists users in verifying the
      accuracy of the uploaded documents before proceeding with the verification
      process.

      3. **File Download**: Upon successful verification or when needed this
      feature allows to retain a copy of submitted verified documents for future
      use.
  - name: Webhooks
    description: >
      ### Webhooks API


      The AML and Document Verification Webhooks API provide essential
      event-driven notifications to developers, enabling seamless integration
      with Dataspike system application's AML checks and document verification
      processes. By leveraging these Webhooks, developers can receive real-time
      updates about AML hits, document verification results, and other
      activities related to applicant screening.
  - name: SDK
    description: >
      ### SDK API

      By leveraging the SDK API, developers can accelerate development, simplify
      integration, and enhance the overall user experience.
  - name: Verification links
    description: >
      ### Verification links API


      Verification links is designed to configure easy verification flow without
      any development on self side.


      **Quick guide**


      Create verification link. All your applicants now is possible to pass
      verification via this link available at https://am.dataspike.io/$link_id.
      Results will be available via webhook.


      Verification link is embedded to verification profile. Only one link can
      be created for profile.
  - name: Bankbooks
    x-displayName: Bankbooks
    description: >
      ### Bankbooks API


      The Bankbooks API is a tool designed to streamline the extraction process
      of account names and numbers from bankbook images, catering to specific
      countries. With this API, developers and financial institutions can
      effortlessly retrieve essential financial information from scanned or
      photographed bankbooks.


      ### Recommendations


      1. **Filter Out-of-Domain (OOD) Images by Similarity Score**

      The API returns a maximum similarity score between the bankbook found in
      the uploaded image and the bankbook images in the database. A recommended
      threshold to filter out-of-domain (OOD) images, such as credit cards or
      unrelated documents, is 0.75-0.8. We recommend to only consider images
      with a similarity score equal to or higher than this threshold as valid
      bankbook images.

      2. **Consider Manual Checks When Detected a Scanned Document**

      The API provides a boolean flag where the True value indicates that the
      uploaded image is a scanned document or a screenshot. While this flag
      works well for distinguishing photos of physical bankbooks from the
      scanned documents, you should be aware that it may give false negatives
      for screenshots made not in the bank's mobile app. Therefore, it's
      recommended to exercise caution when interpreting this flag and consider
      additional validation steps if necessary.

      3. **Consider Approximate String Matching for Names in Thai Language**

      In Thai language some letters can be extremely similar to each other. For
      example, the letters "ข" (kho khai) and "ฃ" (kho khuat) may appear
      visually similar, so the OCR (optical character recognition) model can
      confuse them sometimes. To address this issue, it's recommended to use
      approximate string matching techniques when comparing the extracted
      account name and number from the bankbook with the reference data. This
      can help account for minor discrepancies or variations in the OCR output
      due to visual similarities in Thai characters.



      ### Requirements:

      * The bankbook in the uploaded image must occupy more than 40% of the
      total area

      * The text information on the bankbook must be clearly visible to
      accurately extract information from it



      ### Additional comments:

      **Handling of Rare Bankbook Designs**

      Some bankbook designs, such as those from TMB or UOB, were rare in our
      training dataset. Additionally, screenshots from mobile apps may change
      quite often. If we encounter any issues with detecting or extracting
      information from these rare designs, we will retrain our models. Our
      alerting system ensures that we are promptly notified of any issues that
      require attention.
  - name: Transmon
    x-displayName: Transaction monitoring API
    description: >
      ### What is Transaction Monitoring


      Transaction monitoring is a flexible and highly customizable system
      designed to check financial transactions (both payor to payee transfers
      and payments during checkout).


      The system based on rules, which you can set through API.


      Flexible custom rules can be used to:

      * Reject ineligible transactions, optionally causes can be provided

      * Flag suspicious transactions for further analysis


      For example, you can add rule for rejecting transaction if its sum three
      times more than average for last 30 days for this user. See examples with
      details below.


      ### How it works


      ![Transaction Monitoring
      Diagram](https://cdn.n37z.com/images/docs/kyt/70079905-dcbd-4510-a4de-0b4d57b7dbd0.png)


      1. Desired rules must be set through API

      2. Each received transaction or payment processed by Transaction
      Monitoring, your rules executed

      3. Result for each transaction/payment sent via Webhooks (see
      TransmonWebhookObject in [Webhooks schema](#tag/webhooks_payloads))


      In custom rules you can access:

      * all the data provided in
      [transaction](#tag/Transmon/operation/post-transmon-transaction)/[payment](#tag/Transmon/operation/post-transmon-payment)
      (amount, currency_code, checkout_price and so on)

      * some aggregated statistics (min/max/average and total sum, transactions
      count) for every applicant for last 1, 7 and 30 days


      ### Transaction Monitoring API


      Transaction Monitoring API combines:

      - essential rules management functionalities to
      create/edit/(de)activate/remove rules

      - endpoints for sending transaction/payment data to Transaction Monitoring


      ### Which data can be used

      Fields from original event data
      ([transaction](#tag/Transmon/operation/post-transmon-transaction)/[payment](#tag/Transmon/operation/post-transmon-payment))
      can be accessed by `event.<field_name>`, for example -
      `event.currency_code`.


      Aggregated statistics for applicant can be accessed in form
      `stats.<period>.<indicator>`.

      Allowed periods are:

      - `last1d` - last 1 day*

      - `last7d` - last 7 days*

      - `last30d` - last 30 days*.


      *"day" means calendar day from 00:00 UTC.


      So, `last1d` means aggregated statistic since today 00:00 UTC. `last7d` -
      includes today + additional 6 full calendar days before.


      Allowed indicators:

      - `sum` - total sum of all transactions and payments for period

      - `avg` - average sum of transaction/payment for period

      - `min` - minimal sum for period

      - `max` - maximal sum for period

      - `transactions_count` - count of all transactions (and payments) for
      period.


      For example, `stats.last30d.avg` - average amount of transaction/payment
      for last 30 days for current applicant.


      ### Rules expressions syntax and fields


      **Arithmetic operators**

      | Operator | Description | Example               |

      | -------- | ----------- | --------------------- |

      | `+`      | sum         | `event.amount + 100`  |

      | `-`      | difference  | `event.amount - 100`  |

      | `*`      | product     | `2 * event.amount`    |

      | `/`      | quotient    | `event.amount / 3`    |



      **Comparison operators**

      | Operator | Description      |
      Example                                     |

      | -------- | ---------------- |
      ------------------------------------------- |

      | `==`     | equal            | `event.amount ==
      100.45`                    |

      | `!=`     | not equal        | `event.amount !=
      0`                         |

      | `<`      | less             | `event.amount <
      0`                          |

      | `<=`     | less or equal    | `event.amount <=
      0`                         |

      | `>`      | greater          | `event.amount >
      0`                          |

      | `>=`     | greater or equal | `event.amount >=
      0`                         |



      **Logical operators**

      | Operator | Description     |
      Example                                       |

      | -------- | --------------- |
      --------------------------------------------- |

      | `&&`     | conditional AND | `event.amount > 100 && event.amount <
      200`    |

      | `\|\|`   | conditional OR  | `event.amount <= 0 \|\| event.amount >
      10000` |

      | `!`      | NOT             | `!(event.amount ==
      0)`                        |



      **Membership operators**

      | Operator | Description                                            |
      Example                                  |

      | -------- | ------------------------------------------------------ |
      ---------------------------------------- |

      | `in`     | checks that left operand exists in right operand array |
      `event.payee_country_cd in ["US", "UK"]` |



      ### Examples

      1. Check sum of transaction above 10000 or below or equal to zero

      ```

      event.amount > 10000 || event.amount <= 0

      ```

      2. Check currency is USD or EUR

      ```

      event.currency_code in ["USD", "EUR"]

      ```

      3. Check payee country is not US and not UK

      ```

      !(event.payee_country_cd in ["US", "UK"])

      ```

      4. Check if transactions sum 2.5 times more than average for last 30 days
      for this user.

      ```

      event.amount > 2.5 * stats.last30d.avg

      ```
  - name: Deepfake API
    x-displayName: Deepfake API
    description: >
      The **Deepfake API** is a powerful fraud-prevention tool that detects
      manipulated media across **images, documents, video, and audio**.  

      It is designed for high-stakes **identity verification** and **compliance
      workflows**, helping organizations stop deepfake-based fraud before it
      causes damage.  


      With advanced AI analysis, the API can:  

      - Verify the authenticity of **selfies and liveness checks**  

      - Detect tampering in **ID documents** such as passports or driver’s
      licenses  

      - Analyze **video calls and recordings** for synthetic face swaps or
      manipulations  

      - Identify **AI-generated or cloned voices** in audio files  


      **Why use the Deepfake API?**  

      - Reduce fraud losses from synthetic identities and impersonation  

      - Strengthen KYC/AML compliance and meet regulatory requirements  

      - Build user trust by securing digital onboarding and remote verification
      flows  

      - Integrate easily via a developer-friendly REST API  


      In short, the Deepfake API helps you protect your platform, your users,
      and your reputation against the rising threat of AI-generated media.  
  - name: search_request
    x-displayName: AML Search Request
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchRequest" />
  - name: search_response
    x-displayName: AML Search Response
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/SearchResponse" />
  - name: search_entity
    x-displayName: AML Entity Record
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/EntityRecord" />
  - name: applicant_person_request
    x-displayName: New Applicant Person Request
    description: >
      <SchemaDefinition
      schemaRef="#/components/schemas/CreatePersonApplicantRequest" />
  - name: applicant_org_request
    x-displayName: New Applicant Organization Request
    description: >
      <SchemaDefinition
      schemaRef="#/components/schemas/CreateOrganizationApplicantRequest" />
  - name: applicant_person_object
    x-displayName: Applicant Person Object
    description: >
      <SchemaDefinition schemaRef="#/components/schemas/ApplicantPersonResponse"
      />
  - name: applicant_org_object
    x-displayName: Applicant Organization Object
    description: >
      <SchemaDefinition
      schemaRef="#/components/schemas/ApplicantOrganizationResponse" />
  - name: verification_request
    x-displayName: New Verification Request
    description: >
      <SchemaDefinition
      schemaRef="#/components/schemas/CreateVerificationRequest" />
  - name: verification_object
    x-displayName: Verification Object
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/VerificationInfo" />
  - name: verification_error
    x-displayName: Verification Error codes
    description: >
      <SchemaDefinition schemaRef="#/components/schemas/VerificationErrorCode"
      />
  - name: webhooks_payloads
    x-displayName: AML & Docver & Transmon Webhook Payloads
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/WebhookObject" />
  - name: Non-Document Verification
    x-displayName: Non-Document Verification
    description: >
      ### Non-Document Verification API


      The Non-Document Verification API allows initiating specific identity
      checks that do not rely on traditional document uploads. This includes
      verifying national identifiers like Brazil's CPF, Nigeria's NIN, or
      Nigeria's BVN against authoritative sources.


      **Key Features:**


      1.  **Targeted Checks**: Perform specific verification types relevant to
      the applicant's country and the required check.

      2.  **Real-time Results**: Obtain verification status (verified or failed)
      along with data returned from the source system.

      3.  **Integration**: Seamlessly integrate these checks into your
      onboarding or compliance workflows for existing applicants.
  - name: KYB Verification
    description: >
      ### KYB (Know Your Business) Verification API


      The end-to-end KYB case flow: create a case for a merchant, collect its
      data through the hosted widget, then read the aggregated result.


      **Retrieving verifications:** list all KYB verifications for your
      organization (`GET /api/v4/kyb/verifications`) and fetch the full detail
      of one by id (`GET /api/v4/kyb/verifications/{verification_id}`).
  - name: KYB Single Checks
    description: >
      ### KYB Single Checks API


      Individual, standalone KYB checks you can run against an applicant without
      the full case flow. All are asynchronous — submit a request and poll `GET
      /api/v4/kyb/result/{request_id}` for the result.


      **Checks:**


      1. **Document Verification** — upload and verify corporate documents
      (incorporation, ownership, tax, bank, PCI) to extract and validate company
      information.

      2. **US Company Registry Check** — look up a company in a US Secretary of
      State registry by name or SOS ID.

      3. **TIN Verification** — check that a business name and TIN/EIN match IRS
      records.
paths:
  /api/v4/kyb/verifications/{verification_id}:
    get:
      tags:
        - KYB Verification
      summary: Get a KYB verification
      description: >
        Returns the full detail for one KYB verification: the widget-collected
        `application` data, the flat `checks` list (registry, TIN, document
        verification, doc-manipulation per file, AML per person, company AML,
        cross-check, KYC, business risk score, agentic verification), and the
        `documents` and `persons` grouping slices.


        The `risk` block and the top-level `decision` field are reserved for the
        KYB risk scoring service and are `null` until it runs — the risk-driven
        outcome currently surfaces in `status` (`approved` / `manual_review` /
        `rejected`).


        The path id is the KYB case id (the `id` returned by the list). The
        organization scope is taken from the API key.
      operationId: kyb-get-verification
      parameters:
        - name: verification_id
          in: path
          description: The KYB case id (the `id` from the list response).
          required: true
          schema:
            type: string
            format: uuid
            example: 019f179b-0fa7-72c8-818e-819652540477
      responses:
        '200':
          description: KYB verification detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KybVerificationDetail'
        '404':
          description: Verification not found
components:
  schemas:
    KybVerificationDetail:
      type: object
      description: Full drill-in for one KYB verification.
      properties:
        id:
          type: string
          format: uuid
          description: KYB case id (the URL key; the id from the list).
          example: 019f179b-0fa7-72c8-818e-819652540477
        verification_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Verification id created by the pipeline after submit; null before
            then.
        public_id:
          type: string
          example: KYBC8274B9CF4907859
        organization_id:
          type: string
          example: o6e501dc4d3c6d9a4
        applicant_id:
          type: string
          format: uuid
          example: 019f1383-8f38-7d31-b921-39310a19b444
        external_id:
          type: string
          nullable: true
          example: bolt-merchant-123
        company_name:
          type: string
          nullable: true
          example: Acme Holdings Inc.
        country:
          type: string
          nullable: true
          example: US
        status:
          type: string
          description: >
            KYB case status.

            - `draft` → `under_review` as the case moves from data collection
            into checks.

            - `action_required` — a remediation is open (the merchant must fix
            and resubmit something).

            - Once the checks are terminal the risk score sets the outcome:
            `approved` (Low) /
              `manual_review` (Medium) / `rejected` (High), or `failed` when the score could not be obtained.
            - `approved_manually` / `rejected_manually` — a reviewer's manual
            decision.
          enum:
            - draft
            - under_review
            - action_required
            - approved
            - manual_review
            - rejected
            - failed
            - approved_manually
            - rejected_manually
          example: under_review
        stage:
          type: string
          description: >
            Derived lifecycle stage. While the case is in progress:
            `collecting_data` →

            `running_checks` → `manual_review`; `action_required` when a
            remediation is open.

            Once the case is decided, `stage` mirrors the final `status`.
          enum:
            - collecting_data
            - running_checks
            - manual_review
            - action_required
            - approved
            - rejected
            - failed
            - approved_manually
            - rejected_manually
          example: manual_review
        decision:
          type: string
          nullable: true
          description: >
            Reserved for the KYB risk scoring service; currently always `null`.
            The risk-driven

            outcome is surfaced in `status` instead.
          example: null
        risk_level:
          type: string
          nullable: true
          description: >-
            KYB business risk level (Low/Medium/High); null until the risk-score
            check runs.
          example: High
        is_sandbox:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
        submitted_at:
          type: string
          format: date-time
          nullable: true
        company:
          $ref: '#/components/schemas/KybCompanySummary'
        form_progress:
          $ref: '#/components/schemas/KybFormProgress'
        checks_summary:
          $ref: '#/components/schemas/KybChecksSummary'
        application:
          type: object
          description: >
            The widget-collected state — the section catalog merged with stored
            values, owners and documents.

            Same shape as the widget state (`GET
            /api/v4/kyb/widget/{public_id}`).
          additionalProperties: true
        checks:
          type: array
          description: The single flat list of every check the pipeline ran.
          items:
            $ref: '#/components/schemas/KybCheckResult'
        documents:
          type: array
          description: >-
            Uploaded files grouped for the Documents section; each references
            its doc-manipulation check via `check_ref`.
          items:
            $ref: '#/components/schemas/KybDocumentEntry'
        persons:
          type: array
          description: >-
            The representative and beneficial owners grouped for the People
            section; each references its AML check via `aml_check_ref` (and the
            representative its KYC via `kyc_check_ref`).
          items:
            $ref: '#/components/schemas/KybPersonEntry'
        risk:
          $ref: '#/components/schemas/KybRiskResult'
    KybCompanySummary:
      type: object
      nullable: true
      description: >-
        Declared-company snapshot for the Company/Application cards, sourced
        from the widget field values.
      properties:
        legal_name:
          type: string
          example: Acme Holdings Inc.
        dba:
          type: string
          nullable: true
        form_type:
          type: string
          example: US - Limited Liability Company (LLC)
        entity_type:
          type: string
          example: Limited Liability Company (LLC)
        registration_type:
          type: string
          example: EIN
        registration_number:
          type: string
          example: 16-1782204
        country:
          type: string
          example: US
        state:
          type: string
          example: NY
        representative_name:
          type: string
          example: Joe Marrano
        representative_email:
          type: string
          example: joe@acme.com
    KybFormProgress:
      type: object
      nullable: true
      description: >-
        Widget-session completion stepper. Section completeness uses the same
        rules Submit enforces.
      properties:
        sections_completed:
          type: integer
          example: 4
        sections_total:
          type: integer
          example: 7
        current_section:
          type: string
          nullable: true
          description: The first incomplete section; null once submitted.
          example: volume_banking
        sections:
          type: array
          items:
            $ref: '#/components/schemas/KybSectionProgress'
    KybChecksSummary:
      type: object
      nullable: true
      description: >
        Aggregates the verification's checks for the expanded row. Counts are by
        check TYPE (a fan-out

        check such as AML-per-person counts as one). `completed` = `passed` +
        `review` + `failed` +

        `errored`. Null until the pipeline links a verification to the case.
      properties:
        expected:
          type: integer
          description: How many check types the verification plan runs.
          example: 7
        completed:
          type: integer
          description: How many types have all their instances done so far.
          example: 6
        passed:
          type: integer
          description: Completed types with a low-severity (clear) outcome.
          example: 4
        review:
          type: integer
          description: Completed types with a medium-severity outcome.
          example: 2
        failed:
          type: integer
          description: Completed types with a high-severity outcome.
          example: 0
        errored:
          type: integer
          description: >-
            Types whose check technically failed (provider unavailable / invalid
            input), counted apart from business outcomes.
          example: 0
        checks:
          type: array
          items:
            $ref: '#/components/schemas/KybCheckSummaryItem'
    KybCheckResult:
      type: object
      description: >-
        One check in the unified `checks` list. Every check type shares this
        shape; the type-specific payload lives in `response`.
      properties:
        id:
          type: string
          format: uuid
          description: Check id; referenced by `documents[]`/`persons[]`.
          example: 019f1a00-0000-7000-8000-000000000001
        type:
          type: string
          enum:
            - registry
            - tin
            - document_verification
            - doc_manipulation
            - aml_company
            - aml_person
            - cross_check
            - business_risk_score
            - agentic_verification
            - kyc
          example: registry
        subject_kind:
          type: string
          description: >-
            What the check ran against. `person` is the representative's KYC
            check.
          enum:
            - company
            - document
            - owner
            - person
          example: company
        subject_ref:
          type: string
          nullable: true
          description: >-
            document_id (doc-manipulation), owner id (AML per person) or the
            representative key (KYC); empty for company-level checks.
        status:
          type: string
          description: >
            `pending` (planned, not started) / `in_progress` (fan-out partly
            done) / `completed` /

            `error` (technical or provider failure — see `errors`).
          enum:
            - pending
            - in_progress
            - completed
            - error
          example: completed
        severity:
          type: string
          nullable: true
          description: Normalized outcome severity; present only when `completed`.
          enum:
            - low
            - medium
            - high
          example: low
        verdict:
          type: string
          nullable: true
          description: >
            Normalized lower_snake verdict, present only when `completed` (e.g.
            `active`, `match`,

            `authentic`, `verified`, `no_hits`, `confirmed_hit`).
            `business_risk_score` carries no

            verdict — its level is in `severity`.
          example: active
        response:
          description: >-
            Raw provider payload, passed through as-is. Present only when
            `status` is `completed`; omitted for `error` checks.
          nullable: true
        errors:
          type: array
          description: >-
            Customer-safe failure entries; present only when `status` is
            `error`.
          items:
            $ref: '#/components/schemas/KybCheckError'
        completed_at:
          type: string
          format: date-time
          nullable: true
    KybDocumentEntry:
      type: object
      description: One uploaded file for the Documents section.
      properties:
        document_id:
          type: string
          format: uuid
          example: 019c9c39-0b8a-7aa4-a5c0-abc123def456
        document_type:
          type: string
          example: Certificate of Registration / Incorporation
        file_name:
          type: string
          example: cert_of_inc.pdf
        owner_id:
          type: string
          nullable: true
          description: Set when the file is a person's government ID.
        check_ref:
          type: string
          format: uuid
          nullable: true
          description: >-
            The id of this file's doc-manipulation check in `checks`; null if
            none ran.
          example: 019f1a00-0000-7000-8000-000000000004
    KybPersonEntry:
      type: object
      description: The representative or one beneficial owner for the People section.
      properties:
        owner_id:
          type: string
          format: uuid
          example: 019f1383-8f38-7d31-b921-39310a19b444
        full_name:
          type: string
          example: John Doe
        role:
          type: string
          enum:
            - representative
            - beneficial_owner
          example: beneficial_owner
        citizenship:
          type: string
          nullable: true
          example: US
        ownership_pct:
          type: number
          format: double
          nullable: true
          example: 60
        aml_check_ref:
          type: string
          format: uuid
          nullable: true
          description: The id of this person's AML check in `checks`.
          example: 019f1a00-0000-7000-8000-000000000007
        id_check_ref:
          type: string
          format: uuid
          nullable: true
          description: >-
            The id of this person's government-ID doc-manipulation check, if
            any.
        kyc_status:
          type: string
          nullable: true
          description: >-
            Collapsed identity-verification state (representative only today;
            owners join later). Absent for non-KYC persons.
          enum:
            - not_started
            - pending
            - passed
            - failed
          example: passed
        kyc_verification_status:
          type: string
          description: >-
            Raw docver verification status behind `kyc_status` (verified,
            in_progress, pending, canceled, expired, …). Empty until a
            verification exists.
          example: verified
        kyc_check_ref:
          type: string
          format: uuid
          description: >-
            The id of this person's `kyc` check in `checks`; equals the KYC
            verification id, so it also deep-links the verification. Empty until
            a verification exists.
          example: 0195c1f0-1234-7000-8000-0123456789ab
    KybRiskResult:
      type: object
      nullable: true
      description: >-
        Final risk scoring outcome. Provided by the KYB risk scoring service;
        null until then.
      properties:
        score:
          type: integer
          example: 42
        level:
          type: string
          example: medium
        decision:
          type: string
          example: manual_review
        state:
          type: string
          enum:
            - not_calculated
            - preliminary
            - in_progress
            - final
            - manual_override
          example: final
        rules_triggered:
          type: array
          items:
            type: string
        calculated_at:
          type: string
          format: date-time
          nullable: true
    KybSectionProgress:
      type: object
      description: One widget section in the stepper.
      properties:
        key:
          type: string
          example: volume_banking
        title:
          type: string
          example: Volumes & banking
        state:
          type: string
          enum:
            - completed
            - current
            - pending
            - action_required
          example: current
    KybCheckSummaryItem:
      type: object
      description: One check type in the Checks & screening card (the badge-level view).
      properties:
        type:
          type: string
          enum:
            - registry
            - tin
            - document_verification
            - doc_manipulation
            - aml_company
            - aml_person
            - cross_check
            - business_risk_score
            - agentic_verification
            - kyc
          example: registry
        status:
          type: string
          description: >
            `pending` (no instance done yet) / `in_progress` (some, not all
            instances done) /

            `completed` / `error` (technical/provider failure).
          enum:
            - pending
            - in_progress
            - completed
            - error
          example: completed
        severity:
          type: string
          description: >-
            Normalized outcome severity (worst-of across instances); empty while
            pending/in_progress or on error.
          enum:
            - low
            - medium
            - high
          example: low
        verdict:
          type: string
          description: >
            Normalized lower_snake verdict, worst-of across instances (e.g.
            `active`, `match`,

            `authentic`, `no_hits`). Empty while pending/in_progress or on
            error.
          example: active
        completed_at:
          type: string
          format: date-time
          nullable: true
        instances:
          $ref: '#/components/schemas/KybCheckInstances'
    KybCheckError:
      type: object
      properties:
        code:
          type: string
          enum:
            - invalid_input
            - check_unavailable
          example: check_unavailable
        message:
          type: string
          example: Verification is temporarily unavailable, please try again later
    KybCheckInstances:
      type: object
      nullable: true
      description: >-
        Per-check fan-out progress (AML runs once per owner+representative,
        doc-manipulation once per file). Omitted for single-instance checks.
      properties:
        expected:
          type: integer
          example: 8
        completed:
          type: integer
          example: 3
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: ds-api-token

````