Documentation 2022

Incomes Register's interface descriptions and application guidelines for the submission and distribution of earnings and benefits payment data.

Data content application guidelines

Wages

  1. Wages – Descriptions of income types and items deducted from income  2022 (pdf),  7 June 2021, version 1.0
    • The document contains descriptions of income types and deductibles used in the earnings payment report.
    • The document describes the situations in which the income types are used.
    • The document also contains description of withholding tax and payment of social insurance premiums with respect to each income type.
  2. Application instructions on the data contents of an earnings payment report 2022 (pdf), 7 June 2021, version 1.0
    • The document contains a description of the data content in earnings payment report and what to report under each individual section.
  3. Application instructions for the employer's separate report 2022 (pdf), 7 June 2021, version 1.0
    • The document describes data content in employer´s separate reports and covers what to report under each individual section.

Benefits

  1. Benefits – Descriptions of income types and items deducted from income 2022 (pdf), 7 June 2021, version 1.0
    • Descriptions of income types and items deductible from income on a benefits payment report.
    • The situations in which income types are used are described in the document.
  2. Application instructions on the data contents of a benefits payment report 2022  (pdf), 7 June 2021, version 1.0
    • The document contains a description of the data contents of a benefits payment report and what to report under each individual section.

Technical interface descriptions

General descriptions

  1. Technical interface – Submitting data to the Incomes Register 2021 (pdf), 22 September 2020, version 1.01
    • This document provides an overview of how data is submitted to the Incomes Register via the technical interface. The document presents the Incomes Register’s data reception services and a general description of the data content to be submitted to the register.
  2. Technical interface – Distribution of data from the Incomes Register 2022 (pdf), 7 June 2021, version 1.0
    • This document provides an overview of the distribution of data from the Incomes Register via the technical interface. The document presents the Incomes Register’s data reception services and a general description of the data content to be distributed from the register.
  3. Income data – Calculation rules 2021 (pdf), 1 June 2020, version 1.0
  4. Transcripts from the Incomes Register 2021 (pdf), 1 June 2020, version 1.0
    • The document describes the transcripts generated from the Incomes Register for data providers, data users and income earners.

Content descriptions of schemas

  1. Data delivery – Schemas – Earnings payment reports 2022 (pdf), 7 June 2021, version 1.0
    • This document presents the WageReportsToIR schema, which is used for submitting earnings payment reports to the Incomes Register.
  2. Data delivery – Schemas – Employer's separate reports 2022 (pdf), 7 June 2021, version 1.0
    • This document presents the PayerSummaryReportsToIR schema, which is used for submitting employer´s separate reports to the Incomes Register
  3. Data delivery – Schemas – Benefits payment reports 2022 (pdf), 7 June 2021, version 1.0 
    • This document presents the BenefitReportsToIR schema used for submitting benefits payment reports to the Incomes Register.
  4. Data delivery – Schemas – Record subscriptions 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the SubscriptionsToIR schema, which is used for submitting record subscriptions to the Incomes Register.
  5. Data delivery – Schemas – Cancellation data 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the InvalidationsToIR schema, which is used for cancelling earnings reports, record subscriptions and records from the Incomes Register.
  6. Data delivery – Schemas – Acknowledgement of receipt 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the AckFromIR schema, which the Incomes Register uses to delivers an acknowledgement of receipt for the record submitted to the register (deferred Web Service interface).
  7. Data delivery – Schemas – Request for processing feedback 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the StatusRequestToIR schema, by which the record submitter can submit a request for processing feedback to the Incomes Register concerning the submitted record (deferred Web Service interface).
  8. Data delivery – Schemas – Processing feedback 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the StatusResponseFromIR schema, by which the Incomes Register delivers a processing feedback to record submitted to the register.
  9. Data distribution – Schemas – Service Request 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the DataRequestToIR schema, which is used for submitting a service request for data distribution (real-time Web Service interface).
  10. Data distribution – Schemas – Earnings payment reports 2021 (pdf), 25 June 2020, version 1.01
    • This document presents the WageReportsFromIR schema, which is used to distribute earnings payment reports from the Incomes Register.
  11. Data distribution – Schemas – Employer's separate reports 2022 (pdf), 7 June 2021, version 1.0
    • This document presents the PayerSummaryReportsFromIR schema, by which employer´s separate reports are distributed from the Incomes Register.
  12. Data distribution – Schemas – Benefits payment reports 2021 (pdf),  7 June 2021, version 1.08
    • This document presents the BenefitReportsFromIR schema, by which benefits payment reports are distributed from the Incomes Register.
  13. Data distribution – Schemas – Log Data 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the LogDataFromIR schema, by which log data are distributed from the Incomes Register.
  14. Data distribution – Schemas – Summary of payer's earnings payment data 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the WageReportSummaryFromIR schema, by which the summary data of payer's earnings payment reports is distributed from the Incomes Register.
  15. Data distribution – Schemas – Rejected reports submitted on paper form 2021 (pdf), 30 December 2020, version 1.01 
    • The document presents the RejectedPaperReportsFromIR schema by which rejected earnings payment reports and employer's separate reports submitted on paper forms are delivered from the Incomes Register.

