Contents
| Table of Contents | ||
|---|---|---|
|
...
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.
| Macro diagram | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
@startuml actor client boundary "Beneficial owners session API" as session == Part 1: Initialize the session == client -> session: **POST** Create session activate session session --> client: //201 Created// note right: return sessionId client -> session: **GET** Get session session --> client: //200 OK// note right: Example response:\njsonData: IN_PROGRESS\naml-report: NOT_STARTED ...wait... == Part 2: Receive webhook notifications == session -> client: <font color=blue>**POST** jsonData is ready client --> session: //200 OK// session -> client: <font color=blue>**POST** report is ready client --> session: //200 OK// session -> client: <font color=blue>**POST** All done client --> session: //200 OK// ||| == Part 3: Retrieve result content == client -> session: **GET** Retrieve JSON content session --> client: //200 OK// - Result entity client -> session: **GET** Retrieve report session --> client: //200 OK// - PDF-report deactivate session @enduml |
Preparations
Have a look at the API documentation
...
The following scope with corresponding API access are required.
Scope | Access |
|---|---|
aml_organization/basic | API access to the Organization resource |
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.
| POST /beneficial/session/ |
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.
...
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.
| Webhook status | Meaning |
|---|---|
| JsonDataReady | The JSON content is ready for download |
| ReportReady | A PDF report is ready for download |
| AllDone | The session is finished, and all contents are ready for download |
| Failed | Something went wrong, and the session has been canceled. |
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.
...
The result is a set of different entities:
| Result entity | Description | Lifetime |
|---|---|---|
| The JSON response | Structured data | 2 hours after availability |
The PDF report | Human readable report including visual maps of of owner relationships | 2 hours after availability |
Investigate the JSON response elements
...