> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Update AML Hit Status

> Mark individual AML screening hits as Confirmed Match, False Positive, or Inconclusive — single or in bulk — straight from the API.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Update AML Hit Status Prompt"
  prompt={`Set the review status (disposition) of AML screening hits on a Didit session — one hit, or many at once.

AML screening returns a list of HITS (potential sanction / PEP / watchlist / adverse-media matches). Each hit carries a review_status you can change to record your compliance decision. This does NOT change the overall session decision.

Two endpoints:

1) Single hit
PATCH https://verification.didit.me/v3/session/{session_id}/update-aml-hit-status/
Body:
- hit_id (string, required) — the "id" of the hit in the AML check's "hits" array (see GET /v3/session/{id}/decision/).
- review_status (string, required) — one of "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive".
- node_id (string, optional) — graph node ID, only if the session has multiple AML checks.

2) Bulk
PATCH https://verification.didit.me/v3/session/{session_id}/bulk-update-aml-hit-status/
Body:
- hit_updates (array, required) — list of { "hit_id": "...", "review_status": "..." }.
- node_id (string, optional).
All-or-nothing: if any hit_id is missing, returns 404 and nothing changes.

Authentication:
x-api-key (client API key) or a user-auth token. Privilege: write:sessions.

Status values:
- Unreviewed — default for hits at/above the match threshold; still needs review.
- Confirmed Match — a true match.
- False Positive — not the same entity; default for hits below the match threshold.
- Inconclusive — could not determine.

Reviewer decisions are PRESERVED across ongoing-monitoring re-screens.

curl — clear one hit as a false positive:
curl -X PATCH https://verification.didit.me/v3/session/<SESSION_ID>/update-aml-hit-status/ \\
-H "x-api-key: <API_KEY>" \\
-H "Content-Type: application/json" \\
-d '{ "hit_id": "abc123", "review_status": "False Positive" }'

curl — bulk:
curl -X PATCH https://verification.didit.me/v3/session/<SESSION_ID>/bulk-update-aml-hit-status/ \\
-H "x-api-key: <API_KEY>" \\
-H "Content-Type: application/json" \\
-d '{ "hit_updates": [ { "hit_id": "abc123", "review_status": "Confirmed Match" }, { "hit_id": "def456", "review_status": "False Positive" } ] }'

Side effects:
- Fires a data.updated webhook.
- Appends an activity entry (with actor attribution) to the session review trail.

Failure modes:
- 400 — review_status not a valid value, hit_id empty, or hit_updates empty.
- 403 — invalid credentials, or the caller lacks write:sessions.
- 404 — session not found, no AML check, or a hit_id was not found.

Related: to change the overall AML step status (Approved/Declined/In Review) use PATCH /v3/session/{id}/features/{node_id}/update-status/ (see /sessions-api/update-feature-status).

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>

## 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](/sessions-api/retrieve-session) — the AML check's `hits` array, where each hit's `id` is the `hit_id` you pass here.

## Review statuses

| `review_status`   | Meaning                                                                    |
| ----------------- | -------------------------------------------------------------------------- |
| `Unreviewed`      | Default for hits at or above the match threshold — still needs a decision. |
| `Confirmed Match` | A true match for the screened individual / entity.                         |
| `False Positive`  | Not the same entity. Default for hits below the match threshold.           |
| `Inconclusive`    | Could not be determined.                                                   |

<Note>
  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.
</Note>

## Update a single hit

**`PATCH /v3/session/{sessionId}/update-aml-hit-status/`**

```bash theme={null}
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.

```bash theme={null}
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](/sessions-api/update-feature-status). To change the **session** decision, use [update-status](/sessions-api/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

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

## Related

* [Update feature status](/sessions-api/update-feature-status) — change the AML **step** status (or any other step).
* [Update session status](/sessions-api/update-status) — change the overall session decision.
* [Retrieve session](/sessions-api/retrieve-session) — read the AML `hits` and their IDs.
* [AML screening](/standalone-apis/aml-screening) — how screening and scoring work.


## OpenAPI

````yaml PATCH /v3/session/{sessionId}/update-aml-hit-status/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/update-aml-hit-status/:
    patch:
      tags:
        - Sessions
      summary: Update an AML hit review status
      description: >-
        Set the review status of a **single AML hit** (a potential sanction /
        PEP / watchlist / adverse-media match) returned by AML screening,
        without changing the overall session decision. Identify the hit by its
        `hit_id` (the `id` of an entry in the AML check's `hits` array — see the
        session decision).


        `review_status` is one of `Unreviewed`, `Confirmed Match`, `False
        Positive`, or `Inconclusive`. Reviewer decisions are preserved across
        ongoing-monitoring updates, so a hit you mark `False Positive` stays
        that way when the provider re-screens.


        A successful call fires a `data.updated` webhook and appends an activity
        entry (with actor attribution) to the session's review trail. For graph
        workflows with multiple AML checks, pass `node_id` to target a specific
        check.


        Authenticate with your API key (`x-api-key`) or a user authorization
        header — either must carry the `write:sessions` privilege.
      operationId: patch_v3_session_update_aml_hit_status
      parameters:
        - in: path
          name: sessionId
          required: true
          description: >-
            UUID of the verification session. Accepts both user (KYC) and
            business (KYB) session IDs — the service resolves the ID across both
            session types.
          schema:
            type: string
            format: uuid
            example: 11111111-2222-3333-4444-555555555555
        - in: query
          name: node_id
          required: false
          description: >-
            Workflow graph node ID. Required only when the session has multiple
            AML checks (one per node); omit it for single-AML sessions.
          schema:
            type: string
            example: feature_aml_1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hit_id
                - review_status
              properties:
                hit_id:
                  type: string
                  description: The `id` of the hit in the AML check's `hits` array.
                  example: abc123
                review_status:
                  type: string
                  description: The new review status for the hit.
                  enum:
                    - Unreviewed
                    - Confirmed Match
                    - False Positive
                    - Inconclusive
                  example: False Positive
                node_id:
                  type: string
                  description: >-
                    Optional graph node ID. Use it (here or as a query
                    parameter) when the session has multiple AML checks.
                  example: feature_aml_1
      responses:
        '200':
          description: Hit review status updated.
          content:
            application/json:
              example:
                message: Hit status updated successfully
                hit_id: abc123
                review_status: False Positive
        '400':
          description: >-
            Validation error — `hit_id` empty or `review_status` not one of the
            allowed values.
          content:
            application/json:
              example:
                review_status:
                  - '"Maybe" is not a valid choice.'
        '403':
          description: >-
            Missing/invalid credentials or insufficient permissions. This API
            returns `403` for authentication failures — never `401`.
          content:
            application/json:
              examples:
                Invalid Credentials:
                  summary: Missing or invalid x-api-key
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
                Missing Privilege:
                  summary: API key lacks write:sessions
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: >-
            The session was not found, the session has no AML check (optionally
            for the given `node_id`), or no hit matches `hit_id`.
          content:
            application/json:
              examples:
                No AML Check:
                  summary: Session has no AML check
                  value:
                    detail: The session does not have an AML check.
                Hit Not Found:
                  summary: Unknown hit_id
                  value:
                    detail: Hit with ID 'abc123' not found in the AML check.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            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"
              }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.patch(
                "https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-hit-status/",
                headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
                json={"hit_id": "abc123", "review_status": "False Positive"},
            )
            print(response.json())
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````