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

> ## Agent Instructions
> Document only operations in the linked OpenAPI contract: the source-data ingestion operations and the source-scoped outbound webhook management operations.
> Treat the generated OpenAPI document as authoritative for request fields. Never invent compatibility fields, alternate endpoints, or additional source models.
> Preserve explicit nulls, decimal strings, timestamps, source identifiers, immutable version identifiers, and document-version links exactly as defined.

# KYB dossiers

> Submit one complete business dossier and queue its KYB evaluation.

`POST /api/ingestion/kyb-dossiers` records the exact source snapshot used for one KYB
evaluation. The Customer must already exist as a `BUSINESS`, and the request pins an immutable
`customerVersionId` rather than silently using whatever Customer data is current later.

The endpoint accepts the dossier, validates its references, creates one durable Case immediately,
and queues the internal evaluation. The Case is the customer work record; its WorkflowRun and
AssessmentRun are subordinate execution and evidence records.

## Before submitting

1. Create the business with `POST /api/ingestion/customers`.
2. Upload every supporting document with a `sourceExternalId` and wait until each document version
   is `AVAILABLE`; unbound documents cannot enter a KYB dossier.
3. Build one complete snapshot containing related parties, their relationships, document roles,
   and provider evidence.
4. Use an API credential with `karsa:ingestion:kyb` and a stable `Idempotency-Key`.

If you also need to create every beneficial owner as an individual Customer, use
`POST /api/ingestion/business-onboardings` instead. That atomic convenience operation creates the
business Customer, each beneficial-owner Customer, their relationships, and this dossier together.

Use the generated **API Reference** for the complete schema. Important rules include:

* `customerVersionId` must belong to a business owned by the authenticated source.
* Every related party must participate in at least one ownership or role relationship.
* Relationship, party, document-version, and provider-record identifiers must be unique inside the
  dossier.
* A person may own or hold a role. A business may own another business, but may not directly own
  itself.
* Every referenced document version must be declared in `documents`, belong to the same source,
  and be available before processing can complete.
* The business and document facts must be effective no later than `sourceEffectiveAt`. They may be
  observed and recorded later, provided they were available when Karsa admitted the dossier.
* Provider observations may not be newer than the complete source snapshot.
* Provider authority comes from the authenticated ingestion source. An unbound source is rejected
  before a dossier is created.

## Null and empty collections

The Customer contract uses explicit `null` for a fact the source does not have. A KYB dossier uses
an empty array when that complete snapshot contains no items of a collection, such as no related
parties or no provider evidence. Do not omit required keys and do not invent placeholder facts.

## Safe retries and source versions

Reuse the same `Idempotency-Key` and exact body after an ambiguous network result. A changed body
needs a new key and a new `sourceVersion`.

The pair of source and `sourceVersion` identifies the imported dossier. Reusing it with the same
content returns the existing dossier, Case, and workflow run. Reusing it for different content
returns `409 KYB_SOURCE_VERSION_CONFLICT`.

The accepted response contains:

* `dossierId`: the immutable Karsa dossier;
* `customerVersionId`: the exact business snapshot being evaluated;
* `workflowRunId`: the queued or existing workflow run;
* `caseId`: the durable customer work record created for this dossier;
* `evaluationStatus`: `QUEUED` or `EXISTING`; and
* `statusUrl`: the analyst-authenticated Case detail endpoint at `/api/cases/{caseId}`.

The machine submission itself is complete once the dossier, Case, and queue job exist. `statusUrl`
is for an authenticated Karsa analyst session, not the source bearer credential. The Case begins in
`PROCESSING` and remains the permanent record through evaluation and review.

## What the workflow does

The worker admits the Customer, related-party, relationship, document, and supported provider
facts into one frozen evidence snapshot. It then runs exactly eight checks:

1. legal entity;
2. operating address;
3. ownership and control;
4. person verification;
5. business activity;
6. funds and expected use;
7. screening; and
8. regulatory authorization.

Customer policy decides which checks are required and their bounded thresholds. Provider mappings
remain separate from policy. Missing evidence and unavailable provider capability are reported as
different limitations, and neither is silently treated as a pass.

When evaluation finishes, the Case becomes `COMPLETED` if all eight stored checks have no unresolved
problems, or `NEEDS_REVIEW` if any problem remains or execution is blocked. A terminal execution
failure makes it `FAILED`; retryable failures leave it `PROCESSING`. Eve receives only the bounded
capability packets Karsa commissions from the frozen evidence snapshot. It may return cited
observations and limitations, but Karsa retains deterministic checks, persistence, audit, and human
decision authority.


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