Application programming interface (API)

An Application Programming Interface (API) can be used to transfer data between programs. Disclosers can file their disclosures with the Transparency Register using the interface. This facilitates and speeds up reporting and reduces the administrative work created by it.

Integration reduces manual work during the disclosure phase

The integration streamlines the disclosure process by eliminating an unnecessary manual step. When a discloser collects information on its lobbying activities in its own system, it can, once the disclosure period begins, transfer the information electronically from that system to the Transparency Register. As a result, the process no longer includes the separate step of collecting information from the organisation’s own system and entering it individually into the Transparency Register.

The integration is particularly beneficial for disclosers that must report several lobbying or lobbying consultancy subjects. The Finnish Transparency Register does not require the disclosure of each individual meeting; instead, lobbying activities are reported by subject. Therefore, a discloser with only a few lobbying or lobbying consultancy topics can continue to submit its disclosures conveniently and directly through the service portal of the Transparency Register.

The implementer is responsible for the integration and its costs

Integration requires technical expertise and the possibility of modifying the existing system to meet the requirements of the Transparency Register. The discloser may build or commission the integration, or use various suppliers' ready-made services integrated with the Transparency Register.

While using the interface is free of charge, the implementer will pay the costs of developing and implementing the integration.

Subscribe to API newsletters to your email address

The NAOF will inform disclosers of technical changes affecting the integration and other matters concerning the interface. Subscribe to Transparency Register API newsletters and the information you need will always be emailed to you. To read earlier newsletters, visit the archive.

Instructions for disclosers

Own Transparency Register integration

Follow these instructions if you are a discloser and you would like to build an integration between your information system and the Transparency Register. See also the more detailed instructions for the technical implementation below.

1. Fill in an interface agreement and send it to avoimuusrekisteri@vtv.fi.

2. Once the agreement has been signed and your IP address has been added to the restricted test environment, you will receive instructions for accessing the test environment.

3. Implement the integration in the test environment and check that its technical solutions work.

4. Once testing has been completed as described in the agreement, notify the NAOF (avoimuusrekisteri@vtv.fi) of its deployment in production and request that an 'API key management' page be activated in the Transparency Register's online portal, enabling you to create a production API key.

5. When the service portal displays the 'API key management' page, create the key. Select 'We will integrate our system with the Transparency Register' as the implementation method of the integration. Save the key you created at once. You will not be able to view this information later, and if it is lost, you will need to create a new key.

6. Before submitting the first actual production disclosure, let the NAOF know (avoimuusrekisteri@vtv.fi) the date on which you will deploy the production interface.

7. Remember to create and activate a new API key when the previous one expires.

Service integration implemented by a supplier

Follow these instructions if you are a discloser and you wish to use a third-party service to submit disclosures of activities.

1. Agree on the practices with the service provider. Draw up a written authorisation in which you mandate the service provider to act on your behalf in Transparency Register matters as agreed.

2. Your service provider will need an API key to link your disclosure to your organisation. Contact avoimuusrekisteri@vtv.fi and request that an 'API key management' page be activated in the Transparency Register's service portal to enable you to create the key.

3. When the service portal displays the 'API key management' page, create the key. Select the service provider you are using on the list provided. If your service provide is not on the list, ask them to contact avoimuusrekisteri@vtv.fi. You can create an API key once the service provider has been added to the list. Save the key you created at once. You will not be able to view this information later, and if it is lost, you will need to create a new API key.

4. Send the API key to your service provider by a secure method recommended by the service provider, ensuring that it will not end up in the wrong hands. Only send the key to a trusted entity.

5. Follow your service provider's instructions.

6. Remember to create a new API key and send it to your service provider when the previous one expires.

Instructions for service providers

Follow these instructions if you are a service provider building an integration between your service and the Transparency Register for your customers (disclosers) to use when filing their disclosures. See also the more detailed instructions for the technical implementation below.

1. Fill in an interface agreement and send it to avoimuusrekisteri@vtv.fi.

2. Once the agreement has been signed and your IP address has been added to the restricted test environment, you will receive instructions for accessing the test environment.

3. Implement the integration in the test environment and check that its technical solutions work, at minimum as described in the agreement.

4. Request a written authorisation from each customer organisation that specifies the matters in which the service provider is mandated to act in the Transparency Register.

5. Now implement the integration with the production environment.

6. Disclosers can create their organisation-specific API keys on the 'API key management' page of the Transparency Register's service portal. As this page is not automatically displayed in the service portal, customers must contact avoimuusrekisteri@vtv.fi and request its activation in order to be able to create the key. The service provider may also make a centralised activation request on behalf of its customers.

7. When the 'API key management' page has been activated for the customer, ask the customer to create an organisation-specific API key in the service portal. When creating the key, the customer must specify its period of validity and indicate who their service provider is. Only a party that has submitted a completed interface agreement to the NAOF can be entered as the service provider. Remember to instruct the customer to send the API key to the person responsible for the technical implementation securely, ensuring that it does not end up in the wrong hands.

8. Before the first actual production disclosure, let the NAOF know (avoimuusrekisteri@vtv.fi) the date on which you will deploy the production interface.

9. Please remember to replace the API key when it expires. The discloser can create a new key in the service portal.

   ---

Testing and deployment of the API

The instructions below highlight the key issues you need to take into account when implementing the integration. For more detailed specifications of the interface (schema), visit Swagger. The instructions contain links to the Swagger sections relevant to the Transparency Register production environment. This allows you to check which values the queries in question receive or return. You can find the same endpoints in the test environment Swagger.

