Documentation 2021

The Incomes Register's technical instructions and schema descriptions for software developers for 2021 are published on this page. The documentation will be available in English later.

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  2021 (pdf), 29 October 2020, version 1.02

    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.

Benefits

  1. Benefits – Descriptions of income types and items deducted from income (pdf), 10 October 2020, version 1.06
    • 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 (pdf),  27 May 2020, version 1.05

    • 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

Content descriptions of schemas

  1. Data delivery – Schemas – Earnings payment reports 2021 (pdf), 18 August 2020, version 1.02
    • 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 2021 (pdf), 1 June 2020, 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 (pdf), 16 September 2020, version 1.08

    • 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 2021 (pdf), 25 June 2020, version 1.01

    • 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 (pdf), 26 June 2020, version 1.05

    • 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.

Codes

  1. Codes - Error codes 2021 (xls), 27.10.2020, version 1.04

  2. Benefits – Codes – Income types (pdf), 27 May 2020, version 1.05

  3. Codes – Classification of Occupations (stat.fi), 18.5.2018
    • 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