Instructions for system providers
A system provider develops or supplies an information system used by an organisation in which an integration with Suomi.fi Messages has been implemented. As a system provider, you play a key role in determining the opportunities available to public sector organisations to utilise Suomi.fi Messages within their systems. In addition, you can support your client organisation throughout the various stages of deployment.
The way the integration is implemented affects, for example:
- how easily messages can be sent from the system
- whether messages can be replied to
- how message status information is utilised
- how email notifications are managed
- how message content is created
- how well the implementation supports the organisation’s day-to-day processes
A well-designed integration helps an organisation both fulfil its statutory obligations and make the most effective use of the features offered by Suomi.fi Messages.
Below you will find more detailed instructions to support the system provider’s development work.
When planning the implementation of a Suomi.fi Messages integration, you should first familiarise yourselves with organisations' operating practices and needs. We also recommend involving organisations in the development work from the very beginning.
DVV recommends that you review the guidance pages and support materials produced for organisations. These materials will help you understand the service processes and use cases in which Suomi.fi Messages can be utilised.
A single service journey may involve several message types, such as acknowledgements of receipt, requests for additional information, appointment notifications, decisions and payment reminders. Different message types may have different requirements regarding notifications, message content and delivery methods. Professionals within an organisation may also have varying needs related to message tracking, checking mailbox status or enabling two-way communication.
If the same system is used across multiple services, you should enable the creation of multiple service identifiers under a single system ID. This allows messages to be sent on behalf of each individual service. Recipients can immediately see which service a message originated from. At the same time, the organisation avoids the need to come up with a single common name that would be suitable for all services.
Important guidance pages
- Connecting an organisation to Suomi.fi Messages
- Use cases for organisation
- Message recipients
- Designing the electronic message and notification
- Using Suomi.fi messages together with an E-service
Materials produced in cooperation with organisations
- Suomi.fi Messages customer storiesOpens in a new window.
- Operating model descriptions for wellbeing services counties, in finnish (specialised healthcare, social welfare services, invoices, client fee documents and decision documents)
- Operating model descriptions for municipalities, coming soon (case management, early childhood education and care, building supervision, land-use planning and parking enforcement)
Recommended blog posts
The starting point for planning the functionalities and their features should be the customer journey and the day-to-day work of professionals using the service.
The solution could, for example, enable functionalities defined by message type or document type, such as:
- notifications
- status information
- delivery methods
- message formatting
- two-way communication
- mailbox status checks
- other automation features.
This would make it possible, for example, to define separate practices for decisions, requests for additional information and invoices, making the solution flexible and scalable to different needs.
Professionals within the organisation may also wish to manage settings related to messages themselves. It is worth assessing which features could be managed by the organisation’s professionals. For example:
- editing email notifications
- editing the text content of electronic messages
- configuring unread message email notifications
- defining, on a message-by-message basis, whether recipients can reply to a message
All REST API functionalities are described in more detail in the Functionalities section of the documentation.
During the design phase, system providers can also contact DVV’s experts, who have extensive knowledge of customer needs, message use cases and technical implementation options.
System providers can apply for credentials for their own use to support development work. The credentials for the REST API provide access to the Suomi.fi Messages test (QA) environment. No credentials are issued to system providers for the production environment.
Complete the Suomi.fi Messages Service Information Form (DOCX, 216.82 kB)Opens in a new window. and submit it to the Digital and Population Data Services Agency at: viestit-kayttoonotot@dvv.fi. In the accompanying message, system providers can specify that the request concerns credentials for a system provider and briefly describe the system integration being developed.
Based on the information provided in the Service Information form, access rights to the Suomi.fi Messages QA environment will be granted and the credentials required for using the REST API in the QA environment will be issued.
TKJ service credentials
For the development and testing of the printing, enveloping and distribution service (TKJ service), it is also possible to order a TKJ credential.
TKJ credentials are subject to a charge for system providers. A TKJ credential can be ordered by completing the Suomi.fi Messages Order form for TKJ Identifier (DOCX, 76.13 kB)Opens in a new window.. The end of the form contains a section specifically intended for system providers, including information on the price of the TKJ credential.
Submit the form to viestit-kayttoonotot@dvv.fi. In the accompanying message, indicate that the request concerns TKJ service credentials for a system provider.
Further information on testing is available on the Testing instructions page.
Please note that materials containing personal data or classified information must not be sent to the QA environment. The QA environment is shared by all users, which means that test materials from multiple organisations may be present in the environment at the same time.
All technical documentation for the REST API is available in the API documentation Opens in a new window.(api.messages.suomi.fi).
Once the integration has been completed and the solution is ready for customer deployments in the production environment, notify DVV accordingly. At the same time, provide a description of the solution and a link to the website of your choice for inclusion in the list of system providers.
Please also ensure that your organisation’s website and customer materials include information that the system can be integrated with Suomi.fi Messages, as well as details of the functionalities supported by the solution.
System providers should also review the instructions available on the Maintenance page.
The deployment process is described on the Deployment in the organisation page. Every organisation deploying Suomi.fi Messages must complete the process described on the Administrative deployment page.
To proceed with deployment, the organisation must ensure that:
- a valid access licence is in place,
- the organisation completes and submits the Service Information form to obtain credentials for the QA environment,
- the organisation completes and submits the Deployment Checklist to obtain credentials for the production environment.
The information provided in documents submitted to DVV during deployment is binding on the organisation. System providers cannot complete or submit the Service Information form or the Deployment checklist on behalf of an organisation.
During deployment, the role of the system provider is to support the organisation in completing the forms, for example by providing information about the system’s functionalities. However, the organisation is responsible for reviewing the documents carefully and ensuring that the information provided is correct.
Testing within the organisation
Organisations should be encouraged to recognise the importance of testing as part of the deployment process. Testing helps organisations better understand how notifications, messages, the service name, links and attachments appear from the end-user’s perspective.
This helps ensure that the e-service provides a smooth user experience, that message content is clear and understandable, and that the overall service supports customers in managing their affairs effectively.
The legacy Suomi.fi Messages interfaces (WS, SFTP and SMTP) are in maintenance mode, and no new functionalities will be developed for them. All legacy interfaces will be discontinued on 1 January 2027.
All services currently using Suomi.fi Messages through the legacy interfaces must migrate to the new REST API before 2027.
Please ensure that your client organisations have migrated to the REST API well in advance of the end of 2026.