Person resource

Introduction

This is a step-by-step guide for how to integrate with the AML Person resource API.

Summary of the message flow

Step 1: 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 Person 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 are 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.

Note that the old legacy Person API is still available in a deprecated stage until all existing customers have finished migration to the new API.

Step 2: 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.

Step 3: Choose the identification method

Three variants of the resource are available, where the first and second requires that the individual is first identified with BankID at the highest level of assurance.

Variant	Message flow / type of access token	Strongly confirmed BankID identity in AML response
Variant 1: BankID end-user authentication via OIDC	authorization code flow
Variant 2: Assessment of individuals (based on query parameters) without any associated identification with BankID	client credential grant flow

When using variant 1 the end user is directly referenced in the issued access token, which means the token contains everything the AML resource server needs to identify the individual.

When using variant 2 the token contains no information about the actual end-user. The client must instead provide the end-user identification through a separate request parameter in the API.

See grant types about the difference between the regular end-user OIDC flow (used in variant 1) and the client credential grant flow.

Step 4: Get access token

The service uses the default Access Token format of the OIDC Provider from BankID, adapted to either one of the end-user flows or the client credential grant flow. The Access Token must be added as a Bearer Token to subsequent requests to endpoints for the AML API.

Message flow	Process
authorization code flow (end-user flow)	Direct the end-user to the Authorize endpoint. Remember to include the necessary AML scopes in the request (see table below).
client credential grant flow	Invoke the Token endpoint using client credential grant and supply the appropriate scope values.

AML person resource scopes

The following scopes with corresponding API access are supported.

Scope	Access
aml_person/basic	API access to the Person resource
aml_person/OFAC	AML sanction search will include The Office of Foreign Assets Control (OFAC) sanction list.

Note that the AML Person resource requires that the standard scope profile is also added to the scope list along with the other scopes when using variant 1 of the identification method (BankID)

Step 5: Query the resource

Make a GET request to the endpoint associated with the Person AML resource.

See the following sections for descriptions of the different request parameters.

Client timeout recommendation

This synchronous service has been designed to always give a response (either successful or unsuccessful) within a time limit of 9 seconds. On the client-side, a timeout of 10 seconds is recommended.

Test data

Example test persons have been prepared in the test environment (Current).

Specify the individual

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

Method

Description

BankID OIDC authenticated individual

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

Query parameters

Required query parameters

firstName

lastName

One or both of the following parameter sets are also required

dateOfBirth

ssn
country

The following countries and ssn types are supported: NO, SE, DK, FI

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.

Using the "expand" parameter

By default, only a basic minor dataset with a few key information elements is returned. To select more data, the expand parameter must be provided in the request. Se Person API expand parameter documentation.

Example

/person?expands=address.postal,aml

request postal address and aml search result

Scopes

The scope aml_person/basic is a general requirement for the resource.

The scope aml_person/OFAC is required in order to trigger AML search against 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.

The "matchMode" parameter

Read more about "Exact mode or Fuzzy mode" in the product literature.

Step 6: Investigate the 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
PDF report	links.reports	Link to a signed PDF report containing the complete result set.

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.

Step 7: Download the PDF report

If the request included the expand parameter links.reports.aml a signed PDF report will be available. The report contains all the information returned from the service in a human-readable fashion.

A link to the report is returned as a response element inside the links.reports structure. The endpoint must be polled while the report is generated, and will return HTTP 202 until it is ready.

Important note: The PDF reports have a limited lifespan, and will only be available for a period of 10 minutes after the JSON response is ready.

LATEST PROD (OIDC)