AML Monitoring Migration Guide

Overview

iDenfy introduced AML Monitoring v3 with an upgraded screening engine. Existing v2 integrations continue to work — the API automatically handles backward compatibility and your webhooks will look exactly as they always have.

There is no announced shutdown date for v2 compatibility. However, the mapping layer exists for continuity, not as a permanent solution. We recommend planning migration to v3 to ensure long-term stability and access to the full capabilities of the screening engine.

This guide covers:

What changed between v2 and v3
Request body field changes with examples
The complete webhook payload reference
The recommended migration path and a complete migration checklist

What Changed

Event	Status transition
Initial screening complete	`PENDING` → `ACTIVE` or `ALERT`
New match found	→ `ALERT`
Match resolved	→ `ACTIVE`

Status Field Names

v3 introduced a new status field with updated values. The existing alertStatus field continues to return v2 values for all integrations.

v2 (`alertStatus`)	v3 (`status`)
`ACCEPTED`	`ACTIVE`
`ALERT`	`ALERT`
`DECLINED`	`STOPPED`
`PENDING`	`PENDING`

Both fields are present in all webhook payloads. If you are on v2, use alertStatus and ignore status.

Request Body Fields

When migrating to v3 endpoints, the request body structure changes. v3 uses a nested structure — a top-level object wrapping an amlCheck object with separate input (who to screen) and filter (what to screen for) sub-objects. Person monitoring:

Area	v2 field	v3 field	Notes
First name	`name`	—	Combined into `fullName`
Last name	`surname`	—	Combined into `fullName`
Full name	—	`amlCheck.input.fullName`	Single combined field
Subject type	`type: "PERSON"`	`userType: "PERSON"`	Renamed
Date of birth	`dateOfBirth`	`amlCheck.input.dateOfBirth`	Moved into nested input
Nationality	`nationality`	`amlCheck.input.nationality`	Moved into nested input
Gender	—	`amlCheck.input.sex`	New optional field: `M`, `F`, or `O`
Adverse media	`monitorAdverseMedia: true`	—	Legacy feature, not supported in v3
Auto-renewal	`autoExpirationExtension`	`isSubscribed`	Renamed, same boolean behaviour

Company monitoring:

Area	v2 field	v3 field	Notes
Company name	`name`	`amlCheck.input.companyName`	Renamed and nested
Subject type	`type: "COMPANY"`	`userType: "COMPANY"`	Renamed
Country	`nationality`	`amlCheck.input.country`	Renamed and nested

The name + surname → fullName change is the most common cause of silent failures. If you send name and surname separately to a v3 endpoint, the fields are ignored and the check runs with no name.

Example v3 request body (person):

{
  "userType": "PERSON",
  "isSubscribed": true,
  "tags": [],
  "amlCheck": {
    "input": {
      "fullName": "John Doe",
      "nationality": "GBR",
      "dateOfBirth": "1980-01-15",
      "sex": "M"
    },
    "filter": {
      "datasets": ["PEP", "SAN"]
    }
  }
}

Datasets

v3 lets you control which screening databases to check via the amlCheck.filter.datasets array. This replaces the implicit fixed set from v2, where adverse media was a separate boolean toggle.

Dataset	Description
`PEP`	All PEP tiers — shorthand that expands to current, former, and linked
`PEP-CURRENT`	Active politically exposed persons
`PEP-FORMER`	Former PEPs
`PEP-LINKED`	Associates and family members of PEPs
`SAN`	All sanctions — shorthand for current and former
`SAN-CURRENT`	Active sanctions
`SAN-FORMER`	Expired or lifted sanctions

If datasets is omitted or null, the system falls back to the default dataset set configured on your partner contract. If no contract default is configured, the request will fail with a validation error. Contact support if you are unsure what datasets are enabled on your account.

False Positive Handling

v2 and v3 handle false positives differently — there is no direct 1:1 equivalent endpoint.

v2 (POST /api/v2/add-whitelist) marked an entire monitoring subject as whitelisted using their monitoringId.
v3 (DELETE /aml/monitorings/{id}/profiles/{profileId}/) removes a specific matched profile from the results, leaving the monitoring record and any other matches intact.

