POST API

The POST API enables directing and storing forms that end users have filled in your organisation's e-service to Suomi.fi Messages. By doing so your organisation can supplement its form service without the need for an e-service that can store forms. At the same time, submitting forms becomes more secure.

The POST API functions according to the following:

The end user must have Suomi.fi Messages enabled, or they must activate the service before submitting the form.
The end user fills in the form you have defined in your e-service.
Submitting the form requires strong identification. If a person who does not have Suomi.fi Messages enabled attempts to submit the form, the submission will fail and they will receive an error message.
The form submitted by the end user is delivered to Suomi.fi Messages using the POST API.
The content of the form that is visible to the end user is stored in the end user’s electronic mailbox in Suomi.fi Messages.
The content of the form is then forwarded from Suomi.fi Messages to your organisation via the interface that supports the reply functionality you have enabled.

Please note that like the last point of the above list describes, the POST API must always be used alongside another interface that supports two-way messaging. This enables the delivery of the form's content to your organisation. The POST API is only used for directing the form to Suomi.fi Messages.

Due to the identification requirement an end user may not send forms on behalf of another party.

Using the POST API

The POST API is called by a POST call, for example an HTML form. The action parameter of the form is the address of the POST interface to be used. The actual data fields required by Suomi.fi Messages are fields inside the form, usually of the "hidden input" type. They are listed in Table 2.

The form also contains HTML form fields that are visible to the end user. Their type and other properties can be selected freely, as long as their names are not the same as the fields used by Suomi.fi Messages. The JavaScript code at the end of this article exports the contents of the visible HTML fields as an attachment that is sent along with the form.

The example in this instruction (at the bottom of the page) uses both a PDF and an XML attachment. If necessary, the attachment type could also be something else, such as DOC. The visibility of the attachment to the end user is configured in the TiedostoPiilotettu field. The attachment will always be delivered to your organisation even if it is not displayed to the end user.

The sent message must always contain at least one attachment. The maximum number of attachments is 10 and their combined maximum size is 10 Mb.

Table 1 lists the action addresses of the POST API in the testing and production environment. If the addresses require a separate identification, your organisation will be provided with the necessary credentials.

Environment	Address
The testing environment	https://viestilomake.qa.suomi.fi/form
The production environment	https://viestilomake.suomi.fi/form

Table 1. The action addresses of the POST interface.

POST form fields

Table 2 lists the POST form fields that are used in Suomi.fi Messages.

Field	Explanation	Type
ViranomaisTunnus	The ID used to identify your organisation, for example viranomainen_ws. The ID is given by Suomi.fi Messages.	string
PalveluTunnus	The ID used to identify your organisation's service, for example viranomainen_ws_palvelu. The ID is given by Suomi.fi Messages.	string
Nimeke	Form title	string
Kuvausteksti	A textual description of the content of the form. The actual content will be delivered as an attachment.	string
Paluuosoite	The URL address that serves as the return address of the POST API. Suomi.fi Messages adds a piece of information as a parameter to the URL return address. The parameter indicates whether the end user has sent the message or interrupted the sending at some point (Delivered=1 or 0).	string
PalaaAutomaattisesti	If the value of this flag is 1, the system will return automatically to the return address (if any) after the form has been sent	bit (0 or 1)
ViranomaisenEmail	The email address of your organisation to which the message can be routed. In use when the return channel is based on the SMTP API.	string
TiedostoNimi_1	Name of attachment 1	string
TiedostoSisalto_1	Contents of attachment 1 as a Base64 encoded string	string
TiedostoMuoto_1	MIME type of attachment 1	string
TiedostoPiilotettu_1	If the value of this flag is 1, attachment 1 is not shown to the end user in Suomi.fi Messages (for example the data of the form in xml format)	bit (0 or 1)
…	As above for possible attachments 2 – 9	-
TiedostoNimi_10	Name of attachment 10	string
TiedostoSisalto_10	Contents of attachment 10 as a Base64 encoded string	string
TiedostoMuoto_10	MIME type of attachment 10	string
TiedostoPiilotettu_10	If the value of this flag is 1, attachment 10 is not shown to the end user in Suomi.fi Messages (for example the data of the form in xml format)	bit (0 or 1)

Table 2. POST form fields used by Suomi.fi Messages.

The following section is an example how the data entered on a form can be sent as PDF and XML attachments.

This example is based on native JavaScript, which means that its functionality cannot be guaranteed in all browser versions. It can be used as a model for generating attachments from the contents of a feedback form. However, the code must always be ported to the used application as required by the application.

Please note! <script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js">> is a CDN address owned by a third party. In principle, the address could be used to attack the site. Therefore, the address is here for illustrative purposes only. The appropriate way is to install the library on your own server and make a reference to it.

