> ## 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.
# Enable or Disable AML Monitoring for Businesses
> Turn AML ongoing monitoring on or off for many businesses in one call, with a cost estimate dry-run, a pollable job and a per-business outcome.
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
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
Content-Type: application/json
Request body:
- is_enabled: boolean (required) - true to enable monitoring, false to disable it.
- estimate_only: boolean (default false) - when true, returns the cost preview and performs NO writes: no screening, no billing, no job.
- vendor_data_list: string[] - your own identifiers, matched exactly as sent.
- didit_internal_id_list: string[] (UUIDs) - the didit_internal_id returned by the create, get and list endpoints.
Provide at least one list; the two are OR'd. At most 1000 identifiers per request across both lists - split larger selections into several calls.
Semantics:
- One monitored screening per business: a company that verified several times is monitored and billed once. Disabling turns monitoring off across all of the business's screenings.
- Businesses without any AML screening are screened first (billed as a regular AML screening) using their legal name (or display name) and country; a business with no name is reported as skipped_no_identity_data.
- Sandbox applications never create screenings (skipped_sandbox).
- Enabling is refused with 403 when the organization balance does not cover the estimate; the response carries the estimate.
curl (estimate first):
curl -X POST 'https://verification.didit.me/v3/businesses/aml-monitoring/' \\
-H 'x-api-key: YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{"is_enabled": true, "estimate_only": true, "vendor_data_list": ["company-123", "company-456"]}'
Response 200 (estimate_only):
{
"users_total": 2, "already_enabled": 0, "with_existing_aml": 1, "needing_screening": 1,
"skipped_no_identity_data": 0, "skipped_blocked": 0,
"estimated_screening_cost_usd": 0.2, "estimated_annual_monitoring_cost_usd": 0.14,
"balance_sufficient": true, "unmatched": []
}
(users_total counts the selected businesses; the estimate shape is shared with the users endpoint.)
curl (enable):
curl -X POST 'https://verification.didit.me/v3/businesses/aml-monitoring/' \\
-H 'x-api-key: YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{"is_enabled": true, "vendor_data_list": ["company-123", "company-456"]}'
Response 200 (20 businesses or fewer - processed inline, already COMPLETED) or 202 (more than 20 - running in the background):
{
"job_id": "", "status": "COMPLETED", "is_enabled": true, "target_type": "business",
"total": 2, "processed": 2,
"outcomes": {"enabled": 1, "screened_and_enabled": 1, "already_enabled": 0, "disabled": 0, "skipped_no_identity_data": 0, "skipped_blocked": 0, "skipped_sandbox": 0, "failed_provider": 0, "failed_insufficient_balance": 0},
"results": [
{"didit_internal_id": "", "vendor_data": "company-123", "outcome": "enabled"},
{"didit_internal_id": "", "vendor_data": "company-456", "outcome": "screened_and_enabled"}
],
"estimate": { ...same shape as above, without unmatched... },
"unmatched": [],
"error": null, // generic message when status is FAILED
"created_at": "", "completed_at": ""
}
On 202, poll GET /v3/aml-monitoring/jobs/{job_id}/ every couple of seconds until status is COMPLETED or FAILED; results fills in as businesses are processed.
Per-business outcome values: enabled, screened_and_enabled, already_enabled, disabled, skipped_no_identity_data, skipped_sandbox, failed_provider, failed_insufficient_balance (skipped_blocked is always 0 for businesses).
Failure modes:
- 400 - is_enabled missing, no selector, or more than 1000 identifiers across both lists.
A selection that matches nothing is NOT an error: the job completes with total 0 and every identifier is listed under unmatched (same convention as the batch delete endpoints).
- 401 - missing/invalid x-api-key.
- 403 - insufficient balance to enable monitoring for this selection (body: error + estimate).
Idempotency: re-sending an enable returns already_enabled for businesses that are already monitored, with no second screening and no second bill. Disabling an unmonitored business returns disabled and changes nothing.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>
## Overview
Enables or disables [ongoing AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) for the selected [Business entities](/entities/businesses/overview), exactly as the **AML Ongoing monitoring** action in the Business Console does. The Console and this endpoint run the same underlying operation, so the rules, the billing and the outcomes are identical.
Send `estimate_only: true` first to see how many businesses are selected, how many need a new AML screening, the one-time screening cost and the yearly monitoring cost. Nothing is written by a dry-run. The estimate uses the same field names as the users endpoint, so `users_total` is the number of selected businesses.
## How a selection is processed
* **One monitored screening per business.** A company that verified several times is monitored and billed once. Disabling turns monitoring off across all of that business's screenings.
* **Businesses without an AML screening are screened first.** Didit creates a new AML verification for them (visible in the business's **Verifications** tab), billed as a regular AML screening, and enables monitoring on it. The screening uses the business's legal name (or display name) and country; a business with no name at all is reported as `skipped_no_identity_data` rather than silently dropped.
* **Sandbox applications never create screenings** (`skipped_sandbox`).
* **Balance is checked up front.** Enabling is refused with `403` when your balance does not cover the estimate, and the response carries the estimate so you know how much to top up.
* **Yearly renewal.** A newly monitored business is billed the yearly monitoring price at its next renewal date, the same date the Console shows in the **Ongoing monitoring** column. Disabling stops the renewal; it does not refund a period already billed.
## Selection and batch size
Select businesses with `vendor_data_list`, `didit_internal_id_list`, or both; the two lists are OR'd. A request accepts at most **1000 identifiers** across both lists. Identifiers that match no business in your application are returned under `unmatched`, exactly as sent, and never fail the request: a selection that matches nothing completes as an empty job (`total: 0`) with every identifier listed, the same convention as the batch delete endpoints.
## Inline or in the background
Selections of **20 businesses or fewer** are processed inline and the call returns `200` with the finished job. Larger selections return `202` with a `PENDING` job; poll [Get AML Monitoring Job](/management-api/aml-monitoring/get-job) until `status` is `COMPLETED` or `FAILED`. Either way the job carries one `results` entry per business with its `outcome`.
| `outcome` | Meaning |
| ----------------------------- | ---------------------------------------------------------------------- |
| `enabled` | Monitoring enabled on an existing AML screening. |
| `screened_and_enabled` | A new AML screening was created (billed) and monitoring enabled on it. |
| `already_enabled` | Monitoring was already active; nothing changed, nothing billed. |
| `disabled` | Monitoring turned off across every screening of the business. |
| `skipped_no_identity_data` | The business has no legal or display name to screen. |
| `skipped_sandbox` | Sandbox application; no screening is created. |
| `failed_provider` | The screening could not be completed. Retry later. |
| `failed_insufficient_balance` | Balance ran out while the job was running. |
## Webhooks
Toggling monitoring emits no webhook of its own. Once monitoring is on, re-screens keep firing the usual `status.updated` and `data.updated` events described in [Continuous AML Monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening).
## Permissions
Any active API key of the application can call this endpoint. Didit API keys are **application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions) decide what a *person* can do in the Console and are not evaluated for Management API traffic.
## Related
* [Get AML Monitoring Job](/management-api/aml-monitoring/get-job)
* [Toggle AML Monitoring for Users](/management-api/aml-monitoring/toggle-users)
* [Continuous AML Monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening)
* [Business AML screening](/business-verification/aml)
* [List Businesses](/management-api/businesses/list)
## OpenAPI
````yaml POST /v3/businesses/aml-monitoring/
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/businesses/aml-monitoring/:
post:
tags:
- AML Ongoing Monitoring
summary: Enable or disable AML ongoing monitoring for businesses
description: >-
Turns AML ongoing monitoring on or off for the selected businesses, with
the same semantics as the Business Console. Exactly one monitored AML
screening is kept per business, so a profile that verified several times
is monitored and billed once; disabling turns monitoring off across all
of the profile's screenings. Businesses without any AML screening are
screened first (billed as a regular AML screening) when they have the
legal or display name needed; otherwise they are reported as
`skipped_no_identity_data`.
Set `estimate_only: true` to preview counts and costs without writing
anything. Selections of 20 profiles or fewer resolve inline and return
`200` with the completed job; larger selections return `202` and run in
the background - poll [Get AML monitoring
job](#get-/v3/aml-monitoring/jobs/-job_id-/) with the returned `job_id`.
Enabling is refused with `403` when the organization balance does not
cover the estimate. Identifiers that match nothing are listed in
`unmatched` and never fail the request: a selection that matches nothing
completes as an empty job (`total` 0), the same convention as the batch
delete endpoints.
operationId: toggle_businesses_aml_monitoring
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- is_enabled
description: >-
Select businesses with `vendor_data_list`,
`didit_internal_id_list`, or both (the two lists are OR'd). At
most 1000 identifiers per request across both lists.
properties:
is_enabled:
type: boolean
description: true to enable monitoring, false to disable it.
estimate_only:
type: boolean
default: false
description: >-
When true, returns the cost estimate and performs no writes
- no screening, no billing, no job.
vendor_data_list:
type: array
items:
type: string
description: >-
Your own identifiers of the businesses to toggle, matched
exactly as sent.
didit_internal_id_list:
type: array
items:
type: string
format: uuid
description: >-
Didit internal ids of the businesses to toggle - the
`didit_internal_id` returned by the create, get and list
endpoints.
examples:
Estimate first:
summary: Preview the cost without writing
value:
is_enabled: true
estimate_only: true
vendor_data_list:
- company-123
- company-456
Enable:
summary: Enable monitoring for two businesses
value:
is_enabled: true
vendor_data_list:
- company-123
- company-456
Disable:
summary: Disable monitoring by Didit internal id
value:
is_enabled: false
didit_internal_id_list:
- 3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11
responses:
'200':
description: >-
The estimate (when `estimate_only` is true) or the completed job for
a selection processed inline.
content:
application/json:
schema:
oneOf:
- type: object
required:
- users_total
- already_enabled
- with_existing_aml
- needing_screening
- skipped_no_identity_data
- skipped_blocked
- estimated_screening_cost_usd
- estimated_annual_monitoring_cost_usd
- balance_sufficient
- unmatched
description: >-
Cost preview. Returned directly when estimate_only is true
(nothing is written).
properties:
users_total:
type: integer
description: Profiles matched by the selection.
already_enabled:
type: integer
description: >-
Profiles already monitored (nothing to do when
enabling; these are what disabling turns off).
with_existing_aml:
type: integer
description: >-
Profiles whose existing AML screening will be switched
to monitored (no new screening).
needing_screening:
type: integer
description: >-
Profiles without any AML screening that will be
screened first (billed as a regular AML screening).
skipped_no_identity_data:
type: integer
description: >-
Profiles that cannot be screened because identity data
is missing.
skipped_blocked:
type: integer
description: >-
Blocked users that will be skipped (always 0 for
businesses).
estimated_screening_cost_usd:
type: number
example: 0.2
description: One-time cost of the new screenings.
estimated_annual_monitoring_cost_usd:
type: number
example: 0.07
description: >-
Yearly monitoring cost of the profiles that will
become monitored.
balance_sufficient:
type: boolean
description: >-
Whether the organization balance covers the screening
plus the first year of monitoring.
unmatched:
type: array
items:
type: string
description: >-
Identifiers of the request that matched no profile in
this application, exactly as sent.
- type: object
required:
- job_id
- status
- is_enabled
- target_type
- total
- processed
- outcomes
- results
- error
- created_at
- completed_at
- estimate
- unmatched
properties:
job_id:
type: string
format: uuid
status:
type: string
enum:
- PENDING
- PROCESSING
- COMPLETED
- FAILED
is_enabled:
type: boolean
description: >-
true when the job enables monitoring, false when it
disables it.
target_type:
type: string
enum:
- user
- business
description: Which profile family the job toggles.
total:
type: integer
description: Profiles the job processes.
processed:
type: integer
description: Profiles processed so far.
outcomes:
type: object
description: >-
Per-record outcome counters. Every selected profile
resolves to exactly one counter; nothing is silently
skipped.
properties:
enabled:
type: integer
description: Monitoring enabled on an existing AML screening.
screened_and_enabled:
type: integer
description: >-
A new AML screening was created (billed) and
monitoring enabled on it.
already_enabled:
type: integer
description: >-
Monitoring was already active; nothing changed and
nothing was billed.
disabled:
type: integer
description: >-
Monitoring turned off across every AML screening
of the profile.
skipped_no_identity_data:
type: integer
description: >-
Skipped: the profile lacks the full name, date of
birth and country (users) or a name (businesses)
needed to screen.
skipped_blocked:
type: integer
description: 'Skipped: the user is blocked.'
skipped_sandbox:
type: integer
description: >-
Skipped: sandbox application, no screening is
created.
failed_provider:
type: integer
description: The screening could not be completed; retry later.
failed_insufficient_balance:
type: integer
description: Balance ran out while the job was running.
results:
type: array
description: >-
One entry per processed profile, in processing order.
Grows while the job runs; complete once status is
COMPLETED. Recorded for jobs started through the API.
items:
type: object
properties:
didit_internal_id:
type: string
format: uuid
description: Didit internal id of the profile.
vendor_data:
type: string
nullable: true
description: Your own identifier for the profile.
outcome:
type: string
enum:
- enabled
- screened_and_enabled
- already_enabled
- disabled
- skipped_no_identity_data
- skipped_blocked
- skipped_sandbox
- failed_provider
- failed_insufficient_balance
error:
type: string
nullable: true
description: >-
Generic failure message when status is FAILED; the
detailed cause is kept on the platform side.
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
nullable: true
estimate:
type: object
description: >-
Cost preview. Returned directly when estimate_only is
true (nothing is written).
properties:
users_total:
type: integer
description: Profiles matched by the selection.
already_enabled:
type: integer
description: >-
Profiles already monitored (nothing to do when
enabling; these are what disabling turns off).
with_existing_aml:
type: integer
description: >-
Profiles whose existing AML screening will be
switched to monitored (no new screening).
needing_screening:
type: integer
description: >-
Profiles without any AML screening that will be
screened first (billed as a regular AML
screening).
skipped_no_identity_data:
type: integer
description: >-
Profiles that cannot be screened because identity
data is missing.
skipped_blocked:
type: integer
description: >-
Blocked users that will be skipped (always 0 for
businesses).
estimated_screening_cost_usd:
type: number
example: 0.2
description: One-time cost of the new screenings.
estimated_annual_monitoring_cost_usd:
type: number
example: 0.07
description: >-
Yearly monitoring cost of the profiles that will
become monitored.
balance_sufficient:
type: boolean
description: >-
Whether the organization balance covers the
screening plus the first year of monitoring.
unmatched:
type: array
items:
type: string
description: >-
Identifiers of the request that matched no profile in
this application, exactly as sent. They are not part
of the job.
'202':
description: >-
Larger selections run in the background. Poll the job endpoint with
`job_id`; `results` fills in as profiles are processed.
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
format: uuid
status:
type: string
enum:
- PENDING
- PROCESSING
- COMPLETED
- FAILED
is_enabled:
type: boolean
description: >-
true when the job enables monitoring, false when it
disables it.
target_type:
type: string
enum:
- user
- business
description: Which profile family the job toggles.
total:
type: integer
description: Profiles the job processes.
processed:
type: integer
description: Profiles processed so far.
outcomes:
type: object
description: >-
Per-record outcome counters. Every selected profile
resolves to exactly one counter; nothing is silently
skipped.
properties:
enabled:
type: integer
description: Monitoring enabled on an existing AML screening.
screened_and_enabled:
type: integer
description: >-
A new AML screening was created (billed) and
monitoring enabled on it.
already_enabled:
type: integer
description: >-
Monitoring was already active; nothing changed and
nothing was billed.
disabled:
type: integer
description: >-
Monitoring turned off across every AML screening of
the profile.
skipped_no_identity_data:
type: integer
description: >-
Skipped: the profile lacks the full name, date of
birth and country (users) or a name (businesses)
needed to screen.
skipped_blocked:
type: integer
description: 'Skipped: the user is blocked.'
skipped_sandbox:
type: integer
description: 'Skipped: sandbox application, no screening is created.'
failed_provider:
type: integer
description: The screening could not be completed; retry later.
failed_insufficient_balance:
type: integer
description: Balance ran out while the job was running.
results:
type: array
description: >-
One entry per processed profile, in processing order.
Grows while the job runs; complete once status is
COMPLETED. Recorded for jobs started through the API.
items:
type: object
properties:
didit_internal_id:
type: string
format: uuid
description: Didit internal id of the profile.
vendor_data:
type: string
nullable: true
description: Your own identifier for the profile.
outcome:
type: string
enum:
- enabled
- screened_and_enabled
- already_enabled
- disabled
- skipped_no_identity_data
- skipped_blocked
- skipped_sandbox
- failed_provider
- failed_insufficient_balance
error:
type: string
nullable: true
description: >-
Generic failure message when status is FAILED; the
detailed cause is kept on the platform side.
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
nullable: true
estimate:
type: object
description: >-
Cost preview. Returned directly when estimate_only is true
(nothing is written).
properties:
users_total:
type: integer
description: Profiles matched by the selection.
already_enabled:
type: integer
description: >-
Profiles already monitored (nothing to do when
enabling; these are what disabling turns off).
with_existing_aml:
type: integer
description: >-
Profiles whose existing AML screening will be switched
to monitored (no new screening).
needing_screening:
type: integer
description: >-
Profiles without any AML screening that will be
screened first (billed as a regular AML screening).
skipped_no_identity_data:
type: integer
description: >-
Profiles that cannot be screened because identity data
is missing.
skipped_blocked:
type: integer
description: >-
Blocked users that will be skipped (always 0 for
businesses).
estimated_screening_cost_usd:
type: number
example: 0.2
description: One-time cost of the new screenings.
estimated_annual_monitoring_cost_usd:
type: number
example: 0.07
description: >-
Yearly monitoring cost of the profiles that will
become monitored.
balance_sufficient:
type: boolean
description: >-
Whether the organization balance covers the screening
plus the first year of monitoring.
unmatched:
type: array
items:
type: string
description: >-
Identifiers of the request that matched no profile in this
application, exactly as sent. They are not part of the
job.
'400':
description: >-
Validation error: `is_enabled` missing, no selector, or more than
1000 identifiers across both lists.
'401':
description: Missing or invalid API key.
'403':
description: >-
Insufficient balance to enable monitoring for this selection. The
response carries the `estimate` so you can top up the right amount.
content:
application/json:
schema:
type: object
properties:
error:
type: string
estimate:
type: object
description: >-
Cost preview. Returned directly when estimate_only is true
(nothing is written).
properties:
users_total:
type: integer
description: Profiles matched by the selection.
already_enabled:
type: integer
description: >-
Profiles already monitored (nothing to do when
enabling; these are what disabling turns off).
with_existing_aml:
type: integer
description: >-
Profiles whose existing AML screening will be switched
to monitored (no new screening).
needing_screening:
type: integer
description: >-
Profiles without any AML screening that will be
screened first (billed as a regular AML screening).
skipped_no_identity_data:
type: integer
description: >-
Profiles that cannot be screened because identity data
is missing.
skipped_blocked:
type: integer
description: >-
Blocked users that will be skipped (always 0 for
businesses).
estimated_screening_cost_usd:
type: number
example: 0.2
description: One-time cost of the new screenings.
estimated_annual_monitoring_cost_usd:
type: number
example: 0.07
description: >-
Yearly monitoring cost of the profiles that will
become monitored.
balance_sufficient:
type: boolean
description: >-
Whether the organization balance covers the screening
plus the first year of monitoring.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X POST
'https://verification.didit.me/v3/businesses/aml-monitoring/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"is_enabled": true, "vendor_data_list": ["company-123", "company-456"]}'
- lang: python
label: Python
source: |-
import requests
resp = requests.post(
'https://verification.didit.me/v3/businesses/aml-monitoring/',
headers={'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={'is_enabled': True, 'vendor_data_list': ['company-123', 'company-456']},
)
resp.raise_for_status()
job = resp.json()
print(job['status'], job['outcomes'])
for row in job['results']:
print(row['vendor_data'], row['outcome'])
- lang: javascript
label: JavaScript
source: >-
const resp = await
fetch('https://verification.didit.me/v3/businesses/aml-monitoring/',
{
method: 'POST',
headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ is_enabled: true, vendor_data_list: ['company-123', 'company-456'] }),
});
const job = await resp.json();
console.log(job.status, job.outcomes);
for (const row of job.results) console.log(row.vendor_data,
row.outcome);
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````