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

# How records fit together

> Stable resources, immutable versions, and the KYB dossier that pins their evidence.

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

```json theme={null}
{
  "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

1. A KYB dossier, account, or transaction links a document by its immutable Document `versionId`.
2. 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.
3. A transaction identifies known parties with Customer or Account `resourceId` values.
4. An outcome belongs to exactly one Customer, Account, Transaction, or Document `resourceId`.
5. Missing source values remain `null`; do not manufacture a counterparty or amount.
6. 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.

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## Related

* [Customers](/concepts/customers): individuals and businesses
* [Accounts](/concepts/accounts): customer-linked bank or payment accounts
* [Documents](/concepts/documents): uploaded files and immutable content
* [Transactions](/concepts/transactions): movements of value
* [Outcomes](/concepts/outcomes): source-reported results
* [KYB dossiers](/guides/kyb-dossiers): one immutable business evaluation input


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