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

Access to information from Norwegian National Registry

Some information elements about each beneficial owner require customer access to the Norwegian National Registry. In order to gain this access, the client must have fulfilled the two-step application process.

A dedicated access rights API can be used to check the status of this access.

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.

Some information elements must be selected specifically through the usage of the expand parameter. More specifically this applies to citizenship and birthplace. Note that delegated access to the Norwegian National Registry is required.

(The information element identificationNumber / ssn is also possible, but requires even greater access).

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.