The v3 approach is more granular — you dismiss individual matches rather than the whole subject. The profileId is returned inside each match entry in the monitoring response and webhook payload. Store or pass through this ID in your integration to support false positive dismissal.

Webhook Reference

Both v2 and v3 send the same webhook payload structure. v3 adds the status field and an optional amlCheck object — both can be safely ignored if you have not yet migrated.

Headers

Header	Value
`Idenfy-Event-Type`	`AML_MONITORING`
`Content-Type`	`application/json; charset=utf-8`
`User-Agent`	`iDenfy/1.0`
`Idenfy-Signature`	HMAC-SHA256 signature — only present if a signing key is configured

Payload Fields

If you are on v3, use the amlCheck object from the webhook payload for all screening results. The top-level fields below exist only for backward compatibility with v2 integrations and should not be relied on in new or migrated integrations.

Top-level (v2 compatibility fields):

Field	Type	Description
`monitoringId`	string (UUID)	Unique identifier for this monitoring record
`name` / `surname`	string	Subject’s name
`nationality`	string	ISO country code
`dob`	string \| null	Date of birth
`isActive`	boolean	Whether monitoring is still running
`expiration`	string	Monitoring expiry date
`alertStatus`	string	v2 status: `ACCEPTED`, `ALERT`, `DECLINED`, `PENDING`
`status`	string	v3 status: `ACTIVE`, `ALERT`, `STOPPED`, `PENDING`
`pepsStatus`	string	`NOT_CHECKED`, `FLAGS_FOUND`, `FALSE_POSITIVE`, or `CLEAR`
`sanctionsStatus`	string	Same values as `pepsStatus`
`adverseMediaStatus`	string	Same values as `pepsStatus`
`results[]`	array	Per-category check results (see below)

amlCheck — v3 screening results (use this on v3): The amlCheck object contains the full World-Check screening output broken down by dataset, with per-finding profileId values used for false positive dismissal. Refer to the API Reference for the complete schema. results[] — v2 compatibility, per-category check:

Field	Type	Description
`serviceName`	string	Name of the check that ran
`serviceGroupType`	string	Category, e.g. `AML_NAMES_CHECK`
`status.overallStatus`	string	`SUSPECTED`, `NOT_SUSPECTED`, or `ERROR`
`data[]`	array	Matched profiles (see below)

data[] — matched profile:

Field	Type	Description
`listName`	string	`PEPS` or `SANCTION`
`name` / `surname`	string	Matched entity’s name
`nationality`	string	Matched entity’s nationality
`dob`	string \| null	Matched entity’s date of birth
`score`	integer	Match confidence (0–100)
`pepLevel`	integer	PEP tier 1–4 (present for PEP matches only)
`category`	string	e.g. `Head of Government`
`reason`	string	Why this entity is listed
`whitelisted`	boolean	Whether you have marked this as a false positive
`isActive`	boolean	Whether the entity is still active on the list

Migrating to v3

AML Single Check Flow

Use POST /aml/checks/ to screen a subject once without ongoing monitoring.

Create an AML Check

Submit a person or company for screening. The response includes a check ID and any matched profiles.

Create AML Check

POST /aml/checks/ — Screen a subject against sanctions, PEPs, and adverse media.

The response body includes a profiles array. Each entry contains a profileId you can use in the next step.

Retrieve a Matched Profile

Use the check ID and profile ID from the previous response to fetch the complete profile record — all sanctions entries, PEP tiers, and adverse media sources, regardless of the filters applied during the check.

Retrieve AML Profile

GET /aml/checks/{id}/profiles/{profileId}/ — Fetch full profile detail for a specific match.

Profile data is not filtered by the check’s configured datasets. Retrieve the full profile to see all available information for a matched entity.

AML Monitoring Flow

Monitoring is continuous screening — the system re-screens the entity daily and sends webhooks whenever status changes.

Create a Monitoring Record

Register a person or company for ongoing daily screening. The response returns a monitoringId used in all subsequent calls.

Create AML Monitoring

POST /aml/monitorings/ — Start ongoing screening with automatic status change alerts.

