Screening observations

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.

​

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.

​

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.