The Incomes Register has added new instructions for using the technical interface

12/4/2020

The Incomes Register has been in use for almost two years. Next year, the number of reports submitted to the Incomes Register will increase significantly, as benefit payers start reporting paid pensions and benefits to the register on 1 January 2021.

– The highest number of earnings payment reports submitted in a single day is up to 500,000 reports. Usually, the peak volume of reports has been around 200,000–300,000 reports per day. Based on an analysis carried out together with benefit report submitters, it is expected that the number of benefits payment reports submitted per day can rise up to one million reports, says Terhi Holmström, Director of Incomes Register Unit.

The Incomes Register has specified its instructions regarding the technical interfaces in order to make reporting and distributing data as efficient and easy as possible for the users. In addition to helping select the appropriate reporting channel, the Incomes Register makes recommendations regarding the size of records, delivery times and retrieval of processing feedback.

The recommendations are based on the increase in data flows and two years' worth of user experience with reporting wages.

Recommendations to data providers

Restrict the size of the record and wait for the processing to finish before requesting for feedback

The recommended size of a record is a maximum of 3,000 reports. If you plan to submit over 100,000 reports during a single day, please contact the Incomes Register to agree on a suitable time for submitting the reports. If you send multiple records from an SFTP account, it is recommended that you submit them one after another and take into account the renaming practices.

After submitting the record, you should wait at least five minutes before you start requesting processing feedback in the SFTP interface and deferred Web Service interface. The specified recommendations regarding records have been published in Section 4 of the technical documentation for data delivery  The document Technical interface – Distribution of data from the Incomes Register will be published in English at a later date.

Submit large volumes via the SFTP or deferred Web Service interface

The SFTP and deferred WS interface are suited for recurring use and for submitting large volumes of reports, for example, when submitting large quantities of data directly from the payroll run.

The real-time WS interface can be used, for example, when integrating the data user’s own user interface application with Incomes Register services. It is best suited for submitting individual reports.

The web form in the Incomes Register's e-service is intended for filling in, correcting and cancelling individual reports. The upload service in the e-service is intended for submitting records that contain few reports.

Recommendations to data users

SFTP user: limit the number of query criteria and include only one secondary subscription in a single record subscription 

It is recommended that you give a maximum of 5,000 income earner or payer's identifiers as query criteria for a single record subscription. Numbers higher than this should be divided into separate subscriptions. Additionally, record-specific restrictions should be taken into account in the query criteria.

It is recommended that you only include one secondary subscription in a single record subscription. The Query time range for changes is always the same for all subjects included in the subscription, but the other query criteria for individual income earners or payers may differ from one another. If data regarding multiple subjects is needed at the same time, the data must be ordered using the same secondary subscription of the record subscription. In such a case, the data is delivered in the same query files.

The record's query time is determined according to the scheduled query time. The record is queried and generated into files after the scheduled time and sent to be retrieved from the subscriber organisation's SFTP file. Do not try to retrieve the record before the scheduled query time.

The specified recommendations regarding records have been published in Section 4 of the technical documentation for data distribution. The document Technical interface – Submitting data to the Incomes Register will be published in English at a later date.

Order recurring records via SFTP

You can use the real-time Web Service to search for data related to an individual subject such as an income earner or a payer. This channel is best suited for situations in which the need for data is immediate and only applies to one subject at a time, for example, when processing an application or decision related to an individual income earner or payer.

If you need data related to the same subject recurrently or you want to process several subjects with similar query criteria, it is recommended that you retrieve the data via the SFTP channel. If multiple record subscriptions are sent from an SFTP account, it is recommended that you send them one after the other and take into account the renaming practices.

The search function in the Incomes Register's e-service is intended for searching individual data items when the searches are infrequent. The search result is not generated into a summary; instead, the result is a list of reports. The reports can only be viewed one at a time. In the e-service, you can also retrieve PDF and CSV format transcripts that are generated based on record subscriptions.