Contents

Introduction

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

Note that a new and more robust asynchronous alternative to this service is ready.

New integration partners must use the asynchronous alternative.

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 Organization resource:

API development and changes

There is no versioning system in this API, and the only available version is the latest and greatest.

Documentation about changes to the API is 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.

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: Get access token

The organization resource 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.

AML organization resource scopes

The following scopes with corresponding API access are supported.

Scope	Access
aml_organization/basic	API access to the Organization resource

Step 4: Query the resource

Make a GET request to the endpoint associated with the Organization 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 organizations have been prepared in the test environment (Current).

Specify the organization

Use either the organizationNumber parameter or the dunsNumber parameter.

Using the "expand" parameter

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

Example

/organization/?expands=address,roles,links.reports.aml

request address, roles, and link to AML PDF report

Step 5: Investigate the response elements

Information	JSON path	Details
Key Information	keyInformation	(delivered by default) Company name Org number DUNS number Organization type Country Registered date Webpage Employees Member of registries status code institutional sector industry sector purpose Sources
LEI number	keyInformation.lei
Addresses	address	Postal address Visiting address
Financials: Accounting	financials.accounting	Last tree years
Financials: Key figures	financials.keyFigures	Share capital, turnover, operating profit, equity, earnings, sources, accounting years
Financials: Auditor	financials.auditor	Name, org number, sources
Financials: Accountant	financials.accountant	Name, org number
Ownership: Beneficials	ownership.beneficials	Name, address, owner share, date of birth, roles
Ownership: Subsidiaries	ownership.subsidiaries	name, org number, percentage (owned by the company)
Ownership: Shareholders	ownership.shareholders	name, org number, percentage, type (organization or person)
Ownership: Indicators	ownership.indicators	A set of numbers describing the organisational structure.
Authorities	authorities	Here you will find: signature rights and power of procuration. See separate chapter for a guide about how to interpret the authorities response.
Roles	roles	Roles delivered: CEO, chairman, deputy chairman, proprietor, board members, deputy board members, contact person, company secretary, representative foreign entity, trustee
Sanction	sanction	Status, message (if no hit), matchIndicator, matchIndicatorDescription, aliasList, address, source (listname), data provider (source) Initial date, LastUpdate, list of Urls (to documents about the result).
PDF Reports: Certificate of registration AML	links.reports

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.

Step 6: Download the PDF reports

Two different PDF reports are supported.

Certificate of registration (firmaattest)
AML

If the request includes the expand parameters links.reports.aml or links.reports.certificate_of_incorporation these PDF reports will be available. The reports are signed. The AML report contains all the information returned from the service in a human-readable fashion, while the Certificate of registration contains the subset of the information necessary for this purpose.

A set of links to the reports are returned as response elements 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.

Browser not supported