Person resource

Introduction

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

Step 1: Have a look at the API documentation

See the Person API documentation for further details about the API.

See also the Person API expands overview.

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 in 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 or implicit flow
Variant 2: End-user authentication embedded in BankID SDO that is the result of an individual signing a document with BankID in the legacy way via BankID Server	client credential grant flow
Variant 3: 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 and 3 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 Message flow details 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

End-user /

authorization code flow or implicit 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 Person
aml_person/NO_NATIONAL_REGISTRY	API access to response elements in Person API fetched from the Norwegian National Registry source.
aml_person/OFAC	API access AML search through Person API against The Office of Foreign Assets Control (OFAC) sanction list.

Note that the AML Person resource currently requires that the standard scope profile is also added in the scope list along with the other scopes.

Step 5: Query the resource

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 and ssn is fetched from the session associated to the access token in the request
BankID signature of individual	The name and ssn is picked from the BankID SDO that is included as a request parameter
Query parameters about name and ssn	The following query parameters must be included firstName lastName ssn countryOfSsn
Query parameters about name and birthdate	The following query parameters must be included firstName lastName dateOfBirth Note that the Norwegian national registry source is not supported by this variant because ssn is a required input parameter against that source

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.

In addition, the scope aml_person/NO_NATIONAL_REGISTRY is required in order to receive information from the Norwegian national registry source, and the scope aml_person/OFAC is required in order to trigger AML search against The Office of Foreign Assets Control (OFAC) sanction list.

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.	Norwegian National Registry
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	Norwegian National Registry
Historic Address	address.historic	List of historic addresses	Norwegian National Registry
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
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, and empty JSON node is returned to dictate that a search has been done.

LATEST PRE-PROD (OIDC)