WS API
Please note that the old Suomi.fi Messages APIs are in maintenance mode, and no new functionalities are produced for them as a rule. All old APIs will be closed on 1 January 2027. This means that all services using Suomi.fi Messages must switch to the new REST interface before 2027.
Web Service (WS) is the most versatile of the old APIs. It supports both two-way messages and the paper mail option.
The WS API is split into the mandatory Official Services API and the voluntary Return Channel API. Your organisation can use the Official Services API to send messages and attachments to end users. The Return Channel enables Suomi.fi Messages to send message statuses to your organisation’s system as well as messages sent by end users.
The descriptions of the Official Services and Return Channel APIs are below. Please note that the message structure of the APIs follows the structure designed for the citizen's e-services account already in 2010. A few changes and additions have been made to the interface, but its interoperability with client organisations’ systems that use the old interface has been maintained. As a result, the message structure contains some old terminology associated with the e-services account.
The messages use UTF-8 encoding and their format is text/xml.
The details of taking the WS API into use are provided in the last expandable section.
The first WS API is called "Official Services". Your organisation can use the Official Services API to send messages and attachments to end users as well as check the status of the Suomi.fi Messages service or an end user's mailbox.
The API enables the use of four operations:
- LahetaViesti is an operation with which your organisation's system can send messages to end users, including messages that will be routed to paper mail if necessary.
- LisaaKohteita is an operation which allows your organisation to send electronic messages.
- HaeAsiakkaita is an operation with which your organisation’s system can check which of your customers have given their consent to electronic messaging in the Messages service.
- HaeTilaTieto is an operation with which your organisation's system can verify the status of the Messages service.
The interface's signed endpoint is /Asiointitili/ViranomaispalvelutWSInterface. The unsigned endpoint is /Asiointitili/ViranomaispalvelutWSInterfaceNonSigned.
Table 1 lists the operations and soapAction attributes of the Official Services interface.
Operation | SoapAction |
|---|---|
HaeAsiakkaita | http://www.suomi.fi/asiointitili/Viranomaispalvelut/HaeAsiakkaita |
HaeTilaTieto | http://www.suomi.fi/asiointitili/Viranomaispalvelut/HaeTilaTieto |
LahetaViesti | http://www.suomi.fi/asiointitili/Viranomaispalvelut/LahetaViesti |
LisaaKohteita | http://www.suomi.fi/asiointitili/Viranomaispalvelut/LisaaKohteita |
Table 1. The operations of the Official Services API and their soapAction attributes.
The first element in all queries sent through the Official Services interface is information about your organisation. The Viranomainen element that holds this information is described in Table 2.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> ViranomaisTunnus | The ID used to identify your organisation, for example viranomainen_ws. The ID is given by Suomi.fi Messages. | string | mandatory |
> PalveluTunnus | The ID used to identify your organisation's service, for example viranomainen_ws_palvelu. The ID is given by Suomi.fi Messages. | string | mandatory |
> KayttajaTunnus | User ID of the user who performed the run in the client organisation’s system, for example timakar | string | - |
> Yhteyshenkilo | Contact information to be contacted for example in case of errors. It is recommended to use an email alias. | element that is specified by attributes | - |
Yhteyshenkilo > Nimi | Contact name | attribute, string | - |
Yhteyshenkilo > Sahkoposti | Contact email address | attribute, string | mandatory, if using the LahetaViesti operation |
Yhteyshenkilo > Matkapuhelin | Contact mobile number | attribute, string | - |
> Osoite | Address information of your organisation | element that contains child elements | mandatory, if using the LisaaOsoitesivu feature of the LahetaViesti operation |
Osoite > Nimi | Name of your organisation | string | mandatory |
Osoite > Lahiosoite | Address of your organisation | string | mandatory |
Osoite > Postinumero | Postcode | string | mandatory |
Osoite > Postitoimipaikka | Town/city | string | mandatory |
Osoite > Maa | Country (FI) | string | mandatory |
> SanomaTunniste | Unique query ID, for example GUID1222888223 | string | mandatory |
> SanomaVersio | Version number of the message call, for example 1.0 | string | mandatory |
> SanomaVarmenneNimi | The Common Name of the certificate used by your organisation's system, for example Verohallinto | string | mandatory |
Table 2. The Viranomainen element that is required by all the operations of the Official Services API.
LahetaViesti is an operation by which your organisation's system can send end users messages that are delivered either electronically or by paper mail, depending on the state of the receiver's electronic mailbox. Therefore the use of LahetaViesti always requires a printing contract.
The PDF file belonging to the material to be sent is transmitted inside the query message, encoded in Base64. The maximum size for the file (message) is 10 Mb.
If a message is routed to paper mailing instead of electronic delivery, only the attachment of the message will be printed. In other words, all content of the message must be stored in the attached PDF file. Your organisation is responsible for ensuring that the sent material is suitable for paper mailing: the address information and the PDF file must adhere to the specifications of Posti's iPost-service. The specifications can be found in the Design instructions for sending letters (Posti)Opens in a new window..
The query message of the LahetaViesti operation
The control data of the message to be sent and the attachment in PDF format are placed in the Kohteet element. All content of the message to be sent must be stored in the attached PDF file. The message cannot be sent without an attachment.
Only one PDF attachment is allowed per recipient. If there is a need to send several documents in a single LahetaViesti message, they must be aggregated into a single PDF file.
A single query message can send messages to several recipients. In such a case, each recipient must have their own Kohde element and a separate PDF file for each recipient that contains the contents of the message to be sent. A single Kohde element cannot contain more than one recipient or attachment.
To ensure that the message can always be delivered (irrespective of the end user’s consent to electronic messaging), each message must contain both the personal identity code or business ID and the street address of the recipient. The Digital and Population Data Services Agency does not retrieve the street address from the Population Information System or the Business Information System, which means that your organisation must enter it in the Osoite section of the query message.
Table 3 presents the Kysely element of the query message of the LahetaViesti operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> Paperi | Controls the forced delivery of the message via paper mail. If the value is set to "true" the message will always be sent on paper, even if the recipient has an electronic mailbox. | boolean | - |
> Kohteet | Element which contains the targets | element that contains child elements | - |
Kohteet > Kohde | An element that aggregates the data from a single target | element that contains child elements | - |
Kohde > Asiakas | An element that contains the end user data | element that contains child elements and is specified by attributes | mandatory |
Asiakas > Asiakastunnus | End user's personal identity code or business ID. Business IDs are validated, but their existence is not checked against the Business Information System. | attribute, string | mandatory |
Asiakas > Sahkoposti | NO LONGER IN USE | attribute, string | - |
Asiakas > Matkapuhelin | NO LONGER IN USE | attribute, string | - |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | - |
Asiakas > Osoite | End user’s address | element that contains child elements | mandatory |
Osoite > Nimi | End user’s name | string | mandatory |
Osoite > Lahiosoite | Postal address | string | mandatory |
Osoite > Postinumero | Postcode | string | mandatory |
Osoite > Postitoimipaikka | Town/city | string | mandatory |
Osoite > Maa | Country code (FI) | string | mandatory |
Kohde > Viranomaistunniste | A unique identifier for the message in the authority's system. The identifier must be permanent and unique, for example a registration number. | string | mandatory |
Kohde > Viittaus | Used when the message is a response to an earlier message sent by an end user | element that is specified by attributes | - |
Viittaus > ViittausTunniste | Identifier of the associated matter | attribute, string | - |
Viittaus > ViittausTunnisteTyyppi | Identifier type of the related matter. Values: AsiointitiliTunniste or ViranomaisTunniste. | attribute, string | - |
Kohde > VahvistusVaatimus | A verifiable notification that requires an acknowledgment of being read (1 = yes, 0 = no) | int | - |
Kohde > VaadiLukukuittaus | The message forwarding service can be forced to send an acknowledgment message of an item, even if the sending of read acknowledgments were disabled (1 = yes, 0 = no) | int | - |
Kohde > AsiaNumero | E.g. decision number | string | - |
Kohde > Nimeke | Heading of the message, generated by your organisation’s system in the end user's own language | string | mandatory |
Kohde > LahetysPvm | Date on which the message has been sent | dateTime | mandatory |
Kohde > LahettajaNimi | A more specific name for your organisation | string | - |
Kohde > KuvausTeksti | A free-form description of the matter, i.e. contents of the message to be transmitted | string | mandatory |
Kohde > Tila | NO LONGER IN USE | element that contains child elements | - |
Kohde > Tiedostot | Associated documents, the content of the letter (PDF) can be entered here | element that contains child elements | mandatory |
Tiedostot > Tiedosto | An element that aggregates the data from a single file | element that contains child elements | mandatory |
Tiedosto > TiedostonKuvaus | Description of the content of the file | string | mandatory |
Tiedosto > TiedostoSisalto | The file encoded in Base64, maximum size 10 megabytes | base64Binary | mandatory |
Tiedosto > TiedostoMuoto | The file format (MIME Type), this value is always “application/pdf” | string | mandatory |
Tiedosto > TiedostoNimi | Name of file including the filename extension | string | mandatory |
Kohde > SmsLisatieto | NO LONGER IN USE | string | - |
Kohde > EmailLisatietoOtsikko | The heading of the notification that informs the end user about a new message in the Messages service. This content will be forwarded to the end user’s email. | string | - |
Kohde > EmailLisatietoSisalto | The content of the notification that informs the end user about a new message in the Messages service. This content will be forwarded to the end user’s email. | string | - |
Kohde > TavoitettavuusTietoSMS | NO LONGER IN USE | string | - |
Kohde > TavoitettavuusTietoEmail | NO LONGER IN USE | string | - |
Kohde > LisaaOsoitesivu | The first page of the attachment to be mailed must be an address page that contains the necessary sender and recipient information for the delivery of the letter. When you set the LisaaOsoitesivu option to "true", an address page with the necessary name and address information will automatically be created for the mailed letter. When using the address page creation, the complete address information of the sender is also mandatory in the Authority element of the message. The default value is "false". | boolean | - |
Kohde > SalliLiitteenKiertoPystyyn | The size of all pages of the mailable attachment must be A4 (portrait), and any larger pages will be automatically trimmed to that size. If you set the SalliLiitteenKiertoPystyyn option to "true", the system will attempt to detect and rotate any landscape pages before paper mailing. The default value is "false". | boolean | - |
> Tulostustoimittaja | The printing service supplier with which the client organisation has a printing agreement. At the moment only "Posti" is supported. | string | mandatory |
> LahetaTulostukseen (aikaisemmin LahetaOC) | NO LONGER IN USE | boolean | - |
> Laskutus | An element associated with the invoicing of printing | element that contains child elements | mandatory |
Laskutus > Tunniste | A service-specific TKJ-ID supplied to the printing service supplier | string | mandatory |
Laskutus > Salasana | A password associated with invoicing, if required by the printing supplier | string | - |
Laskutus > Kustannuspaikka | Identifier used for internal cost monitoring or allocation in the client organization. The identifier is 1-15 characters long, format [A-Z0-9]{1,15}. | string | - |
> Varitulostus | Colour printing, default is black and white | boolean | - |
Table 3. The query element of the LahetaViesti operation and the elements it contains.
The response message of the LahetaViesti operation
The LahetaViesti query sends a response message (LahetaViestiResponse), when the material (messages) has been stored in the processing queue of Suomi.fi Messages, from which the messages are delivered electronically or routed to paper mailing. If the material cannot be sent or further processing fails, a separate notification is sent to the email address of the contact person specified in the Viranomainen element of the LahetaViesti message (the Sahkoposti field of the Yhteyshenkilo element). The email message describes the reason for the failure in more detail.
Table 4 presents the LahetaViestiResponse element of the response message of the LahetaViesti operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> LahetaViestiResult | An element that aggregates the response message results | element that contains child elements | mandatory |
LahetaViestiResult > TilaKoodi | Status information of the response | element that contains child elements | - |
Tilakoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the TilaKoodiKuvaus description field. Codes that describe successful actions:
Virhekoodit:
In addition, a SOAP Fault can be returned in other errors (such as platform-level errors). Immediate resending of the message is unnecessary. | int | mandatory |
Tilakoodi > TilaKoodiKuvaus | Description field for error code. For example, ViranomaisTunniste already contains a message stored in the customer’s account in the Messages service. | string | - |
Tilakoodi > SanomaTunniste | The unique ID data for the query that can be used, for example, to examine data in the log | string | - |
Table 4. The LahetaViestiResponse element of the response message of the LahetaViesti operation and the elements it contains.
LisaaKohteita is an operation by which your organisation’s system can send messages and notifications to Suomi.fi Messages and receive responses to the queries. Sent messages can contain links to documents that are in your organisation's cache or entire documents that are saved in Suomi.fi Messages' own cache.
A sent message may be attached to an existing message in Suomi.fi Messages, in which case the message is visible to the end user in connection with the existing message (e.g. request for additional information or a response to a question).
Your organisation must assign an identifier for each message. The identifier must be unique within your organisation’s service, irrespective of time and date.
The response to the query can contain storage data for the sent messages separately for each end customer (synchronous) or simply a confirmation that the messages have been received (asynchronous). The communication type can be selected separately for each client organisation when connecting to the service.
The LisaaKohteita operation is only suitable for sending electronic messages. If the end user has not given their consent to electronic messaging and the messages must be mailed on paper, use the LahetaViesti operation.
Please note! An attachment belonging to the message to be sent is transmitted inside the query message, encoded in Base64. The maximum size for the file (message) is 10 Mb.
The query message of the LisaaKohteita operation
Table 5 presents the Kysely element of the query message of the LisaaKohteita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> KohdeMaara | The number of items sent | int | mandatory |
> Kohteet | Element that compiles the items | element that contains child elements | - |
Kohteet > Kohde | An element that compiles data on one item | element that contains child elements | - |
Kohde > Asiakas | Information on the end user related to the message. The message can be sent to only one end user at a time. | element that contains child elements and is specified by attributes | mandatory |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID. Business IDs are validated, but their existence is not checked against the Business Information System. | attribute, string | mandatory |
Asiakas > Sahkoposti | NO LONGER IN USE | attribute, string | - |
Asiakas > Matkapuhelin | NO LONGER IN USE | attribute, string | - |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | - |
Asiakas > Osoite | End user’s address | element that contains child elements | - |
Osoite > Nimi | End user’s name | string | mandatory |
Osoite > Lahiosoite | Postal address | string | mandatory |
Osoite > Postinumero | Postcode | string | mandatory |
Osoite > Postitoimipaikka | Town/city | string | mandatory |
Osoite > Maa | Country code (FI) | string | mandatory |
Kohde > ViranomaisTunniste | A unique identifier for the message in the authority's system. The identifier must be permanent and unique, for example the combination of the name of the sending service + receiver + senderLetterID is globally unique. The maximum length is 256 characters. | string | mandatory |
Kohde > Viittaus | Used when the message is a response to an earlier message sent by an end user | element that is specified by attributes | - |
Viittaus > ViittausTunniste | Identifier of the associated matter | attribute, string | mandatory |
Viittaus > ViittausTunnisteTyyppi | Identifier type of the related matter. Values: AsiointitiliTunniste or ViranomaisTunniste. | attribute, string | mandatory |
Kohde > VahvistusVaatimus | A verifiable notification that requires an acknowledgment of being read (1 = yes, 0 = no) | int | - |
Kohde > VaadiLukukuittaus | The message forwarding service can be forced to send an acknowledgment message of an item, even if the sending of read acknowledgments were disabled (1 = yes, 0 = no) | int | - |
Kohde > AsiaNumero | E.g. decision number | string | - |
Kohde > Nimeke | Heading of the message, generated by the client organisation’s system in the end user's own language | string | mandatory |
Kohde > LahetysPvm | Date on which the message has been sent | dateTime | mandatory |
Kohde > LahettajaNimi | A more specific name for the client organisation that has sent the message | string | - |
Kohde > KuvausTeksti | A free-form description of the matter, i.e. contents of the message to be transmitted. If the message type is a notification message, the entire content of the message is also forwarded as a notification email and to device push notifications for those using the mobile application. | string | mandatory |
Kohde > Maksullisuus | NO LONGER IN USE | int | - |
Kohde > MaksamisKuvausTeksti | NO LONGER IN USE | string | - |
Kohde > Tila | NO LONGER IN USE | element that contains child elements | - |
Kohde > Tiedostot | The attachments related to the message | element that contains child elements | - |
Tiedostot > Tiedosto | An element that aggregates the data from a single attachment | element that contains child elements | - |
Tiedosto > TiedostonKuvaus | Description of the attachment | string | - |
Tiedosto> TiedostoURL | The URL where the attachment can be downloaded, if the client organisation’s own cache is being used | string | - |
Tiedosto > TiedostoSisalto | The file encoded with Base64 | base64Binary | - |
Tiedosto > TiedostoKoko | The file size in kilobytes | string | - |
Tieodosto > TiedostoMuoto | File format (MIME Type), for example “application/pdf” | string | - |
Tiedosto > TiedostoNimi | Name of the file including the filename extension | string | mandatory, if a file has been attached |
Kohde > ViranomaisenEmail | Email interface: One or more email addresses separated with a semicolon (if the reply-to field is different). Messages are sent to all the addresses. | string | - |
Kohde > SmsLisatieto | NO LONGER IN USE | string | - |
Kohde > EmailLisatietoOtsikko | The heading of the notification that informs the end user about a new message in Suomi.fi Messages. This content will be forwarded to the end user’s email. | string | - |
Kohde > EmailLisatietoSisalto | The content of the notification that informs the end user about a new message in Suomi.fi Messages. This content will be forwarded to the end user’s email. | string | - |
Kohde > TavoitettavuusTietoSMS | NO LONGER IN USE | string | - |
Kohde > TavoitettavuusTietoEmail | NO LONGER IN USE | string | - |
Kohde > Viestityyppi | Normal message = 1 (default if no message type was given), notification message = 2 | int | - |
Table 5. The query element of the LisaaKohteita operation and the elements it contains.
The response message of the LisaaKohteita operation
Table 6 presents the LisaaKohteitaResponse element of the response message of the LisaaKohteita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> LisaaKohteitaResult | An element that aggregates the response message results | element that contains child elements | mandatory |
LisaaKohteitaResult > TilaKoodi | Status information of the response | element that contains child elements | - |
TilaKoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the error code's explanation field. Codes that describe successful actions:
Error codes:
In addition, a SOAP Fault can be returned in other errors (such as platform-level errors). | int | mandatory |
Tilakoodi > TilaKoodiKuvaus | Description field for error code. For example, the KohdeMaara in the query does not correspond with the number of items in the query. | string | - |
Tilakoodi > SanomaTunniste | The unique ID data for the message that can be used, for example, to examine data in the log | string | - |
LisaaKohteitaResult > KohdeMaara | The number of matters processed | int | - |
LisaaKohteitaResult > Kohteet | Element that compiles processed messages | element that contains child elements | - |
Kohteet > Kohde | An element that compiles data on one message | element that contains child elements | - |
Kohde > ViranomaisTunniste | A unique identifier for the message in the client organisation’s system, the same as in the query message | string | - |
Kohde > Asiakas | Information on the end user related to the message. The message is delivered to the end user's electronic mailbox in Suomi.fi Messages. | element that contains child elements and is specified by attributes | - |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID. Business IDs are validated, but their existence is not checked against the Business Information System. | attribute, string | - |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | - |
Asiakas > AsiointitiliTunniste | A unique identifier for the message that Suomi.fi Messages has issued for the message. AsiointitiliTunniste is an end-user-specific identifier for a message. | string | - |
Asiakas > KohteenTila | Processing status of the query storing operation. The processing status is returned separately for each end user. Success statuses (the message has been stored in Suomi.fi Messages):
Failure statuses (the message has not been stored in Suomi.fi Messages):
| int | mandatory |
Asiakas > KohteenTilaKuvaus | A more detailed description of the error. For example, if the error concerns an attachment, the file name is stated here. | string | - |
Table 6. The LisaaKohteitaResponse element of the response message of the LisaaKohteita operation and the elements it contains.
HaeAsiakkaita is an operation by which your organisation’s system can check which of your customers have given their consent to electronic messaging in Suomi.fi Messages. The check can be performed on individual personal identity codes or business IDs or on all of your customers.
The response message contains information that indicates whether the end user has an electronic mailbox in Suomi.fi Messages.
The query accepts restrictions based on time, so that it only retrieves the end users who have adopted Suomi.fi Messages within a given time period.
The query is controlled by the KyselyLaji element in the query message (see Table 7), the allowed values for the element are Kaikki, Asiakkaat and TilaMuutos.
The reply message to a Kaikki or TilaMuutos query contains data of a maximum of 1000 end users. If the reply message contains data on exactly 1000 end users, the number of end users that meet the query criteria is greater. In this case, your organisation must perform a new search in which the value of the KyselynAlku attribute is the TilaPvm of the last end user in the reply message of the previous query. This procedure is then repeated until the reply message contains data on fewer than 1000 end users.
The query message of the HaeAsiakkaita operation
Table 7 presents the Kysely element of the query message of the HaeAsiakkaita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> KyselyLaji | The defining element of a query type. The allowed values are:
If you use the query type Kaikki, the KyselyAlku and KyselyLoppu elements must contain data. If you use the query type Asiakkaat, the Asiakkaat element must contain the IDs to be checked. If you use the query type TilaMuutos, the KyselyAlku and KyselyLoppu elements must be filled in. | string | - |
> KyselyAlku | If this element is given, the query only returns
| dateTime | mandatory when using the query type Kaikki tai TilaMuutos |
> KyselyLoppu | If this element is given, the query only returns
| dateTime | mandatory when using the query type Kaikki tai TilaMuutos |
> Asiakkaat | This element aggregates end users when the query contains a list of end users to be retrieved | element that contains child elements | Mandatory when using the query type Asiakkaat. Not used if using the query type TilaMuutos. |
Asiakkaat > Asiakas | Element that aggregates the data of one end user | element that is specified by attributes | - |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID. Business IDs are validated, but their existence is not checked against the Business Information System. | attribute, string | mandatory |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | mandatory |
Table 7. The query element of the HaeAsiakkaita operation and the elements it contains.
The response message of the HaeAsiakkaita operation
Table 8 presents the HaeAsiakkaitaResponse element of the response message of the HaeAsiakkaita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> HaeAsiakkaitaResult | An element that aggregates the response message results | element that contains child elements | mandatory |
HaeAsiakkaitaResult > TilaKoodi | Element summarising the status data of a response message | element that contains child elements | - |
Tilakoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the error code's explanation field. Codes that describe successful actions:
Error codes:
In addition, a SOAP Fault can be returned in other errors (such as platform-level errors). | int | mandatory |
Tilakoodi > TilaKoodiKuvaus | Description field for error code. Example: ViranomaisTunnus does not correspond to the authentication data. | string | - |
Tilakoodi > SanomaTunniste | The unique ID data for the query that can be used, for example, to examine data in the log | string | - |
HaeAsiakkaitaResult > Asiakkaat | An element that aggregates the end users | element that contains child elements | - |
Asiakkaat > Asiakas | Element that aggregates the data of one end user | element that contains child elements and is specified by attributes | - |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID. Business IDs are validated, but their existence is not checked against the Business Information System. | attribute, string | - |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | - |
Asiakas > Tila | End user status information
| int | mandatory |
Asiakas > TilaPvm | Kaikki and Asiakkaat query types: The timestamp of the change to the end user’s data in Suomi.fi Messages. TilaMuutos query type: The timestamp of the latest change to the status of the end user. | dateTime | mandatory |
Asiakas > TiliPassivoitu | Field for additional information. Indicates whether the end user has inactivated their electronic mailbox in Suomi.fi Messages. If the mailbox is inactivated, the value is 1. Otherwise it is always 0. | int | mandatory |
Table 8. The HaeAsiakkaitaResponse element of the response message of the HaeAsiakkaita operation and the elements it contains.
HaeTilaTieto is an operation by which your organisation’s system can verify the status of Suomi.fi Messages.
The query message of the HaeTilaTieto operation
Table 9 presents the Kysely element of the query message of the HaeTilaTieto operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
Kysely | Empty element, does not contain any data | - |
Table 9. The query element of the HaeTilaTieto operation.
The response message of the HaeTilaTieto operation
Table 10 presents the HaeTilaTietoResponse element of the response message of the HaeTilaTieto operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> HaeTilaTietoResult | An element that aggregates the response message results | element that contains child elements | mandatory |
HaeTilaTietoResult> TilaKoodi | Status information of the response | element that contains child elements | - |
Tilakoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the error code's explanation field. Codes that describe successful actions:
Error codes:
In addition, a SOAP Fault can be returned in other errors (such as platform-level errors). | int | mandatory |
Tilakoodi > TilaKoodiKuvaus | Description field for error code | string | - |
Tilakoodi > SanomaTunniste | The unique ID data for the query that can be used, for example, to examine data in the log | string | - |
Table 10. The HaeTilaTietoResponse element of the response message of the HaeTilaTieto operation and the elements it contains.
The second WS API is called "Return Channel". The Return Channel enables Suomi.fi Messages to send message statuses to your organisation’s system as well as messages sent by end users. Using the Return Channel is voluntary.
Your organisation specifies the address of the interface and reports it to Suomi.fi Messages.
The API enables the use of two operations:
- VieKohteita delivers the message sent by an end user to your organisation's system.
- VieKohdeTiloja delivers message statuses to your organisation's system.
Table 11 lists the operations' soapAction attributes.
Operation | SoapAction |
|---|---|
VieKohteita | http://www.suomi.fi/asiointitili/ViranomaisPaluukanava/VieKohteita |
VieKohdeTiloja | http://www.suomi.fi/asiointitili/ViranomaisPaluukanava/VieKohdeTiloja |
Table 11. The operations of the Return Channel API and their soapAction attributes.
The Return Channel URL, i.e. the URL of your organisation's system is transmitted in the header of the SOAP message (see Table 12).
Parameter | Description | Type |
|---|---|---|
paluukanavaUrl | The URL of your organisation's system | string |
Table 12. The PaluuKanavaURL element, which is used to transmit your organisation's system's URL.
The first element in each message sent through the Return Channel interface must contain information about your organisation. The Viranomainen element that aggregates this information is described below in Table 13.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> ViranomaisTunnus | The ID used to identify your organisation, for example viranomainen_ws. The ID is given by Suomi.fi Messages. | string | mandatory |
> PalveluTunnus | The ID used to identify your organisation's service, for example viranomainen_ws_palvelu. The ID is given by Suomi.fi Messages. | string | mandatory |
> KayttajaTunnus | User ID of the user who performed the run in the client organisation’s system, for example timakar | string | - |
> SanomaTunniste | Unique query ID, for example GUID1222888223 | string | mandatory |
> SanomaVersio | Version number of the message call, for example 1.0 | string | mandatory |
> SanomaVarmenneNimi | The Common Name of the certificate used by your organisation's system, for example Verohallinto | string | mandatory |
Table 13. The Viranomainen element that is required by all the operations of the Return Channel API and which contains the details of your organisation.
The Return Channel API supports acting on behalf of another party from version 2.0 onward. This means that a person may act on behalf of another person or company, in which case they are referred to as an agent. The personal identity code and name of the agent are delivered in the Asiakas element, but only when using the VieKohteita operation.
The information regarding the used API version is saved in the same place as other specifications about clients and services. Even if 2.0 has not been specified as the used version, the SanomaVersio element of the Viranomainen element holds information about possible acting on behalf of another party. Version 2.0 is compatible backwards.
The VieKohteita operation delivers the message sent by an end user to your organisation's system.
Attachments within the message must be Base64-encoded. Maximum total size of all attachments is 10 Mb.
The query message of the VieKohteita operation
Table 14 presents the Kysely element of the query message of the VieKohteita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> KohdeMaara | The number of messages sent | int | mandatory |
> Kohteet | Element that compiles the messages | element that contains child elements | - |
Kohteet > Kohde | An element that compiles data on one message | element that contains child elements | - |
Kohde > Asiakas | Information on the end user related to the message | element that is specified by attributes | mandatory |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID | attribute, string | mandatory |
Asiakas > Sahkoposti | NO LONGER IN USE | attribute, string | - |
Asiakas > Matkapuhelin | NO LONGER IN USE | attribute, string | - |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | - |
Asiakas > PuolestaAsioijanTunnus | The personal identity code of the agent, if they sent the message on the end user's behalf | attribute, string | - |
Asiakas > PuolestaAsioijanNimi | The name of the agent, if they sent the message on the end user's behalf | attribute, string | - |
Kohde > Asiointitilitunniste | A unique identifier that Suomi.fi Messages has issued for the message | string | - |
Kohde > Viittaus | A reference to another message. Can be used for forming message chains. | element that contains child elements | - |
Viittaus > Viittaus_WS | Aggregates the reference | element that is specified by attributes | - |
Viittaus_WS > ViittausTunniste | Identifier of the associated message | attribute, string | mandatory |
Viittaus_WS > ViittausTunnisteTyyppi | Identifier type of the related message. Values: AsiointitiliTunniste or ViranomaisTunniste. | attribute, string | mandatory |
Kohde > Nimeke | The header of the message | string | mandatory |
Kohde > LahetysPvm | Date on which the message has been sent | dateTime | mandatory |
Kohde > LahettajaNimi | The name of the sender | string | - |
Kohde > Kuvausteksti | A free-form description of the matter | string | - |
Kohde > Tiedostot | The attachments related to the message | element that contains child elements | - |
Tiedostot > Tiedosto | An element that aggregates the data from a single attachment | element that contains child elements | - |
Tiedosto > TiedostonKuvaus | An element that aggregates the data from a single attachment | string | - |
Tiedosto > TiedostoURL | The URL where the document can be downloaded, if the client organisation’s own cache is being used | string | - |
Tiedosto > TiedostoSisalto | The file encoded with Base64 | base64Binary | - |
Tiedosto > TiedostoKoko | The file size in kilobytes | string | - |
Tiedosto > TiedostoMuoto | File format (MIME Type) | string | - |
Tiedosto > TiedostoNimi | Name of the file including the filename extension | string | - |
Kohde > ViranomaisenEmail | Email interface: One or more email addresses separated with a semicolon (if the reply-to field is different). Messages are sent to all the addresses. | string | - |
Table 14. The query element of the VieKohteita operation and the elements it contains.
The response message of the VieKohteita operation
Table 15 presents the VieKohteitaResponse element of the response message of the VieKohteita operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> VieKohteitaResult | An element that aggregates the response message results | element that contains child elements | - |
VieKohteitaResult > TilaKoodi | Element summarising the status data of a response message | element that contains child elements | - |
TilaKoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the error code's explanation field. Suomi.fi Messages will retry sending the message if the status code return is other than 0 or 400-449. Codes that describe successful actions:
Error codes:
| int | mandatory |
TilaKoodi > TilaKoodiKuvaus | Description field for error code. For example, the KohdeMaara in the query does not correspond with the number of items in the query. | string | - |
TilaKoodi > SanomaTunniste | The unique ID data for the query that can be used, for example, to examine data in the log | string | - |
VieKohteitaResult > KohdeMaara | The number of messages processed | int | mandatory |
VieKohteitaResult > Kohteet | An element that aggregates the processed messages; the data is the same as in the query message | element that contains child elements | mandatory |
Kohteet > Kohde | An element that compiles data on one message | element that contains child elements | mandatory |
Kohde > AsiointitiliTunniste | A unique identifier that Suomi.fi Messages has issued for the message | string | - |
Kohde > ViranomaisTunniste | A new unique identifier for the message in your organisation’s system, which is not the same as in the query messages ViranomaisTunniste Viittaus-element. Suomi.fi Messages saves this for further use in the Viittaus element and for forming up message chains. | string | - |
Kohde > KohteenTila | Processing status of the query storing operation. Suomi.fi Messages will not retry sending the message if the status code return is a failure. Successful statuses:
Failure statuses:
| int | mandatory |
Kohde > KohteenTilaKuvaus | A more detailed description of the error. For example, in the case of an error related to the attached file, the name of the file. | string | - |
Table 15. The VieKohteitaResponse element of the response message of the VieKohteita operation and the elements it contains.
The VieKohdeTiloja operation delivers message statuses to your organisation's system.
Statuses can arrive to the authorities system in random order. Therefore, for example, the receipt for verifiable notification can arrive before the read status. The KohteenTilaPvm timestamp indicates when the status of the message has changed and which one of the status changes is the latest one.
The query message of the VieKohdeTiloja operation
Table 16 presents the Kysely element of the query message of the VieKohdeTiloja operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> KohdeMaara | The number of messages sent | int | mandatory |
> Kohteet | Element that compiles the messages | element that contains child elements | - |
Kohteet > Kohde | An element that compiles data on one message | element that contains child elements | - |
Kohde > ViranomaisTunniste | A unique identifier for the message in your organisation's system. The identifier must be permanent and unique. This is the same identifier as in the LahetaViesti/LisaaKohteita operations and identifies which one of the messages you sent the status change concerns. | string | - |
Kohde > Asiakas | Information on the end user related to the message | element that contains child elements and is specified by attributes | - |
Asiakas > AsiakasTunnus | End user's personal identity code or business ID | attribute, string | mandatory |
Asiakas > TunnusTyyppi | "SSN" for natural persons, "CRN" for companies | attribute, string | mandatory |
Asiakas > AsiointitiliTunniste | The identifier with which the message your organisation send was identified in Suomi.fi Messages. If the end user replies to the message, this identifier will be delivered in the response (see operation VieKohteita). | string | - |
Asiakas > KohteenTila | Status codes:
| int | mandatory |
Asiakas > KohteenTilaPvm | Timestamp of the status change | dateTime | mandatory |
Asiakas > KohteenTilaKuvaus | A more detailed description of the status | string | - |
Kohde > ViranomaisenEmail | Email interface: One or more email addresses separated with a semicolon (if the reply-to field is different). Messages are sent to all the addresses. | string | - |
Kohde > Nimeke | Header of the message | string | - |
Table 16. The query element of the VieKohdeTiloja operation and the elements it contains.
The query message of the VieKohdeTiloja operation
Table 17 presents the VieKohdeTilojaResult element of the response message of the VieKohdeTiloja operation.
Parameter | Description | Type | Mandatory? |
|---|---|---|---|
> VieKohdeTilojaResult | An element that aggregates the response message results | element that contains child elements | mandatory |
VieKohdeTilojaResult > TilaKoodi | Status information of the response | element that contains child elements | mandatory |
Tilakoodi > TilaKoodi | Status code of the response. A more detailed explanation of errors is given in text format in the error code's explanation field. Suomi.fi Messages will retry sending the message if the status code return is other than 0 or 400-449. Codes that describe successful actions:
Error codes:
If a technical fault occurs during the performance of the service, the service will return a SOAP Fault to the caller. Immediate resending of the message is unnecessary. | int | mandatory |
Tilakoodi > TilaKoodiKuvaus | Description field for error code. For example, the KohdeMaara in the query does not correspond with the number of items in the query. | string | - |
Tilakoodi > SanomaTunniste | The unique ID data for the query that can be used, for example, to examine data in the log | string | - |
Table 17. The VieKohdeTilojaResponse element of the response message of the VieKohdeTiloja operation and the elements it contains.
If your organisation already has an IT system that supports the Web Service interface, it can be connected to Suomi.fi Messages. The IT system is connected to the Shared Integration Platform (VIA) through which the message traffic is transmitted. VIA offers a connection as a SOAP service over the HTTPS data transfer protocol.
Alternatively, a software supplier can build a connector to Suomi.fi Messages in their software. The connector enables client organisations to start using Suomi.fi Messages much quicker and cheaper than if they had to build the integration from scratch. The software supplier can decide which properties they will implement in their connector.
A client organisation who wishes to connect to Suomi.fi Messages via the WS API interface must first connect to the testing environment provided by the Digital and Population Data Services Agency. The connection to the testing environment takes place via the QAT environment that is a part of VIA. Only when the necessary tests in the testing environment are completed the client organisation can join the production environment. The connection to the production environment takes place via the PRO environment in VIA.
Testing
The interfaces of the Messages service can be tested in two phases: without signed messages and with signed messages. The tests associated with the phases can be run in parallel, which speeds up the integration process. The testing environment is the same in both phases. Both interfaces (Official Services and Return Channel) use the same environment and the same testing phases.
The following section describes the content of the testing phases. Picture 1 shows the route of a message to the Official Services interface and Picture 2 shows the route of a message to the Return Channel interface.
Step 1: Testing without a signature
All messages calling WS must contain a Viranomainen element with the field SanomaVarmenneNimi filled in. The value of the field should be the same as the Common Name (CN) of the certificate that will be used for signing in the latter steps.
The address of the VIA interface to be used for testing the Official Services is:
- https://qat.integraatiopalvelu.fi/Asiointitili/ViranomaispalvelutWSInterfaceNonSigned
- IP: 192.49.232.194.
As for the Return Channel interface, the VIA service will contact the address specified in the authority ID.
Step 2: Testing with a signature and acceptance testing
All messages calling WS must contain a Viranomainen element with the field SanomaVarmenneNimi filled in. The value of the field must correspond to the Common Name (CN) of the certificate that will be used for signing.
The address of the VIA interface to be used for testing the Official Services is:
- https://qat.integraatiopalvelu.fi/Asiointitili/ViranomaispalvelutWSInterface
- IP: 192.49.232.194.
This address is used for testing the functionality of the signatures in the WS calls that are used between your organisation's system and the VIA service. At the same time, an acceptance testing is performed to the system that will be integrated.
As for the Return Channel interface, the VIA service will contact the address specified in the authority ID. When your organisation wants to start testing a signed return channel it must request a configuration change from the Digital and Population Data Services Agency.
Picture 1 shows how your organisation's system sends a message through VIA to the Official Services interface of Suomi.fi Messages in the testing environment.
Picture: 2. Sending a message to the Return Channel interface in the testing environment.Moving to production
The production environment is an entirely separate environment to which your organisation connects by means of the PRO environment in VIA. You cannot join the production environment until the necessary tests in the testing environment are completed. The configuration of the production environment is shown in Picture 3.
- https://pr0.integraatiopalvelu.fi:443/Asiointitili/ViranomaispalvelutWSInterface
- IP: 192.49.232.195.
Implementing Web Service telecommunications
Information on how to build telecommunications with the WS API is displayed below.
Server certificates
The connection to the VIA servers is made by using the HTTPS protocol. The server certificates are available on the Valtori site (in Finnish)Opens in a new window..
Certificates and signing of calls
Your organisation's system must sign the call messages it sends. Likewise, VIA will sign its return messages. The signatures must be made with a X509V3 certificate issued by one of the certificate authorities approved by VIA. For a list of approved certificate authorities and the certificates with which VIA signs the return messages, visit the Valtori website (in Finnish)Opens in a new window..
Domain certificates (Cn=*.domain.com) cannot be used as signature certificates.
Needed client organisation data
To configure the necessary openings for telecommunications, the Digital and Population Data Services Agency must know certain pieces of information about your organisation’s systems. The Digital and Population Data Services Agency sends your organisation the VIA_Tietoliikenneavaukset form that must be filled in and returned to the Digital and Population Data Services Agency. The Digital and Population Data Services Agency forwards the form to Valtori, who perform the openings for telecommunications.
The form requires, e.g., the following information:
- Addresses of servers that send calls: IP addresses from which your organisation’s calls originate. This information must be submitted on both the testing and production environment of your organisation’s system.
- The authority ID and associated data to be reported: The authority ID is an ID created by the Digital and Population based on name that your organisation enters in the form. VIA performs reporting based on the content of the Authority ID in the call.
- Certificate used for signing: Public parts of the certificates your organisation uses for signing messages. The certificates must be submitted for both the testing and production environment.
Deploying the Return Channel interface
Suomi.fi Messages sends a message to your organisation’s system through the Return Channel interface. VIA works between Suomi.fi Messages and your organisation, routing the message to its destination based on the content of the Viranomaistunnus element.
VIA expects that the your organisation’s system has a service that can receive messages from the Return Channel and that it conforms to the WDSL provided by the Digital and Population Data Services Agency.
VIA signs the Return Channel messages it sends. When your organisation’s system sends response messages, it signs the message as required by the VIA service (see section Certificates and signing of calls above).
If your organisation wishes to use the Return Channel interface, you must deliver required details in the VIA_Tietoliikenneavaukset form. The required details are:
- the address of the Return Channel service, using the address format https://authority.fi/ReturnChannel
- server names and IP addresses
- public parts of the certificates with which your organisation’s system signs the messages.
The certificates and addresses of both the testing and production environment must be submitted. Your organisation should first test the unsigned Return Channel and only when the testing is complete, request the Digital and Population Data Services Agency to change the configuration to a signed Return Channel.
Data communication problems
Occasional data communication problems may occur when using the service, which may cause a single call to fail. A failed API call should be retried automatically.