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

# Screening observations

> Upload provider results and reviewer dispositions without collapsing them into a Karsa decision.

Use screening observations to send Karsa the verification, fraud, AML, transaction-monitoring, and
blockchain-screening results that BlindPay receives from providers such as AiPrise, SEON, and
Chainalysis. For those three providers, use the provider-native routes below: BlindPay supplies the
Karsa subject binding and the untouched provider response, and Karsa owns transport normalization.
The generic endpoint remains available for other providers and already-normalized historical data.

| Provider | Endpoint |
| - | - |
| SEON | `POST /api/ingestion/screening-observations/seon` |
| AiPrise | `POST /api/ingestion/screening-observations/aiprise` |
| Chainalysis | `POST /api/ingestion/screening-observations/chainalysis` |

## What the two records mean

`POST /api/ingestion/screening-observations` records what a provider reported at a particular time.
The observation is immutable and has exactly one primary Customer, Account, or Transaction subject.
Additional implicated subjects may be included in `relatedSubjects`.

Each provider-native route writes that same immutable record after applying a versioned Karsa
adapter. Additive provider fields are retained in bounded `providerDetails.nativeResponse`; unknown
provider states normalize to `UNKNOWN`, not `CLEAR`. AiPrise related-person and related-company
objects are retained as evidence and are not automatically asserted as canonical Karsa links.

`POST /api/ingestion/screening-dispositions` records what a BlindPay reviewer or source system later
did with one observation. It is a separate immutable event tied to an observation uploaded by the
same authenticated source.

<Warning>
  A provider result is evidence, not a Karsa finding. Uploading `REVIEW`, `MATCH`, or an `OPEN`
  alert does not automatically decide its action class, queue, priority, or disposition. Routine 6
  applies the released policy and rule mapping separately.
</Warning>

## Preserve identity and provenance

* Use `externalId` as the stable BlindPay event identity for the authenticated source.
* On the generic endpoint, put the provider's alert, verification, transaction, or screening ID in
  `providerRecordId`. The native routes extract it when the provider response exposes it;
  Chainalysis requires it in the envelope because the exact contracted product schema varies.
* Supply `ruleVersion` when the provider exposes it; otherwise BlindPay may use an immutable
  configuration hash that it captured when the provider ran.
* Use `artifactHash` for the SHA-256 of retained canonical provider detail. Upload supporting
  evidence first and place its immutable Document version references in `documents`.
* Native routes retain the validated provider response in bounded `providerDetails`. Do not include
  credentials, biometric media, document binaries, or signed URLs.

For Routine 4.10, bind every applicable blockchain-screening result to the Account or Transaction
it screened. Include `providerProduct`, `providerApiVersion`, `providerRecordId`, and
`providerObservedAt`; a missing result, missing provenance, `UNKNOWN`, or `ERROR` remains
inconclusive. Chainalysis category, service, direct/indirect exposure, hop attribution, transaction
hash, direction, and other product-specific evidence may remain in the validated bounded native
response.

## Declare feed completeness

After all records for a bounded range have been delivered, submit a source checkpoint with
`dataset` equal to `SCREENING_OBSERVATIONS` or `SCREENING_DISPOSITIONS`. This lets Routine 6 tell the
difference between a complete feed with no alerts and a feed that may simply be missing records.
Use `completeFrom` for the earliest complete instant, or `null` only when the attestation covers the
source's full retained history, and `completeThrough` for the exclusive upper bound.

The checkpoint is your source's attestation. Karsa never infers completeness merely because it
received some observations.

## Result, recommendation, and disposition stay separate

1. `sourceStatus`, `normalizedResult`, and `alertLifecycle` describe the provider observation.
2. Routine 6 produces a cited recommendation only after the observation has enough policy and rule
   context.
3. `normalizedDisposition` describes BlindPay's later reviewer or source-system action.
4. A Karsa Finding disposition, if one exists, remains part of the Karsa Finding lifecycle.

This separation prevents a provider score or status from silently becoming an automated customer
decision.


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