More information for implementers of the import integration (API version 12)

This page is preliminary and will be supplemented during autumn 2026.

Before you begin implementing the import integration, read the following instructions: Technical documentation for the implementer of the integration (API version 12).

Access licence application

The import interface requires a separate access licence. Submit your application before activating the import integration.

How to deploy the import interface

Instructions for implementing the integration

After submitting your application, you can begin implementing the import integration in the customer test environment. You will find the information for the customer test environment at the end of this page.

Make sure that the integration transfers changes made in the source system to the FSC at least once per day. If you delete data in the source system, also make sure to delete it in the FSC. Carry these deletions out at least once per day. 

Study the API methods and data structures in the Scalar documentation:

• Customer test environment API documentation in ScalarOpens in a new window.
• Production environment interface documentation in ScalarOpens in a new window.

Identification in the import interface

To use the import API methods and access-limited search API methods, you will need:

• a valid token, and
• a valid API key. Read the API key instructions.

The token is used to identify the user’s access rights. The API key is used to identify the integration making the API call.

An import integration implementation is always organisation-specific. Submit your organisation-specific API username and password to the Suomi.fi Service Management access control server. The server returns the necessary authentication token.

Using the token for identification in the production environment

The production environment token contains access-right information and the token’s validity period. Check the validity in the token data and apply for a new token before the current one expires.

Token retrieval address: (to be completed later)

Retrieving the token

Submit a token request with the following data.

Header 
Content-Type:application/json 

Body 
username: user 
password: pwd 
apiUserOrganisation: organisation ID (optional) 

The call returns the serviceToken parameter.

If your API username is connected to more than one organisation

• Allocate the token request for the organisation you want with the apiUserOrganisation field.
• In this field, enter the value of the organisation ID returned by Suomi.fi Service Management.
• If you do not provide a value in the apiUserOrganisation field, the token will be generated for the organisation that is marked as active in Suomi.fi Service Management.

Example call 1, no organisation ID

{ 
  "username":"username@domain.fi", 
  "password":"validpassword" 
} 

Example call 2, organisation ID entered

{ 
  "username":"username@domain.fi", 
  "password":"validpassword", 
  "apiUserOrganisation": "9cb2abc6-5458-4811-bbdd-83f75ceeed25" 
} 

Example response

{ 
  "serviceToken":"eyJhlsdlksd...." 
} 

Note regarding the production and customer test environments

The tokens for the two different environments are structurally different.
When you are applying for a production environment token, use the apiUserOrganisation field if you want to target a specific organisation.

Test your integration before deploying to production

Test the import integration in the customer test environment before you deploy it to the production environment.

First, read the testing instructions: 

• Testing the import integration in the customer test environment (includes templates for the test reports)  (in Finnish)

Test the following: 

• the integration must work according to your technical design
• the transmitted data is FSC-compliant 
• the API connections and access rights work correctly. 

Prepare the required test reports and submit them to the DVV in accordance with the test instructions. 

Fixes and production deployment

After completing the required tests and submitting the test reports to the DVV, begin your production deployment in accordance with the test instructions.

Deployment to production

1. Submit the test reports to the DVV.
2. Wait for approval.
3. Receive the API username information for the production environment.
4. Deploy to production.

After your tests have been approved, the DVV will send the API username and password for the FSC production environment to the email address in the application.

Example instructions for the most common use cases

https://api.palvelutietovaranto.trn.suomi.fi/api/auth/oauth/connect/token

Header 
Content-Type: application/json 

Body 
username: user 
password: pwd 
apiUserOrganisation: organisation ID (optional)

{ 
  "username":"username@domain.fi", 
  "password":"validpassword" 
} 

{ 
  "ptvToken":"eyJhlsdlksd...." 
}