<html>
<head>
  <meta charset="utf-8"/>
  <script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js"></script>
  <script>
    function b64EncodeUnicode(str) {
      return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,
 
      function toSolidBytes(match, p1) {
        return String.fromCharCode("0x" + p1);
      }));
    }
     
    function createB64EncodedPdf(header, feedback){
      var pdf = new jsPDF();
       
      pdf.setFontSize(22);
      pdf.text(20,20, "Palaute");
      pdf.setFontSize(20);
      pdf.text(20,30, header);
      pdf.setFontSize(16);
      pdf.text(20,50, feedback);
       
      return b64EncodeUnicode(pdf.output());
    }
     
    function createB64EncodedXml(header, feedback) {
      var xml = xmlTemplate(header, feedback);
      return b64EncodeUnicode(xml);
    }
 
    function xmlTemplate(header, feedback) {
      return "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
        "<palaute>"     +
          "<otsikko>"   +
            header      +
          "</otsikko>"  +
          "<viesti>"    +
            feedback    +
          "</viesti>"   +
        "</palaute>"
    }
     
    function setFileContents(pdfContent, xmlContent) {
      document.getElementById("TiedostoSisalto_1").value = pdfContent
      document.getElementById("TiedostoSisalto_2").value = xmlContent
    }
     
    function send() {
      var header = document.getElementById("header").value;
      var feedback = document.getElementById("feedback").value;
      var base64EncodedPdfAttachment = createB64EncodedPdf(header, feedback);
      var base64EncodedXmlAttachment = createB64EncodedXml(header, feedback);
 
      setFileContents(base64EncodedPdfAttachment, base64EncodedXmlAttachment);
 
      return true;
    }
  </script>
</head>
 
<body>
<h2>Palaute asioinnista</h2>
 
Otsikko:
<div>
  <input id="header" type="text" value=""/>
</div>
 
Palaute:
<div>
  <textarea id="feedback" rows="6" cols="100" value=""></textarea>
</div>
 
<div>
  <form id="postForm" action="https://viestilomake.qa.suomi.fi/form" method="post" onsubmit="send()">
    <input type="hidden" name="ViranomaisTunnus" id="ViranomaisTunnus" value="2574261-7" />
    <input type="hidden" name="PalveluTunnus" id="PalveluTunnus" value="Vaka" />
    <input type="hidden" name="Paluuosoite" id="Paluuosoite" value="http://example.com/?testParam=1" />
    <input type="hidden" name="ViranomaisenEmail" id="ViranomaisenEmail" value="foo.bar@example.com" />
     
    <input type="hidden" name="Nimeke" id="Nimeke" value="Palaute asiointilomakkeelta" />
    <input type="hidden" name="Kuvausteksti" id="Kuvausteksti" value="Lomakkeen sisältö" />
 
    <input type="hidden" name="TiedostoNimi_1" id="TiedostoNimi_1" value="palaute.pdf" />
    <input type="hidden" name="TiedostoSisalto_1" id="TiedostoSisalto_1" value="" />
    <input type="hidden" name="TiedostoMuoto_1" id="TiedostoMuoto_1" value="application/pdf" />
    <input type="hidden" name="TiedostoPiilotettu_1" id="TiedostoPiilotettu_1" value="0" />
     
    <input type="hidden" name="TiedostoNimi_2" id="TiedostoNimi_2" value="palaute.xml" />
    <input type="hidden" name="TiedostoSisalto_2" id="TiedostoSisalto_2" value="" />
    <input type="hidden" name="TiedostoMuoto_2" id="TiedostoMuoto_2" value="text/xml" />
    <input type="hidden" name="TiedostoPiilotettu_2" id="TiedostoPiilotettu_2" value="1" />
     
    <br />
    <input type="submit" value="Lähetä" />
  </form>
</div>
</body>
</html>

In the future, Suomi.fi Messages will only use the REST API and the POST API for electronic forms. The old APIs (WS, SFTP and SMTP) will be discontinued on 1 January 2027. The POST API used in Suomi.fi Messages forms always needs another API for it to pass the message to the organisation. In the future, this must be done with the REST API.

If your organisation currently receives Suomi.fi Messages forms by e-mail (e.g. to the registry’s e-mail address), you are using the SMTP API. After 1 January 2027, the forms will no longer be forwarded to your organisation’s email program as the API will no longer be used.

In the future, the forms will be directed straight to the system via the REST API, such as your organisation’s e-service portal or case management system. For more information on where the forms could be directed in the future after the API change, please contact the form service provider.

Updated: 2/1/2026

Digitalise your service path

Enhance information management

Improve service quality

Protect your data

Open, share and utilise data