Person resource
- Kristoffer Kristoffer (Unlicensed)
- Markdown Macros for Confluence
- Matheus Srebro
- Janny Kinende
Contents
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. |
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
One or both of the following parameter sets are also required
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:
|
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.