Specifications for the new OAM webserivce prepared for ESAP

The security of the ESAP API is OAuth based with a JWT token in Authorization header.

To get a token you need to be registered in our CIAM at Finanstilsynet thereby getting a Client-ID and a secret.

The token issuer endpoint is: 

https://login.microsoftonline.com/bbca25a8-2239-42d3-bf72-abe1833f3cb2/oauth2/v2.0/token

The scope for ESAP API is "api://esap-api/.default"

Sample:

POST https://login.microsoftonline.com/bbca25a8-2239-42d3-bf72-abe1833f3cb2/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded 

client_id={{clientId}}

&client_secret={{clientSecret}}

&grant_type=client_credentials

&scope=api://esap-api/.default

The revised OAM API is under development according to the OpenAPI standard. It is to a high degree Work in Progress and its present state is not ready for development, but it is an early example.

This is a link to the API in our test environment: Scalar API Reference.

We have started out by implementing a few of the TD submissions for Issuers. We are still operating with the working title ("ESAP API"), but when we go live this API will be the new OAM API.

Due to file-type requirements when transferring submissions to ESAP the same requirements will be upheld in the API.

All uploaded documents have to be either data-extractable or machine-readable. Data-extractable means that it is possible to automatically extract meaningful text from the document that is readable by humans. Machine-readable means formats structured so that software applications can easily identify, recognise and extract specific data, including individual statements of fact, and the internal structure of that data (essentially ESEF format in ESAP phase 1). 

Submissions are subjected to two passes of validations - one immediately and one after initial processing and just before registration. All validations have to be passed for submissions to be registered correctly. Failure to pass the first series of validations is reported immediately in the return result from the API, failure in the second pass is reported as a notification and can be read through one of the service endpoints.

Most validations are done in the first pass and are of the following types:

• Valid formats of data
• Valid type of submission for this type of company
• The submitter is allowed to submit for the designated company
• Valid dates according to present date
• Numbers are within the valid limits
• Valid identifiers

The second pass is containing validations that either requires some analyzes of the document content (e.g. data extractability) or validations ud against previous submissions (e.g. positions have to be on different dates). A submission has a state that reflects where in the process the submission is presently. 

The content of all submissions has to adhere to a declaration of possible use and re-use of the information. To avoid superfluous attributes in the API contract this declaration is implicit and the responsibility of ensuring correct entitlement to the use and re-use of information is placed on the user of the API.   

In the naming of the endpoints we are following the ESAP system names for the different information types. When needing an information type that is not part of ESAP we use the prefix "ft_".

The change in naming makes it sometimes less obvious what compares to what between the old OAM and the new.

The list below catches a few of the less obvious:

• Major shareholders also just called Shareholder
  • The submission by the major shareholders themselves is not part of the ESAP and is called "ft_mjshld". In the real old API it was not a possibility.
  • The submission by the issuer about major shareholders is called "mjshld", in the old it was also called Shareholder.
• Managers transactions (PDMR) also called Related party transactions
  • The submission by the managers themselves (or their related party) is not part of the ESAP and is called "ft_mantra". In the real old API it was not a possibility.
  • The submission by the issuer about managers transactions is called "mantra", in the old it was also called Related party transactions in some places.
• Acquisition or disposal of an issuer's own shares also called Own shares (system name: adiosh)

With the new OAM for ESAP we are introducing quite a few changes to the submission of Managers transactions (mantra and ft_mantra).

Already with the OAM from Dec 25 we introduced the possibility to submit the submission from the managers themselves. With that new capability came also the requirement of submitting all the data of the standard formular (PDMR) as structured data.

Now we are introducing a possibility of uploading those structured data as an .htm file following a pre-defined structure, so the data can be deserialized into a database.

With the OAM from Dec 25, we introduced a few changes to the submission of the shareholders own form (ft_mantra) apart from allowing it as an API submission.

With that new capability came also the requirement of submitting all the data of the standard formular as structured data.

Both the shareholders own form and the issuer pendant is adjusted a bit regarding how to identify the other part. We are relying on that we know the other part, and they are therefore identified by an identifier. 

With the new OAM for ESAP we are introducing a more divided API with separation of the different informationtypes and legal frameworks. Take-over bid is part of its own regulation (TBD) compared to Transparency Directive (TD) and is therefore separated from the others.

Part of this separation is also adhering to the nomenclature of TBD, why we introduce the terms offeror and offeree and that both should be identified.