Organization Async Session API implementation guide



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:

  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.

client client Org session API Org session API Part 1: Initialize the session POSTCreate session 201 Created return sessionId GETGet session 200 OK Example response:jsonData: IN_PROGRESSaml-report: NOT_STARTEDwait Part 2: Receive webhook notifications POSTjsonData is ready 200 OK POSTreport is ready 200 OK POSTAll done 200 OK Part 3: Retrieve result content GETRetrieve JSON content 200 OK- Result entity GETRetrieve report 200 OK- PDF-report


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




API access to the Organization resource

aml_organization/OFACAPI access to The Office of Foreign Assets Control (OFAC) sanction list.


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 statusMeaning
JsonDataReadyThe JSON content is ready for download
ReportReadyA PDF report is ready for download
AllDoneThe session is finished, and all contents are ready for download
FailedSomething 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 entityDescriptionLifetime
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


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.

InformationJSON pathDetails
Key InformationkeyInformation

(delivered by default)

  • Company name
  • Org number
  • DUNS number
  • Organization type
  • Country
  • Registered date
  • Webpage
  • Employees
  • Member of registries
  • status code
  • institutional sector
  • industry sector
  • purpose
  • Sources
LEI numberkeyInformation.lei
  • Postal address
  • Visiting address
Financials: Accountingfinancials.accountingLast tree years
Financials: Key figuresfinancials.keyFiguresShare capital, turnover, operating profit, equity, earnings, sources, accounting years
Financials: Auditorfinancials.auditorName, org number, sources

Financials: Accountant

financials.accountantName, org number

Ownership: Beneficials


Name, address, owner share, date of birth, roles

Ownership: Subsidiaries


name, org number, percentage (owned by the company)

Ownership: Shareholdersownership.shareholders

name, org number, percentage, type (organization or person) 

Ownership: Indicatorsownership.indicators

A set of numbers describing the organisational structure.



Signature rights and power of procuration.



Roles delivered:

CEO, chairman, deputy chairman, proprietor, board members, deputy board members, contact person, company secretary, representative foreign entity, trustee



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:

  • Certificate of registration
  • AML

Empty nodes

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.

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.