Go directly to contents.
Suomi.fi Finnish Service Catalogue

Transition from API version V11 to V12 (search API)

Beta – content under developed

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 V11 to 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.

The instructions are preliminary, and their content will be supplemented and updated during spring 2026 as the architectural reform of the FSC progresses. The note “coming later” means that the content of the instructions will be supplemented during spring 2026 as part of the FSC’s architectural reform.

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 V12 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). See instructions on [testing the API] (coming 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 AP.

Considerations for the transition period

  • Note that during the transition period – i.e. when V11 is still available for updating data to the FSC – two versions of the FSC’s data content, V11 and V12, will run simultaneously in the background.
    Data entry and updates will still be done in V11, from where the data is transferred in the background to the V12 side with a delay lasting about 1-1.5 hours.
  • The first API version that will be published in March 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, 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 V12 has two different search methods

  • searching for an individual piece of content with an ID
  • data retrieval with search criteria using the /search API and search 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 regional science, 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 search 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: 24/3/2026

More on the topic

Key improvements and changes

Are you satisfied with the content on this page?