Cases, lists & AML reports

Cases

A decision that needs a person opens a case. Its lifecycle is open → investigating → pending_decision → closed; it may close early from open or investigating, and go back from pending_decision to investigating. Closing needs a final verdict: confirmed, false_positive or inconclusive. A closed case changes only after it is reopened with a reason. Every change — status, verdict, assignee, tags, notes — is kept in an append-only history.

curl -X PATCH https://api.verifex.dev/v1/risk/cases/CASE_ID \
  -H "Authorization: Bearer vfx_your_api_key" -H "Content-Type: application/json" \
  -d '{ "status": "closed", "final_verdict": "false_positive",
        "note": "Salary payment; employer confirmed." }'

On the compatible API the SanctionScanner status (0–9) and match status (1–7) are mapped onto this lifecycle (for example 2 Escalated → investigating, 4 FalsePositive → false_positive). Each case has a deadline from your SLA hours (Settings).

Black and white lists

• Blacklist (customer, account, identity document, IP, device): a hit always blocks.
• Whitelist: lowers a behaviour-driven outcome one step. It never overrides sanctions, PEP, a hard override or a blacklist hit, and vouches only for your own customer's side of a transfer — never for the counterparty.
• Every entry needs a reason; removal is recorded, never erased. Values are stored as keyed digests; only a masked reference is shown back.

AML scenarios S1–S4

Four monthly scenarios (rules AML_01…AML_04) count per sender (identity document) and per beneficiary (IBAN or account number), by calendar month in your time zone. Each fires once per subject per month. S1 needs the sender's daily limit: optionalParameters.dailyLimit or the registered account's dailyTransferLimit — when both are known the lower one applies. Refunds, cancellations and declined transfers are not counted; transfers Shield blocked are.

Monthly reports

One row per sender (S1–S3) or beneficiary (S4) that fired in the month, in JSON, CSV or XLSX, with the rule version and thresholds that fired each row. At month end the four reports are snapshotted and behaviour.report_ready is sent; a closed month no longer moves, and transactions that arrive within the grace days are listed as late additions.

curl "https://api.verifex.dev/v1/risk/reports/behaviour?scenario=S1&month=2026-09&format=xlsx" \
  -H "Authorization: Bearer vfx_your_api_key" -o shield-S1-2026-09.xlsx

Webhooks

Subscribe an endpoint with POST /v1/webhooks (or change one with PATCH /v1/webhooks/{id}). Deliveries are signed (X-Verifex-Signature). Webhooks are hints: re-read the transaction before acting. The delivery log is GET /v1/webhooks/deliveries?events=….