Access to the test environment

1. Before deployment, you should test the API in the Transparency Register's test environment. Access to the test environment is restricted, which is why you need to submit a completed interface agreement to avoimuusrekisteri@vtv.fi.

2. Once the agreement has been signed, the IP address you provided will be added to the list of allowed addresses. You will also receive the test environment address and test personal identification codes for logging in to it. Please note that the test environment is only available on weekdays between 8:00 and 20:00 (UTC+2 / UTC+3).

Using the test environment

1. To log in to the Transparency Register's test environment, click on the Login button in the top right-hand corner. Select 'Test IdP' as the login method and use a test personal identity code following the instructions you received from the NAOF. In the next step, select the organisation you represent. Please note that the test personal identification code you selected may already have been used. In that case, select another code that has not been used. You can recognise an unused personal identity code from the fact that, once you have logged in, the system will ask for your consent to the processing of personal data and sending of electronic notifications, and that the organisation does not yet have a registration.

2. Submit your registration.

3. A disclosure period is not always open in the test environment. In this case, you cannot submit disclosures. In this case, go to the 'Tester tools' page in the service portal, where you can activate inactive disclosures to fill in. Click on the flash icon at the end of the row to activate disclosures.

4. Once a year in summer, disclosers also submit financial information relating to their lobbying activities to the Transparency Register. In order to test this function, the following test design needs to be used:

   1. On the Tester tools page, backdate the registration creation date by a couple of years, ensuring that the test organisation has been in the register for long enough to submit this information (at least a full calendar year).

   2. Activate and fill in two disclosures, covering a full calendar year. Report lobbying activities in the disclosures (do not select 'No contacts' or 'Up to five contacts'). Now activate a third consecutive disclosure of activities. In the third disclosure you will be asked to submit financial information.

5. To test the submission of a disclosure in the user interface, go to the homepage of the service portal and click on 'Submit a disclosure of activities'. You can also start testing the submission of disclosures through the interface.

Creating an API Key

1. API authentication is used in the integration. The discloser can create the API key needed for this purpose in the Transparency Register's service portal.

2. API keys are created on the 'API key management' page, which is not automatically displayed in the service portal. To display this page, click on 'Activate API key management' on the Tester tools page. In the production environment, you must send an activation request to the NAOF (avoimuusrekisteri@vtv.fi).

3. Go to the 'API key management' page. Create an API key. Remember to save the key information as soon as you have created it. You will not be able to view this information later, and if it is lost, you will need to create a new API key.

Submitting a disclosure through the interface

1. Log in using the API key you created. The login returns an access token used in other queries in the Authorization header. The access key will be valid for four hours. Please note that the endpoints used for disclosures have been compiled under the 'Customer API' heading in Swagger (excl. search for disclosure periods).

2. The disclosure should contain the subjects of lobbying. They can be freely worded subjects (50 to 600 characters) or official government projects. To report lobbying related to a government project, enter the project number and name as displayed in the Government Project Register.

3. You can select the lobbying targets associated with the subject on a list maintained by the NAOF. Search for the targets in the interface, either by reporting period or all at once. GET customer-api/target/all/{termId} or GET customer-api/target/targets The ID of the target is specific to the disclosure period. As many lobbying targets are included in the Transparency Register for several disclosure periods, you must add the target using the ID for the period your disclosure concerns. The NAOF adds to, modifies and deletes target data until the start date of the disclosure period. Only essential corrections or additions are made to the targets during the disclosure period.

4. You can retrieve the disclosure periods through the GET open-data-term interface. It will return the information of both past and future disclosure periods. The disclosures for each reporting period must be filed in a chronological order.

5. First make a draft of the disclosure. The draft is not validated at this point. POST customer-api/draft-activity-notification. To update your draft, resubmit the entire draft using the PATCH method. Please note that the updates overwrite any changes made in the user interface. PATCH customer-api/draft-activity-notification/{draftId}

6. Validate the draft before publishing it. If the validation fails, the system will return an error message and a list of the problems found in your disclosure. GET customer-api/draft-activity-notification/validate/{draftId} After successful validation, check in the user interface that the draft looks correct and that the subjects and targets have been successfully uploaded.

7. Publish the successfully validated draft. The disclosure will also be validated at the time of its publication. POST customer-api/activity-notification/publish/{draftId} A published disclosure can be viewed on the Transparency Register's website without logging in. Check in the user interface that the disclosure is correct. If you need to edit a published disclosure, log into the service portal and edit it in the Transparency Register's user interface.

8. To facilitate testing, the test environment has an additional interface for searching for and deleting individual or all disclosures, making it possible to retest filing them. Test environment: DELETE customer-api/test-utils/

Transitioning to the production environment

1. You can transition to building the integration in the production environment once you have completed the following test cases at least once in the test environment:

   1. Created a draft disclosure through the interface and successfully validated it

   2. Successfully updated a draft disclosure through the interface

   3. Successfully published a disclosure through the interface, or published disclosures filed through the interface in the service portal user interface

   4. Checked that the published disclosure is displayed correctly in the user interface

   5. Noted that once a year, financial information is also provided in the disclosure.

2. Before the first actual disclosure, let the NAOF know (avoimuusrekisteri@vtv.fi) the date on which you will deploy the production interface.

3. Disclosures of activities are submitted to the Finnish Transparency Register twice a year. You must submit the disclosure information to the Transparency Register while a disclosure period is open in January–February and July–August. Any disclosures of activities received after the closing date of the disclosure period will be registered as late.