Skip to main content
PATCH
/
v3
/
session
/
{sessionId}
/
update-aml-hit-status
/
curl
curl -X PATCH \
  https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-hit-status/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "hit_id": "abc123",
    "review_status": "False Positive"
  }'
{ "message": "Hit status updated successfully", "hit_id": "abc123", "review_status": "False Positive" }

​
What this does

AML screening returns a list of hits — potential matches against sanction lists, PEP databases, watchlists, and adverse media. Each hit has a review_status (its disposition) that starts as Unreviewed or False Positive depending on the match score. This endpoint lets your team (or your automation) record a decision on each hit — without changing the overall session decision. Find the hits and their IDs in the session decision — the AML check’s hits array, where each hit’s id is the hit_id you pass here.

​
Review statuses

review_statusMeaning
UnreviewedDefault for hits at or above the match threshold — still needs a decision.
Confirmed MatchA true match for the screened individual / entity.
False PositiveNot the same entity. Default for hits below the match threshold.
InconclusiveCould not be determined.
Reviewer decisions are preserved across ongoing-monitoring re-screens — a hit you mark False Positive keeps that status when the provider re-screens the entity.

​
Update a single hit

PATCH /v3/session/{sessionId}/update-aml-hit-status/ 
curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../update-aml-hit-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hit_id": "abc123",
    "review_status": "False Positive"
  }'
For a session with multiple AML checks (graph workflows), add ?node_id=feature_aml_1 to the URL or include "node_id" in the body to target a specific check.

​
Update many hits at once

PATCH /v3/session/{sessionId}/bulk-update-aml-hit-status/ Pass hit_updates, a list of { hit_id, review_status } pairs. The operation is all-or-nothing: if any hit_id is not found, the request returns 404 and no hit is changed. 
curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../bulk-update-aml-hit-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hit_updates": [
      { "hit_id": "abc123", "review_status": "Confirmed Match" },
      { "hit_id": "def456", "review_status": "False Positive" }
    ]
  }'
A successful bulk call fires a single data.updated webhook and records one activity entry covering all the changes.

​
What happens after an update

  • Webhook — a data.updated event fires on the session.
  • Audit trail — the change is recorded on the session’s review trail with the actor (API key or user), visible in the console’s activity timeline.
  • Overall AML step status is untouched — changing a hit’s disposition does not, by itself, change the AML step status or the session decision. To change the AML step status (Approved / Declined / In Review), use update-feature-status. To change the session decision, use update-status.

​
KYC and KYB support

Works for both User Verification (KYC) and Business Verification (KYB) sessions — Didit resolves the sessionId across both. For KYB, AML screening runs on the company and its key people; each AML check exposes its own hits.

​
Permission

Requires the write:sessions privilege, with either a client API key (x-api-key) or a user authorization header.

​
Errors

StatusMeaning
400review_status is not a valid value, hit_id is empty, or hit_updates is empty.
403Missing/invalid credentials, or the caller lacks write:sessions.
404Session not found, the session has no AML check, or a hit_id was not found (bulk: nothing is changed).

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
sessionId
string<uuid>
required

UUID of the verification session. Accepts both user (KYC) and business (KYB) session IDs — the service resolves the ID across both session types.

Example:

"11111111-2222-3333-4444-555555555555"

Query Parameters

​
node_id
string

Workflow graph node ID. Required only when the session has multiple AML checks (one per node); omit it for single-AML sessions.

Example:

"feature_aml_1"

Body

application/json
​
hit_id
string
required

The id of the hit in the AML check's hits array.

Example:

"abc123"

​
review_status
enum<string>
required

The new review status for the hit.

Available options:
Unreviewed,
Confirmed Match,
False Positive,
Inconclusive
Example:

"False Positive"

​
node_id
string

Optional graph node ID. Use it (here or as a query parameter) when the session has multiple AML checks.

Example:

"feature_aml_1"

Response

Hit review status updated.