Skip to main content
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.