Before you begin
You need a verification with a screening hit on one of its individuals. See Verification for creating one and reading the result.
The decision is written to the screening service, which stays the source of truth. Admiin does not record a final local disposition until a fresh read from the provider confirms it.
When screening returns a hit, you decide whether it is really your customer and record that decision. The decision is written to the screening service, which stays the source of truth. Admiin does not record a final local disposition until a fresh read from the provider confirms it.
The two calls
In this order. There is no time limit between them.
The decision is your own. You make it under your AML/CTF program, and you decide how long the review takes.
GET /v1/verifications/{id}/individuals/{individualId}/aml-matches/evidence
PATCH /v1/verifications/{id}/individuals/{individualId}/aml-matches/dispositions
The evidence call live-fetches the current PEP,
sanctions, watchlist and adverse-media result sets and returns an
opaque resultToken for each. A
200 licenses those tokens for a decision
by the same authenticated principal, with no time
limit. Then submit 1 to 25 unchanged tokens with one decision:
{
"idempotencyKey": "review-case-4821-v1",
"resultTokens": ["aml-profile-result:v1:sha256:aaaa…"],
"decision": "FALSE_POSITIVE",
"reasoning": "Reviewed the current source evidence against the verified identity."
}Decisions
decision |
Meaning |
|---|---|
FALSE_POSITIVE |
The result does not describe the screened person. |
TRUE_POSITIVE_ACCEPT |
A true match, and you accept the associated risk. |
TRUE_POSITIVE_REJECT |
A true match, and you reject the associated risk. |
One request carries one decision and cannot span provider checks.
reasoning is required. Reusing an
idempotencyKey with an identical request returns the
existing operation; reusing it with different input returns
409 IDEMPOTENCY_KEY_REUSED.
Decision responses
| Status | Meaning | Next step |
|---|---|---|
200 |
Every result is confirmed. | Use each result's outcome. |
202 |
At least one result is still pending. | Replay the same request and idempotency key. |
207 |
Confirmed and terminally failed results are mixed. | Handle each result by its outcome. |
502 |
Every result failed terminally. | Inspect each result for the failure reason. |
503 |
The provider is unavailable or the operation can retry. | Retry later. |
Refresh stale evidence
409 EVIDENCE_STALE means the results changed since your
last read, or you have not read them. It never means your read is
too old. Fetch the evidence again, review the update and resubmit.
If the results cannot be checked you get
503 AML_PROVIDER_READ_UNAVAILABLE and no decision is
recorded. Retry later.
Evidence availability
| Response | Meaning | Next step |
|---|---|---|
200 with results: [] |
No actionable results were found. | Treat the request as successful. |
503 EVIDENCE_UNAVAILABLE |
Evidence could not be fetched. The response omits
results.
|
Retry later. |