Person Async Session API Implementation Guide

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.

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

Visit the BankID AML API documentation for detailed descriptions of the API.

The following sections are relevant for the Asynchronous Organization resource:

Person session 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 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_person/basic`	API access to the Person resource
`aml_person/OFAC`	API 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.

Implementation

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.

Method Description

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

Parameters

Use the identifier parameter to specify the indivdual.

Required parameters

firstName

lastName

One or both of the following parameters are also required

dateOfBirth

ssn

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

Investigate the JSON response elements

The following dataset is offered:

Information	JSON path	Details	Source
Key information	keyInformation	Personal data about the individual under assessment.	National Registry of Norway
Citizenship	keyInformation.citizenship	Citizenship of the individual	National Registry of Norway
BankID Identity	identity	Name, common name, and ssn of the individuals BankID certificate	BankID
Postal Address	address.postal	Address form Postal registry	Posten
National Address	address.national	Address from national registries	National Registry of Norway or Sweden
Historic Address	address.historic	List of historic addresses	National Registry of Norway
Number of residents	address.postal.numberOfResidents address.national.numberOfResidents	Type of housing, and number of residents on the given address.	Property register
AML	aml	Lists of possible PEP and Sanction results for the individual.	EU commission UN Security council Trapets OFAC
Roles	roles	A 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.

Contents