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

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 Person session API Person 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

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 Person resource

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

Access to information from Norwegian National Registry

In order to receive information elements from the Norwegian National Registry data source, the client must have fulfilled the necessary application process.

A dedicated access rights API can be used to check the status of this access.


Part 1: Initialize the session

The session is initialized by creating a query and posting a request to the session endpoints:

POST /person/session/no

See the POST Session API documentation for further details about this request.

There are multiple methods for how to specify the individual to query information about.


BankID OIDC authenticated individual

Not yet supported

The name, birth date, and ssn (Norwegian only) is fetched from the BankID session associated with the access token in the request


Use the identifier parameter to specify the indivdual.

Required parameters



One or both of the following parameters are also required



Please note:

It is recommended to always include the dateOfBirth parameter, even if the ssn parameter is available, because of the following reasoning:

  • If only the ssn parameter is included (omitting the explicit date of birth), the search will be based on a birth date derived from the given ssn
  • A birth date derived from a given ssn is not always correct. This is especially common if the ssn is a Norwegian D-number.
  • the ssn parameter is only mandatory when requesting information from the national registry source. In all other cases, the dateOfBirth is sufficient.

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

2 hours after availability


All the information requested from the service in a human-readable fashion.2 hours after availability

Investigate the JSON response elements

The following dataset is offered:

InformationJSON pathDetailsSource
Key informationkeyInformation

Personal data about the individual under assessment.

National Registry of Norway

CitizenshipkeyInformation.citizenshipCitizenship of the individualNational Registry of Norway
BankID IdentityidentityName, common name, and ssn of the individuals BankID certificateBankID
Postal Addressaddress.postalAddress form Postal registryPosten
National Addressaddress.nationalAddress from national registriesNational Registry of Norway or Sweden
Historic Addressaddress.historicList of historic addressesNational Registry of Norway
Number of residents



Type of housing, and number of residents on the given address.Property register
AMLamlLists of possible PEP and Sanction results for the individual.

EU commission

UN Security council



RolesrolesA list of official roles the person has in different organizations.Brønnøysundregisteret

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.

BankID identity in AML response

A BankID identity may be used to identify the individual in question (see identification method above).

In this case, the information from this BankID identity is included as part of the response from the AML service.

In the PDF report the following elements are presented:

  • Timestamp (time of authentication)
  • Certificate serial number (serial number of the BankID certificate)
  • Organization (Issuer of the BankID certificate)
  • Organizational Unit (Organization number of the issuer)

The following elements are added to the JSON response:

  • originator (complete originator String, similar to the one delivered as part of the ID Token)
  • serialNumber (BankID serial number, similar to bankid_altsub in the ID Token)

Note that the PDF report is digitally signed, and it can suit as permanent proof of identification for storage purposes.

Download the PDF reports

Link to the PDF report is available in the response from the GET session endpoint.

The reports are digitally signed.