Beneficial owners API implementation guide

Contents

Introduction

The beneficial owners service offers an asynchronous session API, similar to the organization async session API.

Summary of message flow

A typical message flow can be divided into three main parts:

1. Initialize the session
2. Receive webhook notifications
3. Retrieve result content

The following sequence diagram shows an example of this flow. Note that the usage of webhooks is not mandatory, and a different approach using a polling method is also possible.

Preparations

Have a look at the API documentation

Visit the Beneficial owners API documentation for detailed descriptions of the API.

API development and changes

There is no versioning system in this API, and the only available version is the latest and greatest.

Documentation of all changes to the API is continuously being published in the AML changelog.

As a rule of thumb, all changes are backward compatible. In general, this means that all new elements that are added will be categorized as nullable. Nothing will be removed or changed without notice.

When there is an exception to this rule, all integration partners will be informed in good time before the change takes place.

Gain access to the service

OIDC Clients must be provisioned to gain access to the service.

Anyone will get access to the test environment after submitting a request to the service desk.

About the access token

The API 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.

The following scope with corresponding API access are required.

Implementation

Part 1: Initialize the session

The session is initialized by creating a query and posting a request to the session endpoint.

Use the identifier parameter to specify the organization with an organization number or a DUNS number.

See the POST Session API documentation for further details about this request.

Check session status

When a session has been successfully created, a response with an assigned sessionId will immediately be delivered. This is the key to your session and it must be provided in all further requests about the session.

Make a request to the GET session information endpoint at any point in time to receive a JSON object with status information about the different result entities associated with the session.

Both the JSON data and the PDF report have a dedicated status descriptor. When a result entity is ready to download the corresponding status will be READY.

Part 2: Receive webhook notifications

A range of different webhooks is available to be sent with notifications about events. Which webhooks you want to receive is a choice in the session request.

Note that the usage of webhooks is not mandatory. If desired, a polling mechanism may be implemented instead to check the status of the session until the results are ready.

See the section about webhooks in the API documentation for information about how to consume these notifications.

Part 3: Retrieve result content

The result is a set of different entities:

Investigate the JSON response elements

See also the The beneficial owners report service page for a overview of the information elements provided.

Download the PDF reports

Use the link to the report as provided by the GET session endpoint.

The reports are digitally signed.