Contents
| Table of 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 most time-consuming requests will more often lead to the asynchronous service will be able to deliver a successful response in the asynchronous service. Even cases 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)
...
The Asynchronous Session API is an alternative to the older synchronous API.
...
- 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:
...
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 "Org 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
...
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
...
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 endpoint.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 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 documentationUse 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.
...
Make a request to the GET session information endpoint at at any point of in time to receive a JSON object with status information about the different result entities associated with 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 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"
| All the information requested from the service in a human-readable fashion. | 2 hours after availability | ||||
A PDF report "Certificate of registration" | A subset of the information necessary to fulfill the "Firmaattest" purpose. | 2 hours after availability |
Investigate the JSON response elements
| Info |
|---|
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.
| |||
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 |
| Info | ||
|---|---|---|
| ||
| Note that if a particular response element is requested (typically through expand parameter), but no information could be found in the source, an empty JSON node is returned to dictate that a search has been done. |
...