Specifications – business validations of the Incomes Register

The Tax Administration in cooperation with other data users publishes business validations not included in the payroll report schema of the Incomes Register. Implementation of business validations is not mandatory. Implemented in payroll administration software, additional validations ensure that data users can use the information submitted to the Incomes Register as such.

Where should an IT developer start?

First you should read the documents included in the zip file:

  • data user validations v1.04.xlxs
  • documented schema (xsd)
  • schematron file

How can the IT developer make sure the data generated by the software is right for the data users?

  • By implementing validations in the software, utilising the documents above.
  • By testing the functionality of the validations in the checkup service on ilmoitin.fi or at the ApiTamo interface.

What should the IT developer decide or consider in advance?

  • Some of the additional validations should preferably be implemented in the software so that they function when data is being entered. In an accounting firm, for example, it is easier for a person using the software to correct a typing error immediately rather than when the returns are ready to be submitted.
  • Some of the checkups, however, can or must be carried out during the sending step. Those include checkups that cannot be carried out until all relevant data has been submitted.
  • The ApiTamo interface can be accessed when data is being produced or when data is being transmitted to the Incomes Register. The checkups should be implemented so that they take place as close to the data production step as possible. This ensures that the data producer using the software does not need to edit a file generated by the software, and instead the software provides instructions in accordance with the validations to supplement and correct data directly in the software.
  • The software can also generate material in line with the Incomes Register schema without any additional validations. In these situations the data producer should preferably be instructed to use the checkup service on ilmoitin.fi or to check alternatives provided by other TYVI service providers before transmitting the material generated by the software to the Incomes Register. In addition, the system should state that if data is not corrected before the transmission, the data user will probably ask for explanation later on directly from the data producer/filer.
  • Further, it should be noted that the Tax Administration’s business validations are designed to be executed once a month. What this means is that the Incomes Register schema allows the withholding to be negative in a single earnings payment report, but when the tax year’s data for the whole pay period is added up in the Tax Administration, the withholding cannot be negative. Software developers should thus choose which way to proceed. Should the user always see a notification when the withholding is negative, or should the system generate tax-period-specific calculations and display notifications of negative withholding at month level.

Good to know!

  • Some Kela validations can be found in the XSLT files (ZIP).
  • Errors found by the checkup service are shown on the Payer's report reference (ReportId) level.

Business validation routines were transferred to the check-and-test environment of Ilmoitin.fi on 15 May. As of 27 September, checking is also available in the validation interface provided by Ilmoitin.fi. At present, applications can be programmed for testing the functionality of the validations at the Ilmoitin.fi interface, and also at the checkup interface (https://www.ilmoitin.fi/webtamo/sivut/Esittelysivu?kieli=en).

Further information

The Ilmoitin user interface:

The Ilmoitin validation interface:

  • is recommended when a software application is being tested for the first time in order to ensure that its interface for data submittal works; the software application is expected to carry out an automatic check process – without secure login – on the data to be transmitted to the Incomes Register


The interface for data submittal:

  • recommended for software that already contain a functional interface for submittal of data. Requires secure login even if the data will actually not be sent via this interface (i.e. data are sent via the Incomes Register interface). NOT recommended for software that has been created as new software to accommodate the new reporting to the Incomes Register.


Send questions and feedback to