Organization Async Session API implementation guide
- Kristoffer Kristoffer (Unlicensed)
- Markdown Macros for Confluence
- Kristoffer Skaret (Unlicensed)
- Janny Kinende
Contents
Introduction
The Asynchronous Session API is an alternative to the older synchronous API, and this will be the preferred integration choice in the time going forward.
New features such as international organization search again different countries like Sweden, Finland, and Denmark are only available in this API.
Technical advantages
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 asynchronous service will be able to deliver a successful response even for the more time-consuming requests. 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)
- Future extensions to this API may lead to more advanced behavior regarding disrupted requests
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:
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 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 one of the session endpoints.
Choose the right endpoint associated with the organization of interest:
| POST /organization/session/no |
| POST /organization/session/se |
| POST /organization/session/fi |
Use the identifier parameter to specify the organization with an organization number or a DUNS number.
Use the reports parameter to select what PDF reports to receive as a result.
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 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 Note that company information from a series of different countries is supported. The different countries have separate API endpoints and corresponding separate response models. The response models have some differences due to variations between countries, but they are also similar in a large matter. | 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
The following documentation is a detailed description of the response model for a Norwegian company. For other countries a similar but different response model is offered.
| 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.