Use PATCH /aml/monitorings/{id}/ to extend the monitoring period or attach organizational tags.

Receive Webhook Alerts

The system fires an AML_MONITORING webhook each time the screening status changes. See the Webhook Reference above for the full payload and delivery details.

Retrieve Monitoring Status

Poll the monitoring record at any time to get the current status and latest results — useful for reconciling state if a webhook was missed.

Retrieve Monitoring

GET /aml/monitorings/{id}/ — Fetch a single monitoring record.

List All Monitored Entities

GET /aml/monitorings/ — List all monitoring records.

Manage the Monitoring Lifecycle

Pause, resume, or remove monitoring records as your compliance requirements change.

Start / Stop Monitoring

POST /aml/monitorings/{id}/stop/ or /start/ — Pause or resume without deleting.

Delete Monitoring

DELETE /aml/monitorings/{id}/ — Permanently remove a monitoring record.

To dismiss a specific false positive match without stopping monitoring, use DELETE /aml/monitorings/{id}/profiles/{profileId}/. See False Positive Handling above for details.

Generate a Compliance PDF (Optional)

Export the full screening history for a monitoring record as a PDF for audit trails and compliance records.

Generate Monitoring PDF

POST /aml/monitorings/{id}/pdf/ — Download a full-history PDF report.

Complete Migration Checklist

Use this as a final review before cutting over to v3. API endpoints:

v2 endpoint	v3 endpoint
`POST /api/v2/add-aml-user`	`POST /aml/monitorings/`
`POST /api/v2/get-monitoring-callback`	`GET /aml/monitorings/{id}/`
`POST /api/v2/get-aml-users`	`GET /aml/monitorings/`
`POST /api/v2/delete-monitoring-user/`	`DELETE /aml/monitorings/{id}/`
`POST /api/v2/generate-pdf-aml`	`POST /aml/monitorings/{id}/pdf/`
`POST /api/v2/add-whitelist`	No direct equivalent — see False Positive Handling

Request body — persons:

Combine name + surname → amlCheck.input.fullName
Rename type: "PERSON" → userType: "PERSON"
Move nationality → amlCheck.input.nationality
Move dateOfBirth → amlCheck.input.dateOfBirth
Remove monitorAdverseMedia — adverse media is not supported in v3
Rename autoExpirationExtension → isSubscribed

Request body — companies:

Rename name → amlCheck.input.companyName
Rename type: "COMPANY" → userType: "COMPANY"
Rename nationality → amlCheck.input.country

Webhook handler:

Read status instead of (or alongside) alertStatus
Update status value comparisons: ACCEPTED → ACTIVE, DECLINED → STOPPED
Store profileId from match entries if you support false positive dismissal

Existing monitoring records created via v2 remain accessible. v2 and v3 records coexist in the system — your historical data is not affected by migration.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Fraud Prevention

Bank Verification

Going Live

Reference

Overview

What Changed

Status Field Names

Request Body Fields

Datasets

False Positive Handling

Webhook Reference

Headers

Payload Fields

Migrating to v3

AML Single Check Flow

Create AML Check

Retrieve AML Profile

AML Monitoring Flow

Create AML Monitoring

Retrieve Monitoring

List All Monitored Entities

Start / Stop Monitoring

Delete Monitoring

Generate Monitoring PDF

Complete Migration Checklist

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Fraud Prevention

Bank Verification

Going Live

Reference

Documentation Index

​Overview

​What Changed

​Status Field Names

​Request Body Fields

​Datasets

​False Positive Handling

​Webhook Reference

​Headers

​Payload Fields

​Migrating to v3

​AML Single Check Flow

Create AML Check

Retrieve AML Profile

​AML Monitoring Flow

Create AML Monitoring

Retrieve Monitoring

List All Monitored Entities

Start / Stop Monitoring

Delete Monitoring

Generate Monitoring PDF

​Complete Migration Checklist

Overview

What Changed

Status Field Names

Request Body Fields

Datasets

False Positive Handling

Webhook Reference

Headers

Payload Fields

Migrating to v3

AML Single Check Flow

AML Monitoring Flow

Complete Migration Checklist