Integration Guide
A complete, step-by-step guide to integrating AML Name Screening and managing Cases, Alerts, and Ongoing Monitoring.
INTEGRATION FLOW
Account
Setup
Step 1
Dashboard
Config
Step 2
API
Integration
Steps 3–5
Review
Alerts
Step 6
Ongoing
Monitoring
Step 7
Before any configuration or API call, your Advance AI account manager must provision your account. During onboarding, confirm the following:
| Item | What to confirm |
|---|---|
| Dashboard access | Confirm login credentials and role assignments (Admin, Reviewer, etc.) for your compliance team. |
| API credentials | Receive your clientId and clientSecret for calling openapi.advance.ai. Both production and test environments share the same domain — environment is distinguished by account credentials. |
| Dashboard roles | Ensure team members are assigned appropriate roles: Super Admin / Workspace Admin (manage config) / Reviewer (review alerts) / Operator (view only). |
- Global AML Settings — Applies to all Levels by default. Set at Dashboard → Settings → Global AML Settings.
- Level AML Settings — Overrides Global settings for a specific Level. Set at Dashboard → Configuration → Levels → [Level] → AML Step.
2.1 — Create a Level with an AML Step
Go to Configuration → Levels
Navigate to Verification Levels → Individual. Click + Create Level or select an existing one. Give it a descriptive name such as "AML Only — Standard" or "KYC + AML — Premium".
Add an AML Step to the Level
In the Level editor, select the AML template to add AML Step. This Step is what triggers screening when an Application runs through this Level. You can also customise the Step combination (optional), e.g. place AML last in an eKYC + AML flow.
Configure AML settings for this Level
Click the AML Step to expand its configuration panel. Set the parameters described in section 2.2 below.
Save and Activate the Level
Click + Create Level to make the Level available for new Applications. Copy the levelId — you will need it in the API integration step.
2.2 — AML configuration parameters
| Parameter | Description | Vendor |
|---|---|---|
Enable Name Screening | Whether to enable AML watchlist screening for this Level | Enabled |
Ongoing Monitoring State | Set to Enabled, Disabled, or Default (inherits Global setting) | Enabled |
Auto Renew | Automatically renew Ongoing Monitoring at the end of each 365-day cycle to prevent gaps | true |
Rescreening Interval Days | Periodic re-screening interval in days (1–365). Only effective when Ongoing Monitoring is Disabled. | Not set |
3.1 — Authentication
accessToken. Include in all subsequent requests as Authorization: Bearer <accessToken>. Tokens expire periodically — implement a refresh mechanism in your integration.3.2 — Submit an AML Screening Application
externalUserId may only have one Initial Screening. If an active session already exists for that user, the API returns an error.4
3.2a — Manual screening via the Dashboard (no API needed)
For one-off screenings, compliance team members can create Applications directly in the Dashboard without any API integration:
Go to Manage → Applications (Individuals)
Navigate to the Applications list in the Dashboard.
Click "+ Create Application"
Click the button to open the creation form.
Select a Level
Choose the Level that contains the AML Step.
Fill in identity information
The form fields are determined by the selected Level. Fill in name, date of birth, nationality, and any other required fields.
Submit and view results
Click Create to submit. The AML Step runs asynchronously. Results appear in the Application detail view.
4.1 — Application status Lifecycle
| Status | Meaning | What happens next |
|---|---|---|
init | Application created; AML screening initializing | Application created and initialize the AML screening. |
pending | Application submitted; AML Step running | Wait for async processing. Use Webhook (recommended) or poll. |
onHold | AML Step found a potential match | A Case and Alert have been created. A compliance reviewer must resolve the Alert. |
completed | No match found, or all Alerts resolved as false positives | Application result = GREEN. Profile is updated with verified data. |
terminated | Application was cancelled, or AML Step encountered a technical failure | Retry the Application. A retry button is visible in the Application detail view. |
4.2 — Retrieve the AML Step Result from the Application
| Field | Description |
|---|---|
caseId | AML Case ID (prefix amlc-) — use this to query Case details |
alertType | SCREENING / UPDATE_SCREENING / RE_SCREENING / MONITORING |
alertStatus | OPEN / CLOSE / EXPIRED |
totalMatches | Number of matching records detected |
ongoingMonitoringStatus | enabled or disabled |
4.3 — Register a Webhook (recommended)
🔔 Avoid polling — use Webhooks
Register a Webhook endpoint at Dashboard → Settings → Webhooks and subscribe to these events:
Application Events
| eventType | Status | Trigger |
|---|---|---|
| APPLICATION_PENDING | init -> pending | Data submitted; verification in progress |
| APPLICATION_ON_HOLD | pending -> onHold | Awaiting manual review |
| APPLICATION_COMPLETED | -> completed | Verification complete; check reviewAnswer |
| APPLICATION_TERMINATED | -> terminated | Application cancelled |
AML Events
| eventType | Trigger | Description |
|---|---|---|
AML_OGS_UPDATE | Ongoing Monitoring detects a change | New or updated screening result found; review the new Alert |
⚠️ Webhook delivery is not guaranteed
Implement polling as a fallback (recommended interval: every 10 minutes or more). On failure, the system automatically retries 3 times (5s / 10s / 20s intervals).
5.1 — Case structure
Each Profile
has exactly
one
AML
Case
. All Alerts — from the initial screening and from Ongoing Monitoring — are aggregated into this single Case. All Alerts must be closed before the Case status can change.
5.2 — Match resolution workflow (Dashboard)
Find the flagged Application or Case
Navigate to Manage → Applications and filter by status onHold. Or go to AML → Cases and filter by status Open.
Review the Match details
Open the Alert and examine each Match: list name, match strength (WEAK / MEDIUM / STRONG), entity details (nationality, date of birth, positions held, sanctions sources).
Set the Resolution Status for each Match
For each Match in the Alert, set the Resolution Status:
- False — False Positive. The match is not the same person. Add a comment explaining why.
- Positive — True Positive. The match is confirmed. This will result in the Application being rejected (RED).
Close the Alert
Once all Matches have a Resolution Status, close the Alert. Enter a mandatory comment (required for audit trail). The Alert status changes to Closed.
Application result is updated automatically
- All Matches = False Positive → Application: completed (GREEN)
- Any Match = True Positive → Application: rejected (RED)
Case state machine
When a match is found, an AML Case is created with an OPEN parent state. The Case must be resolved by your compliance team before the Application can complete:
→ Application GREEN
→ Application RED
Reassignment rule:
Case can only be reassigned to a different compliance officer while in OPEN state. Once a Case is CLOSED (Approved or Rejected), it is a terminal state and cannot be manually reopened.
Match status classification
Each Match within an Alert must be individually classified. Classification is irreversible — once set, it cannot be changed:
| Status | Meaning | Effect |
|---|---|---|
Unresolved | Default — match not yet reviewed | Case remains OPEN |
False | Confirmed as a false positive. Entity is NOT the same as the watchlist entry | Does not contribute to rejection; cannot be reverted |
Positive | Confirmed as a true positive. Entity IS confirmed to be on the watchlist | Triggers Application rejection; cannot be reverted |
Mandatory audit notes:
Every Match status change requires the operator to add a comment. This is enforced by the platform and contributes to the immutable audit log (records operator, timestamp, before/after state, and comment for every action).
Case Operations via Dashboard
| Scenario | Navigation Path |
|---|---|
| Pick up a new Case from the queue | Case List → Check-in → Enter detail view |
| Dispatch a Case directly to a colleague | Case List → Select PENDING Case → Reassign → Select target → Add comment |
| Hand off mid-review to someone else | Case detail → Reassign → Select target → Add comment → Confirm |
| Submit final conclusion | Case detail → Submit → Select Approve / Reject → Add comment → Confirm |
| View your own Cases | Case List → My Cases tab → Filter by ASSIGNED status |
Case Audit Log
The system records every key event in the Case lifecycle. Navigate to Case Details → View Activity Log.
| Event Type | Recorded Information |
|---|---|
| Creation | Case source (Screening / Ongoing Monitoring) |
| Check-in | Officer who claimed the Case |
| Reassign | Previous assignee, new assignee, dispatcher, comment |
| Decision | Approve / Reject conclusion, submitter, comment |
| Status Change | Before and after state values |
Permission Reference
| Permission | Description |
|---|---|
case.view | View Case list and detail |
case.checkin | Check-in a PENDING Case |
case.submit | Submit a Case conclusion (Approve / Reject) |
case.reassign | Dispatch or re-assign a Case to another officer |
When Ongoing Monitoring is enabled in the Level configuration, Profiles that complete AML screening are automatically enrolled in continuous watchlist monitoring.
6.1 — Ongoing Monitoring Alert flow
AML database is updated
A change in the Database is detected that affects a monitored Profile and related matches.
New Alert created automatically
AdvanGuard creates a new Open Alert (Type: AML Ongoing Monitoring). If an existing Open Alert exists, it is moved to Expired. All prior resolution notes are inherited by the new Alert.
Case reverts to Open
The AML Case status automatically reverts to Open.
Compliance team reviews the new Alert
Follow the same Match resolution workflow as Step 5 above.
Profile-level Ongoing Monitoring toggle: A compliance team member can manually disable Ongoing Monitoring for an individual Profile from the Profile's AML tab in the Dashboard. Toggling OGS on and off within the same subscription period does not incur additional charges.
Irreversible:
Once an Alert reaches Reviewed status, it cannot be reverted to Pending Review or None.
AML APIs used in this guide
Click any endpoint to jump directly to its API reference documentation:
Updated 1 day ago