Continuous screening API implementation guide
Contents
Introduction
The service is implemented in the form of a monitor system, which is available through a collection of API endpoints.
This guide shows a brief walkthrough of the integration process.
Step 1: Have a look at the API documentation
See Monitor API documentation for detailed documentation.
The API documentation suffers from a bug affecting scrolling when presented through the Chrome browser. We recommend using a different browser until this issue is resolved.
Step 2: Gain access to the service
OIDC Clients must be provisioned to gain access to the AML service.
Anyone will get access to the test environment after submitting a request to the service desk.
Test simulator
In the test environment, a simulator is available as a test tool. See Continuous screening test simulator.
Step 3: Get access token
The continuous screening service uses the default Access Token format of the OIDC Provider from BankID, adapted to the client credential flow.
Eligible OIDC Clients can request Access Tokens for the AML Service by invoking the token endpoint using Client Credential Grant and supplying appropriate scope values. The Access Token must be added as an OAuth2 Bearer Token to subsequent requests to endpoints for the AML API.
AML continuous screening service scopes
The following scopes are required.
Scope | Access |
|---|---|
| aml_person/monitor | Access to the monitor API |
Step 4: Register the monitor
To be able to subscribe to notifications you must first make a request to create your monitor. Create a new monitor API reference.
An important attribute of the registration request is the webhook URL. This is the endpoint where you wish to receive the notifications.
| Parameter | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Webhook | The webhook url is the endpoint where you wish to receive the notifications. | ||||||||
| Name | Name of the monitor | ||||||||
| Template | The template controls what sanction lists the monitor will be connected to.
Note that access to the OFAC list is restricted and requires extra scope. |
Step 5: Add persons to the monitor
Next, the collection of individuals of your choice must be added to the monitor. There are different methods for how to populate or manipulate the list, such as batch file upload and POST JSON array.
Note about birthdate:
It is recommended to always include the dateOfBirth parameter, even if the ssn parameter is available, because of the following reasoning:
- If only the ssn parameter is included (omitting the explicit date of birth), the monitoring will be based on a birth date derived from the given ssn
- A birth date derived from a given ssn is not always correct. This is especially common if the ssn is a D-number.
- the ssn parameter is only mandatory when requesting information from the national registry source. In all other cases, the dateOfBirth is sufficient.
Step 6: Check status about the monitor
Make a request against the GET Monitor endpoint.
The response contains statistics about the collection of persons added to the monitors, such as how many have been added, how many have failed and so on.
Step 7: Receive notifications
The service will continuously monitor all registered individuals and trigger alerts whenever a state has changed, for instance, if a person has been added to a PEP- or Sanction-list.
Your system will be notified about such alerts through notifications send to the webhook endpoint. Notifications are sent out as soon as there are unhandled alerts registered on the monitor. This may happen at different points of time during the day. A notification contains information about the number of alerts, and what monitor triggered the alerts.
Step 8: Retrieve alerts
A request to the alerts endpoint is responded with a list of all unhandled alerts. Each alert has a unique ID.
Every time you make a request to this endpoint you will receive all unhandled alerts that are not yet marked as received (See step 9). Be sure to take care of this process flow to prevent any appearance of duplicates to the end-user.
Step 9: Mark alerts as received
Finally, a request must be made to mark the alert as received (stop notifications).
Monitor state flow
The state of a monitor can be inspected through the GET /monitor endpoint.
The state will change as described in the following diagram through the monitor's life cycle.