Connecting an application to the wellbeing applications interface

Check the Finnish Institute for Health and Welfare (thl.fi) regulations(opens new window) when developing your wellbeing app:

• THL Regulation 4/2025
• THL Regulation 5/2024
• ‘Wellbeing app that uses client data’ profile.

See also

• HL7 FHIR standard (hl7.org)(opens new window)
• OAuth 2.0 authentication protocol (oauth.net)(opens new window)
• Kanta authorisation guide
• Specifications.

You can find support for using the interface in the following:

• Up-to-date information on the interface service is shared in the HL7 Finland Personal Health SIG development community (hl7.fi)(opens new window).
• For more information, you can also contact the Kanta Services by sending an email to kanta@kanta.fi(opens new window).

Register for the client test environment by submitting the following forms to the Kanta Services:

• Application form for the ‘Patient data interface for wellbeing applications’ client test service (xlsx)(opens new window)
• THL’s System Form (Annex 4 of Regulation 5/2024) (xlsx, thl.fi)(opens new window)

Send the forms by email to kanta@kanta.fi.

Once Kela has approved your application, apply for a test server certificate from the Finnish Digital and Population Data Services Agency (DVV).

• Server-based apps need a test server certificate for both the client test environment and joint testing.
• You can only apply for a wellbeing application service certificate once the app has been approved for client testing and Kela has given the organisation’s OID code to the application provider.
• We will send you more detailed instructions separately on how to apply for a certificate from Kela.
• The service certificate and the application are linked together with the OID code in the serialNumber field under Subject in the service certificate.
  • The OID code is a unique OID code that the system provider applies for the application.

The certification of a wellbeing application includes joint testing by the Kanta Services, a data security assessment performed by an inspection body accredited by Traficom, and the registration of the application in the register maintained by Valvira.

The required functionalities are described in Annex 3h (thl.fi) of THL Regulation 5/2024 (thl.fi)(opens new window).

Joint testing refers to the verification of the internal testing of the app and ensuring that it functions in the Kanta Services’ client test environment. Joint testing is intended for testing in the final stage of development.

App providers are responsible for ensuring that any other testing of the app is sufficiently comprehensive and performed at a high level of quality.

Register for joint testing by submitting the application form for the Patient data interface for wellbeing applications service to Kela. Send the form by email to kanta@kanta.fi(opens new window).

Wellbeing applications must pass a data security assessment performed by an inspection body accredited by Traficom. 

1. Register the wellbeing app on Valvira’s Register of information systems (valvira.fi)(opens new window). After registration, make sure that the wellbeing app can be found in the Astori register(opens new window).
2. Notify Kela (kanta@kanta.fi) of your need to start production use. Kela sends the supplier the documents required for the technical registration of the service (steps 4 and 5) and submits the production readiness data to THL’s Code Service application register.
3. Acquire a production service certificate from the Digital and Population Data Services Agency (dvv.fi)(opens new window).
   • Server-based apps need a service certificate for wellbeing applications from DVV for production.
   • The service certificate and the application are linked together with the OID code in the serialNumber field under Subject in the service certificate.
   • The backend system of the wellbeing application, i.e., the server application running on the system provider’s server, is connected to the Kanta Services. The IP addresses assigned to the service must be static and belong to the public IP address space.
   • The data communication of wellbeing applications to the Kanta Services takes place over the public internet.
4.  Accept the terms and conditions and the service description of the interface for the wellbeing applications by signing the commitment document and submitting it to Kela.
5. Submit the details of the app to be published to Kela (kanta@kanta.fi) using the form document for submitting information. Kela will send a notification of acceptance as a service user and provide the application provider with the technical information required for production use. 
   • The app is technically registered in the Kanta Services’ interface service. Technical registration requires that the wellbeing application has been published on Valvira’s register.
   • The app will be added to the list of applications on kanta.fi two weeks after technical registration.
6. Make sure production is functional and notify Kela (kanta@kanta.fi) of the functioning of the connection. After this, production use of the application can begin. 

Report any errors or disruptions you notice in the wellbeing application or the application’s interface to Kela (kanta@kanta.fi). In order to resolve the fault situation, the message must be accompanied by search and response messages with the Access Token and personal identity code anonymised. Both messages are delivered in their entirety (header and body).

In the future, the personal identity numbers used for joint testing may not be used in your own testing.

App users can access their patient data in the wellbeing app by giving the app access rights to their patient data and by accepting the information about accessing patient data in the wellbeing app (pdf)(opens new window).