How records fit together

Karsa separates the identity of a record from the history of what your system reported about it. The first upload creates a stable resource and its first immutable version. Sending changed data with the same externalId appends another version to that resource.

API resource	Stable root	Immutable data	Example relationship
Document	`Document`	`DocumentVersion`	A KYB dossier links exact DocumentVersion IDs
Customer	`Customer`	`CustomerVersion`	Subject referenced by the transaction and both outcomes
Account	`Account`	`AccountVersion`	`customerId` references the Customer root
Transaction	`Transaction`	`TransactionVersion`	`receiverCustomerId` references the Customer root
Outcome	`Outcome`	`OutcomeVersion`	`customerId` references exactly one subject
Screening	n/a	`ScreeningObservation`	Exactly one primary Customer, Account, or Transaction
Disposition	n/a	`ScreeningDispositionEvent`	References one source-owned screening observation

Identifiers returned by every upload

{
  "outcome": "CREATED",
  "resourceId": "customer_resource_example_01",
  "versionId": "customer_version_example_01",
  "currentVersionId": "customer_version_example_01"
}

resourceId is the stable Karsa identifier for the record. Use it when another record refers to this customer, account, transaction, document, or outcome.
versionId identifies the immutable snapshot written by this request.
currentVersionId identifies the latest version after the write.
outcome is CREATED, VERSION_CREATED, or UNCHANGED.

Relationship rules

A KYB dossier, account, or transaction links a document by its immutable Document versionId.
An account links to its verified owner with the Customer resourceId returned by the customer upload. Do not set customerId merely because a customer used or funded an external account.
A transaction identifies known parties with Customer or Account resourceId values.
An outcome belongs to exactly one Customer, Account, Transaction, or Document resourceId.
Missing source values remain null; do not manufacture a counterparty or amount.
A KYB dossier pins one business Customer versionId; it never follows the mutable current pointer.

Declare source completeness

After your source has delivered every record in a supported dataset for a bounded range, record a source checkpoint with POST /api/ingestion/source-checkpoints. Supported datasets are CUSTOMERS, KYB_DOSSIERS, ACCOUNTS, TRANSACTIONS, DOCUMENTS, OUTCOMES, SCREENING_OBSERVATIONS, and SCREENING_DISPOSITIONS. The checkpoint is an append-only attestation from the authenticated source; Karsa does not infer completeness from the records it happened to receive.

{
  "dataset": "TRANSACTIONS",
  "completeFrom": "2026-07-01T00:00:00Z",
  "completeThrough": "2026-08-21T12:00:00Z"
}

completeFrom is the earliest complete instant; use null only when the attestation covers the source’s full retained history. completeThrough is the exclusive upper bound. Checkpoints cannot move backwards. Monitoring routines resolve the latest checkpoint known at their frozen evidence cutoff and cite it alongside the source versions used by the calculation. A missing, stale, or too- narrow checkpoint makes coverage-dependent results inconclusive rather than clear.

The API Reference is generated from the validation contract enforced by the running API. Use it for the exact required fields, nullability, limits, examples, responses, and problem codes.

Customers: individuals and businesses
Accounts: customer-linked bank or payment accounts
Documents: uploaded files and immutable content
Transactions: movements of value
Outcomes: source-reported results
KYB dossiers: one immutable business evaluation input

Platform overview

Customer data

Financial data

Evidence

Results

Events

Identifiers returned by every upload

Relationship rules

Declare source completeness

​Identifiers returned by every upload

​Relationship rules

​Declare source completeness

​Related

Identifiers returned by every upload

Relationship rules

Declare source completeness

Related