Go directly to contents.
Suomi.fi Data Exchange Layer

Deploying a single service

This article describes how to deploy a service offered via the Data Exchange Layer when your organisation has already joined the Data Exchange Layer and has a functioning Security Server.

  1. Familiarise yourself with the service, its terms of use and technical details in the API Catalogue
  2. Apply for a use permit for the service (subsystem use permit)
  3. Connect your organisation’s and the service provider’s information systems

Note that the deployment of a single service always depends on the service provider. If needed, check service-specific instructions directly with the organisation providing the service.

Prerequisites:
Before applying for a use permit for a single service, your organisation must be connected to the Data Exchange Layer and have a functioning subsystem. Make sure that at least one subsystem has been added to your Security Server.
• You can also verify the existence of the subsystem in the API CatalogueOpens in a new window. under your organisation’s details.

Note! If the subsystem is added to a Security Server that is not yet in use within the Data Exchange Layer, follow the instructions starting from the Join the Test Environment page. If your organisation intends to use services via the Data Exchange Layer, it must be connected to the production environment. The full instructions for joining the Data Exchange Layer are available on the Deployment page.

1. Familiarise yourself with the service, its terms of use and technical details in the API Catalogue

The organisation providing a service will describe said service in its subsystem description.

If any of the information you need is missing from the subsystem’s description, ask your service provider for the missing information.

Check whether you will be able to implement the service

First, ensure that your organisation meets the requirements for deploying the service
• regarding the terms of use and
• technical specifications.

Terms of Use

The implementation and use of services may be subject to restrictions, licence applications and fees. For service-specific terms and conditions, see the description of the subsystem in the API Catalogue.

Technical specifications

More detailed interface-related information on the service can be found in the subsystem’s attachments. If the service is SOAP-based, the information on the service is presented in a WSDL file. In services based on the REST model, the file is usually in the JSON format. Service providers may also add other technical documents related to the service, such as PDF files, to the Attachments section.

The API Catalogue contains descriptions of services that are based on both the SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) model. Whether a service is SOAP or REST-based will influence the technical solutions necessary for the implementation of the service. For example, a so-called adapter service is not needed with REST interfaces. REST is generally a more lightweight solution than SOAP, as it is more lightly standardised.

2. Apply for a use permit for the service (subsystem use permit)

You may need to apply for a permit to use the services. Depending on the service to be deployed, you can apply for a permit either in the API Catalogue or by contacting the service provider.

Apply for a use permit in the API Catalogue

In the API Catalogue, you can apply for a permit to use the subsystem and services if the service provider has enabled the function. You can also apply for a use permit as an intermediate operator acting on behalf of another organisation. Once enabled by the service provider, the API Catalogue displays a separate section to logged-in users on the subsystem’s page, Request permission to use this subsystem. For additional information on how to apply for a service licence, see the separate support article.

Contact the service provider

If a use permit can not be applied via API Catalogue for a service you want to deploy, contact the organisation that provides the service.

The service provider’s contact information is included in the subsystem information available in the API Catalogue. If no contact information is available, ask for help from API Catalogue maintenance: palveluvayla@palveluvayla.fiOpens in a new window..

Testing is possible once the subsystem has been connected to the Security Server and the use permit has been granted. We recommend that you test the compatibility of your subsystems with the service provider when you join the test environment. This will help ensure that the messages between your organisation and your service provider’s service are transmitted without any issues. Read further about testing.

3. Connect your organisation’s and the service provider’s information systems

Your organisation’s information system is connected to the Data Exchange Layer via the Security Server and the subsystem

Please note that before you begin connecting the information systems used by the service user (you) and the service provider, your information system must already be connected to the Data Exchange Layer.

The information system that will receive data from other Data Exchange Layer services is connected to the Data Exchange Layer via a security server. The subsystem, on the other hand, acts as the interface between the security server and information system. In other words, the retrieval of information from one information system connected to the Data Exchange Layer to your information system takes place between the organisations' subsystems.

Access rights to the Data Exchange Layer are defined at the subsystem level, which is why the use of information system-specific subsystems is recommended as a starting point. In some cases, one subsystem can be used with multiple services if these services form a logical entity.

In practice, the deployment of a security server and the addition of a subsystem are part of the Data Exchange Layer connection process.

Test the Integration of Information Systems First in the Test Environment

Before you connect your information systems in the Data Exchange Layer’s production environment, you must test the connection in the test environment. Agree on the testing process with the organisation providing the service.

Record the errors detected during testing and correct them before entering the production environment. When everything is functioning smoothly in the test environment, you can begin connecting your information systems in the production environment.

For more information on the test environment and testing process, see:

Environments of the Data Exchange Layer and API Catalogue

Test services in the Data Exchange Layer

Issues to consider when connecting information systems

When you begin connecting your information systems, your service provider will need at least the following:

  • your subsystem’s identifying information for configuring the service permissions (subsystem name = X-Road subsystem code)
  • your security server’s IP address for the necessary port openings (5500 and 5577).

Your organisation must also be provided with the IP address of the service provider’s security server, so that you can perform the same port openings.

Note! If there are issues in the connection between your organisation and the service provider after the use permit has been granted and the ports have been opened, check the error logs of your Security Server.

Updated: 29/9/2025

Are you satisfied with the content on this page?