Suomi.fi Messages migrates to REST API – what does that mean for organisations using the service?

In the next few years, the use of Suomi.fi Messages will move to the new REST API. This will require technical and administrative measures of organisations that use Suomi.fi Messages.

The following topics are covered in this blog post:

• What is the REST API, and what is behind the migration?
• The differences between the different APIs (WS, SMTP, SFTP) and finding out which one your organisation uses.
• Migration schedule and what your organisation must do next.

What is an API?

An application programming interface (API) is a technical solution that enables integration between systems. Today, organisations interface with Suomi.fi Messages in different ways, such as WS, SMTP (e-mail interface) and SFTP.

These old APIs are being replaced with the REST API. REST is a modern API that enables communication between different systems using HTTP. It is designed to be simple and flexible.

The POST API, i.e. POST forms or electronic forms in Suomi.fi Messages, will also be available in the future. The POST API needs another API for it to pass the message to the organisation. In the future, this must also be done with the REST API.

Why adopt the REST API?

With the REST API, all features of Suomi.fi Messages will be available through a single API. This will make it simpler to activate the service and reduce the need to compare different APIs for the needs of the organisation. In addition, the REST API improves message transmission and enables a faster response to potential faults.

What are the differences between the WS, SMTP and SFTP APIs?

How do I know which API my organisation uses?

If you are not sure which API your organisation uses, this is one way to find out:

• Check how messages are transmitted
• If messages are sent from the organisation’s system, it is possible you are using WS or SFTP.
• If messages are sent through email, you are using the SMTP API.
• If you receive forms from Suomi.fi Messages in email inboxes, you are using a combination of the POST API and SMTP API.
•  
• Ask your organisation’s ICT experts or the software provider that maintains the system.
• You can also ask the Digital and Population Data Services Agency for help in determining the API: viestit-kayttoonotot@dvv.fiOpens in a new window.

Migration schedule

The Digital and Population Data Services Agency has set a schedule for discontinuing old connections. Each organisation that uses Suomi.fi Messages must migrate to the new REST API by 1 January 2027.

The migration will take place in stages and the old APIs will be decommissioned as follows:

1 January 2025: New connections are no longer opened in the old APIs. All new activations are made with the REST API.
1 January 2026: New services can no longer be added to existing connections in the old APIs. Applies especially to software solutions offered by ICT service providers.
1 January 2027: All old APIs will be decommissioned.

Reserve enough time for the migration. It may take several months to carry out the technical and administrative migration, including the improvement of usage patterns or a completely new activation. It is therefore important to start planning in advance.

What must my organisation do next?

The required measures depend on which API your organisation uses. Your organisation may have several services in Suomi.fi Messages that operate through different APIs. In other words, your organisation must first find out which APIs it uses.

Technical migration of WS and SFTP interfaces

Start planning your integration by reading the documentation on the Suomi.fi for Service Developers website. Also submit a completed Service Catalogue Form to the Digital and Population Data Services Agency (the form and instructions are available under section 3)

Migration from WS and SFTP APIs to REST is usually more straightforward. If you use the WS API, you can always test and take one endpoint at a time to production. The easiest way to migrate from the SFTP API is the multichannel /messages endpoint of the REST API. Messages that are sent by paper mail must be sent as printable PDF files, but with an electronic message, it may be a better idea to include the content of the message. It is also possible to include text styling in electronic messages in the REST interface with Markdown symbols.

A significant change from previous connection types is that monitoring the status of messages you send and receiving messages from end users no longer takes place in the REST API’s return channel. Instead, your system must actively retrieve data on message status changes and potential messages sent by end users by regularly calling the /events endpoint of the REST API. In order to retrieve status information, your system must save the latest followToken value returned by the Suomi.fi Messages REST API’s /events endpoint.

When making any changes, it is always advisable to test all the functions you use with the Suomi.fi Messages QA environment, making use of our testing instructions. When everything is ready, complete and submit your activation checklist to the Digital and Population Data Services Agency (see section 6 of the instructions on the Suomi.fi for Service Developers website). Also indicate the start date of production use. The checklist helps both you and the Digital and Population Data Services Agency to ensure that all requirements have been taken into account before the start of production use.

If you have activated Suomi.fi Messages through software provided by third-party ICT system provider, please contact your system provider, who is responsible for the technical migration and schedule. Any administrative measures are your responsibility.

If you are building a REST API for your own system in-house, proceed according to the instructions and contact Suomi.fi Messages activation at viestit-kayttoonotot@dvv.fiOpens in a new window..

Administrative migration of WS and SFTP interfaces

If your organisation’s services that use Suomi.fi Messages do not change, you do not need to apply for a new licence. If you are introducing new services, you must apply for new licences from Suomi.fi Service Management in accordance with our instructions.

Example: An organisation has an early childhood education and care system that integrates Suomi.fi Messages through the WS interface. The organisation has an existing licence to use Suomi.fi Messages for early childhood education and care services. The system provider implements the REST API migration to the system and in the future, the organisation will continue to use Suomi.fi Messages as part of the early childhood education and care system. The organisation does not need to apply for a new licence because the service remains unchanged and only the background API changes.

Even if there are no changes to the services you have connected to Suomi.fi Messages, the Suomi.fi Messages user instructions may have been specified since. During migration, ensure that your organisation’s operating method complies with the instructions. In addition, the REST API provides new functionalities that help you streamline your organisation’s customer processes.

At the minimum, check these:

• Formatting of the message or notification: Check the Formatting of electronic messages and notifications page at the Suomi.fi for Service Developers website for instructions and examples on how to format a message and its notification in way that your customers understand its content and are able to handle their matter.
• Relationship between services and Suomi.fi Messages: We have specified the relationship between services and Suomi.fi Messages. In most situations, the customer is best served by a message that contains all the necessary information. If necessary, you can also direct the client to your service with the message. If you do this, the message content must include a link to the correct location in the service and provide clear instructions on what the client is expected to do there.
• Unlike email, sending links and attachments through Suomi.fi Messages is secure. Third parties cannot send phishing messages or viruses through Suomi.fi Messages, as the senders are verified and messages are sent over a secure connection.
• Naming your service: During the migration, it is also a good idea to carefully assess the name of an existing service that is visible to customers. The name of the service should be as clear as possible and, for example, possible to link to a specific service or industry. The service name is shown to the customer in the New Message notification and in the Inbox of Suomi.fi Messages. End users can also see the name of the service when they write a new message to the organisation (if the organisation has enabled end users to do so). Instructions for changing the name of the organisation or a service can be found on the Administrative Maintenance page.

Pay attention to other diverse functionalities

The REST API includes all the functionalities of the old APIs as well as all-new functionalities. Suomi.fi Messages is specifically intended for sending notifications from the authorities, but it also makes it possible to send other messages related to the service path in a convenient and cost-effective manner.

For example, if you send read-receipts or temporary information to your customers about the stage of the processing of their matter, you can limit the sending of this information to persons that can receive it electronically. You can also choose to turn off reminders for unread messages for messages like this.

The new functionalities of the REST API make it possible to update how the service is used, or the processes related to the use of Suomi.fi Messages. With REST, you can send the same message with different content depending on whether it is sent to the recipient by electronically or by paper mail. For example, a paper letter may include more detailed instructions on what the client needs to do in the paper world, whereas an electronic message can include a direct link to further services.

In summary:

• Verify if your organisation is using the WS or SFTP interface.
• Contact your ICT expert or software supplier – is REST support planned for the desired system and on what schedule?
• Schedule the migration well in advance.
• Review the new functionalities offered by the REST API and redesign your customer process. Make sure that you communicate well and train your customer service personnel.
• Consider whether your organisation has other services that could also benefit from the activation of Suomi.fi Messages.

Discontinuation of the SMTP API and deploying REST

If your organisation has used the SMTP API (= email connection), it is being discontinued in Suomi.fi Messages. Suomi.fi Messages will also not provide a user interface intended for customer organisations to the service. Below, we will explain the alternatives for the SMTP API.

If you are using POST forms that are sent to your organisation’s email addresses through the SMTP API, please contact the system vendor that provides the form service. It will be possible to direct electronic forms from customers directly to a case management system or e-service.

Alternatives to the SMTP API

We recommend that your organisation reviews what you have used the SMTP API for until now and what you want to replace it with. The Digital and Population Data Services Agency has compiled some examples of case management systems and other standard applications with Suomi.fi Messages integration on the Standard Software and Messages deployment page. The page also contains tips for taking the requirements of Suomi.fi Messages into account in connection with competitive tendering for systems.

Your organisation does not necessarily need to apply for a new licence if you enable Suomi.fi Messages on the REST API for the same service.

Example: An organisation has used the SMTP API for early childhood education and care services. Now, the organisation integrates Suomi.fi Messages in the ECEC system through the REST API. Therefore, the organisation continues to use Suomi.fi Messages for ECEC services. The organisation does not need to apply for a new licence, because the application is for the same service, despite the change of the background API and new system.

Suomi.fi Messages deployment instructions include comprehensive and detailed guidelines for organisations from both an administrative and technical perspective.

If it is not possible to migrate to the REST API

We understand that there may be situations that prevent migration to the REST API or keep your organisation from using Suomi.fi Messages for some other reason.

Public administration organisations have been required to use Suomi.fi Messages since 2016 (Act on Central Government’s Joint e-Service Support Services 571/2016). An organisation subject to this obligation must apply for an exemption if it is no longer able to use Suomi.fi Messages for a justified reason.

If your organisation is not required to use Suomi.fi Messages and you want to discontinue its use, it is sufficient to submit a written notification on terminating the use of Suomi.fi Messages. Detailed instructions can be found on the Terminating the use of Suomi.fi Messages page.

As a result of the Digital First project, Finland will shift to digital communication as the primary option for the authorities in the beginning of 2026. At that time, everyone that communicates with the authorities digitally will receive official decisions and other notifications electronically in Suomi.fi Messages. Anyone that has not yet activated Suomi.fi Messages will have it be automatically activated when they authenticate in any e-service of an authority. Organisations that do not send their notifications electronically must also take account of this change. In such a case, an organisation that is required to use Suomi.fi Messages must, in addition to acquiring the exemption, also plan how it will primarily send electronic notifications, such as decisions, if Suomi.fi Messages is not used for this purpose.

Digital reach of Suomi.fi Messages widens

Currently, 1.5 million citizens of Finland use Suomi.fi Messages. In 2026, Suomi.fi Messages will have an even wider digital reachOpens in a new window.. Users of the service will not only be the most digitally capable citizens – there will be a wider variance of digital competence among the users. This should be taken into account when formatting the content of the messages you send and providing user instructions for the services.

Now is the best time to examine the clarity and smoothness of customer paths in the digital world and to ensure smooth digital interactions with the authorities for everyone.

Subscribe to the Digital First project’s mailing listOpens in a new window. to make sure that you always receive up-to-date information on the progress of the project.

Let's work together to improve official communications and a better user experience for our services!

 Maria Juka-Lahdenperä, Service Owner of Suomi.fi Messages, Digital and Population Data Services Agency