Organization API implementation guide

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

client client Organization resource API Organization resource API OIDC provider OIDC provider retrieve access-token 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 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 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

InformationJSON pathDetails
Key InformationkeyInformation

(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 numberkeyInformation.lei
Addressesaddress
  • Postal address
  • Visiting address
Financials: Accountingfinancials.accountingLast tree years
Financials: Key figuresfinancials.keyFiguresShare capital, turnover, operating profit, equity, earnings, sources, accounting years
Financials: Auditorfinancials.auditorName, org number, sources

Financials: Accountant

financials.accountantName, 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: Shareholdersownership.shareholders

name, org number, percentage, type (organization or person) 

Ownership: Indicatorsownership.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.