Specifications for submission webserivce

The flow for a submission is:

1. If the submission contains documents, then these are first uploaded one by one through the documents endpoint. For each document uploaded you receive a documentId needed in the next step 
2. Select the endpoint that matches the legal framework and information type of the intended submission
3. Insert the list of documentId into the documents array. Insert values for the other attributes. Post the submission.
4. If there are errors found in first level validation these are returned within the ProblemDetails of the response given with return code 400 Bad Request.
5. If the submission is accepted then the return code 202 is the response and parte of the respone is the submissionId of the submission.
6. Use the Information service endpoint "status" together with the submissionId to check whether errors are found in second level validation or the submission is Processed.

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. We are now ready to go into Production with the present state.

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

We will continue to add to this API and only when adding breaking news will those endpoints become v2 or higher-

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.

List of file formats and reporting areas:  

• Submissions under the Prospectus Regulation: PDF, XBRL, XHTML, ZIP  
• Submissions under the Short Selling Regulation: no files  
• Submissions under the Transparency Directive:
  • Annual reports under Annual report: ESEF ZIP, XHTML. The ESEF ZIP contains XHTML, images and text
  • Other submissions: PDF, HTML, XHTML, ZIP containing XHTML, images and text

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 contains validations that either requires some analysis of the document content (e.g. data extractability) or validations 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 submissions that are passed onto ESAP undergoes a set of validations done by ESAP itself. Failure to pass these validations will be reported as a notification and can be read through one of the service endpoints.

Normally there should not be any errors since Finanstilsynets validations are similar to the ESAP validations.

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.