Go directly to contents.
Suomi.fi Finnish Service Catalogue

Transition from API version 11 to 12 (search API)

These instructions are for organisations using the Finnish Service Catalogue's (FSC) search API (OUT API) utilising FSC data through the current OUT API and who are preparing to transfer from API version 11 to version 12. The instructions support assessing the workload and starting to use the new version. Separate instructions for import API (IN API) customers will be drawn up later to support the transfer.

What is going to change compared to the previous version?

This version switchover differs from previous ones in scope: the changes are significant and require more preparation and development work from the parties implementing the integration.

Impact of the changes on API users

Required actions

  • Use of API version 12 will require activating an API key. See instructions on [starting to use an API key] (coming later). 
  • API users must update the logic of API calls and information processing to correspond to the new version's structure and response structures. 
  • New API calls and response structures must be carefully tested. The test can be performed in a customer test environment (former training environment). More detailed testing instructions will be published later.
  • Learn more about the API documentation of the customer test environment in Scalar Opens in a new window.as well as the following summary of changes to the API.

Considerations for the transition period

  • Note that during the transition period – i.e. when version 11 is still available for updating data to the FSC – two versions of the FSC’s data content, version 11 and version 12, will run simultaneously in the background.
    Data entry and updates will still be done in version 11, from where the data is transferred in the background to the version 12 side with a delay lasting about 1-1.5 hours.
  • The first API version that will be published in March 2026 is a beta version, so it may still undergo changes and clarifications before the final version. 
  • When the FSC APIs for importing data become available for testing in autumn 2026, the aim is to establish the content of the search APIs. The aim is to no longer make significant changes to them.

Changes to search APIs

API version 12 has two different search methods

  • searching for an individual piece of content with an ID
  • data retrieval with search criteria using the /search method and its parameters

The search method will have versatile filters that can be used to retrieve data from the API with different perspectives. The search can be narrowed by organisation, organisation type, service class, keyword, target group and area information, for example.

Content returned by the search API

  • For data supplementing or classifying the searched content – such as service target groups, life events or keywords – only identifiers (IDs) are returned, not the entire data content. 
  • The search API will only return published data. Archived content (service channel, organisation, service) can only be searched with separate calls. These calls will only return identifiers (IDs), not the whole content. 
  • Different language data of the same content is returned in its own collection in the languageVersions structure. The example below includes a part of the service fields that are available as different language versions. The example does not include all data returned by the API. 
"languageVersions": {
        "fi": {
          "name":"Osallistuva budjetointi",
          "alternativeName": "Osbu",
          "summary": "Tee ehdotuksia ja äänestä – ole mukana kunnan päätöksenteossa koskien taloutta ja resursseja.",
          "description": "Mitä palvelua tai asiaa kaipaat porvoolaisten iloksi ja hyödyksi? Ehdota ideaa ja äänestä suosikkiasi Porvoon kaupungin toteutettavaksi.",         
         },
        "sv": {
          "name": "Deltagande budgetering",
          "alternativeName": "Osbu",
          "summary": "Lämna förslag och rösta – delta i stadens beslutsfattande om ekonomi och resurser.",
          "description": "Vilken tjänst eller sak längtar du efter som kan vara till glädje och nytta för invånare i Borgå? Föreslå en idé och rösta din favorit att förverkligas i Borgå stad.",
          },
          ...


The following more detailed compilation of the changes to the search APIs reflects the current V11 APIOpens in a new window..

Changes to search APIs by dataset

Updated: 28/5/2026

More on the topic

Key improvements and changes

Are you satisfied with the content on this page?