> ## 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 Check Status > Set the status of a session's AML screening check, such as Approved after clearing its hits, without changing the overall session decision. Update AML Check Status API Prompt Copy prompt to clipboard \

\`Set the status of the AML screening check of a Didit verification session through the API.

Endpoint:
PATCH https://verification.didit.me/v3/session/{session_id}/update-aml-status/

Authentication:
Send my Didit API key in the x-api-key header. A scoped key needs decisions: write.

Goal:
\- Record my compliance decision on a session's AML check as a whole (the status of an aml_screenings[] entry in the session decision), for example Approved after my team cleared every hit.

Request body (JSON):
\- status (required): "Approved", "Declined", "In Review", "Not Finished" or "Resub Requested".
\- node_id (optional): the workflow node ID of the AML check when the session ran several AML steps. It can also be sent as the node_id query parameter. Without it the most recent AML check is updated.

Behavior:
\- Works for user (KYC) and business (KYB) session IDs.
\- Only the AML check changes. The session status is not recomputed: use PATCH /v3/session/{session_id}/update-status/ to change the session decision, and PATCH /v3/session/{session_id}/update-aml-hit-status/ to mark individual hits.
\- When the status changes, Didit adds an AML_STATUS_UPDATED activity entry and sends a data.updated webhook.
\- Sending the status the check already has returns 200 and changes nothing (no activity entry, no webhook).

Example call:
curl -X PATCH "https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-status/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "Approved"}'

What to read from the response:
\- status: the AML check status now.
\- previous_status: the status before the call (equal to status when nothing changed).

Failure modes:
\- 400: status missing or not one of the allowed values.
\- 401: the API key has expired.
\- 403: missing or invalid key, a key of another application, a scoped key without decisions: write, or a request from outside the key's IP allowlist.
\- 404: the session does not exist, was deleted, or is outside a scoped key's limits, or it has no AML check (for that node_id). This is checked before the body, so it wins over a 400.

Side effects: changes the AML check status, adds an activity entry and sends a data.updated webhook (only when the status changed).

For the full integration shape, see /integration/integration-prompt.`

\
Paste into To decide on individual matches instead of the whole check, use [Update AML hit status](/sessions-api/update-aml-hit-status.md). For how screening results and statuses are produced, see [AML screening](/core-technology/aml-screening/overview.md). ## OpenAPI ````yaml PATCH /v3/session/{sessionId}/update-aml-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-status/: patch: tags: - Sessions summary: Update an AML check status description: >- Set the status of a session's AML screening check as a whole (the `status` of an `aml_screenings[]` entry in the session decision), for example `Approved` after your team cleared every hit. Works for KYC and KYB session IDs; pass `node_id` (query parameter or body field) when the session ran more than one AML step, otherwise the most recent AML check is updated. When the status actually changes, an `AML_STATUS_UPDATED` activity entry is recorded and a `data.updated` [webhook](https://docs.didit.me/integration/webhooks) is sent; sending the current status returns `200` and changes nothing. The session status is not recomputed: use `PATCH /v3/session/{sessionId}/update-status/` for the session decision and `PATCH /v3/session/{sessionId}/update-aml-hit-status/` for single hits. A scoped API key needs `decisions: write`. operationId: patch_v3_session_update_aml_status parameters: - name: sessionId in: path required: true description: >- UUID of the verification session (the `session_id` returned by `POST /v3/session/`). Accepts both User Verification (KYC) and Business Verification (KYB) session IDs: the server resolves the ID across both session types. Must be a well-formed UUID; a malformed value does not match the route and returns an HTML `404`. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 - name: node_id in: query required: false description: >- Workflow graph node ID of the AML check to update. Needed only when the session ran more than one AML step. Takes precedence over `node_id` in the body. schema: type: string example: feature_aml_1 requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: New status of the AML check. example: Approved node_id: type: string description: >- Workflow graph node ID of the AML check, as an alternative to the query parameter. example: feature_aml_1 example: status: Approved responses: '200': description: AML check status set (or unchanged when it already had this value). content: application/json: schema: type: object required: - message - status - previous_status properties: message: type: string description: Always `AML status updated successfully`. status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: Status of the AML check now. previous_status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- Status before the call. Equal to `status` when nothing changed. example: message: AML status updated successfully status: Approved previous_status: In Review '400': description: >- Validation error: `status` missing or not one of the allowed values. The AML check lookup runs first, so a session without an AML check returns `404` even with an invalid body. content: application/json: examples: Missing status: summary: Empty body or no status value: status: - This field is required. Invalid status: summary: status not in the enum value: status: - '"Cleared" is not a valid choice.' '401': description: >- The scoped API key has expired. This is the only case that returns `401`: a missing, invalid or revoked key returns `403`. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Expired key: summary: The key's expiry date has passed value: detail: This API key has expired. '403': description: >- Authentication or authorization failure. Missing, invalid and revoked keys return `403` (not `401`); so do a key of another application, a scoped key without the permission this endpoint needs, and a request from outside the key's IP allowlist. Distinguish them by `detail`. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Missing or invalid credentials: summary: No x-api-key header, or the key failed validation value: detail: >- Authentication credentials were not provided or are invalid. Other application: summary: >- A valid key that belongs to a different application than the session value: detail: You do not have permission to perform this action. Scoped key without decisions write: summary: 'Scoped key lacks decisions: write' value: detail: This API key has no write access to decisions. IP not allowed: summary: Request from outside the key's IP allowlist value: detail: This API key can't be used from this IP address. '404': description: >- The session does not exist, was deleted or is outside a scoped key's limits, or it has no AML check (for the given `node_id`). The session lookup runs before the credential check, so an unknown `sessionId` returns `404` even without a valid key. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Unknown session: summary: No session with this ID exists, or it was deleted value: detail: Not found. Outside key limits: summary: >- The session is outside a scoped key's limits (also returned for a session deleted moments ago) value: detail: Session not found. No AML check: summary: The session never ran an AML step value: detail: The session does not have an AML check. No AML check for node: summary: node_id does not match an AML check of the session value: detail: >- The session does not have an AML check for node 'feature_aml_2'. '429': description: >- Rate limit exceeded: 300 write (POST, PATCH, DELETE) requests per minute per API key. Wait `Retry-After` seconds before retrying; the `X-RateLimit-*` headers show the budget. content: application/json: schema: type: object properties: detail: type: string description: Human-readable error message. examples: Rate limited: summary: Budget for the current minute exhausted value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 example: 30 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-status/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"status": "Approved"}' - lang: python label: Python source: |- import os import requests session_id = '11111111-2222-3333-4444-555555555555' resp = requests.patch( f'https://verification.didit.me/v3/session/{session_id}/update-aml-status/', headers={'x-api-key': os.environ['DIDIT_API_KEY']}, json={'status': 'Approved'}, timeout=10, ) resp.raise_for_status() body = resp.json() print(body['previous_status'], '->', body['status']) - lang: javascript label: JavaScript source: >- const sessionId = '11111111-2222-3333-4444-555555555555'; const resp = await fetch(`https://verification.didit.me/v3/session/${sessionId}/update-aml-status/`, { method: 'PATCH', headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ status: 'Approved' }), }); if (!resp.ok) throw new Error(`Update failed: ${resp.status}`); const body = await resp.json(); console.log(body.previous_status, '->', body.status); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.