Contents
Introduction
The new asynchronous API has several advantages compared with the synchronous alternative.
- Robustness during periods of high traffic load.
- Improved handling of scenarios with an unusually long response time. In general, the asynchronous service will deliver a response just as fast as before. But an advantage is that the most time-consuming requests will more often lead to a successful response in the asynchronous service. Even cases previously disrupted by short term downtime can now be handled successfully with a delayed response.
- Webhook notifications, making polling unnecessary
- Batch support (coming later)
The Asynchronous Session API is an alternative to the older synchronous API.
- We will encourage all existing integration partners to migrate to the new asynchronous alternative
- New integration partners must only use the asynchronous API
Summary of message flow
A typical message flow can be divided into three main parts:
- Initialize the session
- Receive webhook notifications
- 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
See also the Organization API expands overview.
Visit the BankID AML API documentation for detailed descriptions of the API.
The following sections are relevant for the Asynchronous Organization resource:
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.
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 scopes with corresponding API access are supported.
Scope | Access |
|---|---|
aml_organization/basic | API access to the Organization resource |
aml_organization/OFAC | API access to The Office of Foreign Assets Control (OFAC) sanction list. |
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.
By default, only a basic dataset with key information elements is returned. To select more data, the expands parameter must be provided in the request. Se Organization API expand parameter documentation.
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 of time to receive a JSON object with status information about the different result entities associated with the session.
Both the JSON data and the different PDF reports all 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.
| 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.
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:
| Result entity | Description | Lifetime |
|---|---|---|
| The JSON response | Structured data | 2 hours after availability |
A PDF report "AML" OPTIONAL | All the information requested from the service in a human-readable fashion. | 2 hours after availability |
A PDF report "Certificate of registration" OPTIONAL | A subset of the information necessary to fulfill the "Firmaattest" purpose. | 2 hours after availability |
Investigate the JSON response elements
| Information | JSON path | Details |
|---|---|---|
| Key Information | keyInformation | (delivered by default)
|
| LEI number | keyInformation.lei | |
| Addresses | address |
|
| Financials: Accounting | financials.accounting | Last tree years |
| Financials: Key figures | financials.keyFigures | Share capital, turnover, operating profit, equity, earnings, sources, accounting years |
| Financials: Auditor | financials.auditor | Name, org number, sources |
Financials: Accountant | financials.accountant | Name, org number |
Ownership: Beneficials | ownership.beneficials | Name, address, owner share, date of birth, roles |
Ownership: Subsidiaries | ownership.subsidiaries | name, org number, percentage (owned by the company) |
| Ownership: Shareholders | ownership.shareholders | name, org number, percentage, type (organization or person) |
| Ownership: Indicators | ownership.indicators | A set of numbers describing the organisational structure. |
| authorities | Signature rights and power of procuration. See separate chapter for a guide about how to interpret the authorities response. | |
Roles | roles | Roles delivered: CEO, chairman, deputy chairman, proprietor, board members, deputy board members, contact person, company secretary, representative foreign entity, trustee |
Sanction | sanction | Status, message (if no hit), matchIndicator, matchIndicatorDescription, aliasList, address, source (listname), data provider (source) Initial date, LastUpdate, list of Urls (to documents about the result). |
PDF Reports:
| links.reports |
Empty nodes
Download the PDF reports
If the request includes the expands parameter values links.reports.aml or links.reports.certificate_of_incorporation these PDF reports will become available for download.
The reports are digitally signed.