Continuous screening API implementation guide



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.




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.

WebhookThe webhook url is the endpoint where you wish to receive the notifications.
NameName of the monitor

The template controls what sanction lists the monitor will be connected to.

ValueSearch lists
  • EU commission
  • UN Security council
  • EU commission
  • UN Security council
  • OFac
NotSetnot relevant

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.

CREATED IMPORT_STARTED ACTIVE The monitor is live and active! DELETE_STARTED DELETE_COMPLETED Create the monitor Start file upload Start adding single persons File upload completed Start deleting monitor All persons deleted from monitor Remove completely