Person API implementation guide



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

Summary of the message flow

client client Person resource API Person resource API OIDC provider OIDC provider retrieve access-token The desired OIDC flow must be chosen first.Either authorization code flow or client-credentials-grant flow. access-token GETJSON content 200 OK- Result entity loop[Poll until reports are ready]wait x seconds GETreport 200 OK- PDF-report

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


Message flow / type of access token

Strongly confirmed BankID identity in AML response

Variant 1: BankID end-user authentication via OIDCauthorization code flow(tick)
Variant 2: Assessment of individuals (based on query parameters) without any associated identification with BankIDclient credential grant flow(error)

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 flowProcess

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




API access to the Person resource


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.

BankID OIDC authenticated individualThe 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



One or both of the following parameter sets are also required


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


request postal address and aml search result


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:

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
PDF reportlinks.reportsLink 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.