Codes

  1. Codes 2022 (pdf), 7 June 2021, version 1.0
    • Codes used in the technical interface of the Incomes Register. The codes for the income types are presented in a separate document.
    • Codes 2022 (xls), 7 June 2021, version 1.0
  2. Wages – Codes – Income types 2022 (pdf), 7 June 2021, version 1.0
    • Codes for income types and deductibles on earnings payment reports, reporting modes and social insurance premiums used as default in the income types.
    • Wages - Codes - Income types 2022 (xls), 7 June 2021, version 1.0
  3. Benefits – Codes – Income types 2022 (pdf), 7 June 2021, version 1.0
  4. Codes - Error codes 2022 (xls), 8 June 2021, version 1.01
  5. Codes – Classification of Occupations (stat.fi), 1 January 2021
    • The Incomes Register uses its own version of Statistics Finland's classification of occupations (TK10).

Application developer's guidelines

  1. Technical interface – Application guidelines 2021 (pdf), 16 June 2020, version 1.01
    • This document describes the principles of the implementation of the Incomes Register technical interface from the system integration perspective
  2. Technical interface – ZIP file for application developers 2021 (zip), 1 June 2020, version 1.0
    • A ZIP file that contains xsd descriptions and WSDL descriptions of services.
  3. Technical interface – ZIP file for application developers 2021 (pdf), 1 June 2020, version 1.0
    • This document presents the ZIP-file’s contents.

Example messages: Data delivery – Earnings payment report

The documents contain examples of situations involving the delivery of earnings payment reports.

  1. Example 001: Temporary employer 2021 (pdf), 1 July 2020, version 1.0
  2. Example 002: Employer with insurance contract, basic case 2021 (pdf), 1 July 2020, version 1.0
  3. Example 003: Foreign payer, foreign income earner 2021 (pdf), 1 July 2020, version 1.0
  4. Example 004: Public sector payer 2021 (pdf), 1 July 2020, version 1.0
  5. Example 005: Employment relationship data - Retirement 2021 (pdf), 1 July 2020, version 1.0
  6. Example 006: Work abroad and the NT 2 data 2021 (pdf), 1 July 2020, version 1.0
  7. Example 007: NT data 2021 (pdf), 1 July 2020, version 1.0
  8. Example 008: Employee leasing notice 2021 (pdf), 1 July 2020, version 1.0
  9. Example 009: Exception to insurance - Non-resident taxpayer 2021 (pdf), 1 July 2020, version 1.0
  10. Example 010: Insurance information type for income type 2021 (pdf),1 July 2020, version 1.0
  11. Example 011: Absence data 2021 (pdf), 1 July 2020, version 1.0
  12. Example 012: Unjust enrichment, overpayment previously reported as other income 2021 (pdf), 1 July 2020, version 1.0
  13. Example 013: Recovery, gross recovery 2021 (pdf), 1 July 2020, version 1.0
  14. Example 014: Recovery, net recovery 2021 (pdf), 1 July 2020, version 1.0
  15. Example messages: Data delivery – Earnings payment report (zip), 1 July 2020, version 1.0

Example messages: Data delivery – Benefits payment report

The documents contain examples of situations involving the delivery of benefits payment reports.
  1. Example 001: Compensation for loss of earnings (motor liability insurance), related deduction of employee contributions and tax withholding (pdf), 22 February 2021, version 1.01
  2. Example 002: Partial disability pension paid retroactively when the income earner has already received sickness allowance (pdf), 22 February 2021, version 1.01
  3. Example messages: Data delivery – Benefits payment report (zip), 22.2.2021, versio 1.01.

Sample implementation of message signing

  1. Technical interface - ZIP - message signing, sample implementation (pdf), 31 March 2021, version 1.01
    • This document presents the ZIP file’s contents.
  2. Technical interface - ZIP - message signing, sample codes, 23 March 2018, version 1.0
    • The ZIP file contains a client implementation of a call sent to the Echo service (EchoService) and the signing of the request message sent.