Documentation

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

The interface descriptions related to the distribution of benefits payment data were published in Finnish in the autumn of 2018. Translations will be added to the pages once they are completed.

Data content application guidelines

Wages

1. Reporting data to the Incomes Register (pdf), 29 January 2018, version 1.03

   • The document contains a general description concerning the submission of data to the Incomes Register.

   • The document describes the reporting of wages and social insurance premiums and contains examples of how to correct submitted information.

2. Descriptions of income types and items deducted from income (pdf), 29 January 2018, version 1.03

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

3. Application instructions on the data contents of an earnings payment report (pdf), 29 January 2018, version 1.03

   • The document contains a description of the data content in earnings payment report and what to report under each individual section.

4. Application instructions for the employer's separate report (pdf), 14 November 2017, version 1.01

   • The document describes data content in employer´s separate reports and covers what to report under each individual section.

Benefits

1. Benefits – Reporting data to the Incomes Register (pdf), 13 June 2018, version 1.00
   
   • The document contains a general description of reporting benefits payment data to the Incomes Register.
   • The document uses examples to describe the most common situations concerning reporting benefits payment data to the Incomes Register.
     
     
2. Benefits – Descriptions of income types and items deducted from income (pdf), 13 June 2018, version 1.00
   
   
   • 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.
     
     
3. Application instructions on the data contents of a benefits payment report (pdf), 13 June 2018, version 1.00
   
   
   • 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 (pdf), 11 June 2018, version 1.04

   • 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 (pdf), 7 January 2019, version 1.07

   • 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 (pdf), 7 January 2019, version 1.03

Content descriptions of schemas

1. Data delivery – Schemas – Earnings payment reports (pdf), 8 November 2018, version 1.07

   • 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 (pdf), 6 March 2019, version 1.06

   • 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), 8 March 2019, version 1.03

   • This document presents the BenefitReportsToIR schema used for submitting benefits payment reports to the Incomes Register.

4. Data delivery – Schemas – Record subscriptions (pdf), 7 January 2019, version 1.07

   • This document presents the SubscriptionsToIR schema, which is used for submitting record subscriptions to the Incomes Register.

5. Data delivery – Schemas – Messages (pdf), 26 September 2018, version 1.05

   • This document presents the MessagesToIR schema, by which messages are delivered to the Incomes Register.

6. Data delivery – Schemas – Cancellation data (pdf), 26 September 2018, version 1.05

   • This document presents the InvalidationsToIR schema, which is used for cancelling earnings reports, record subscriptions and records from the Incomes Register.

7. Data delivery – Schemas – Acknowledgement of receipt (pdf), 26 September 2018, version 1.04

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

8. Data delivery – Schemas – Request for processing feedback (pdf), 26 September 2018, version 1.05

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

9. Data delivery – Schemas – Processing feedback (pdf), 26 September 2018, version 1.04

   • This document presents the StatusResponseFromIR schema, by which the Incomes Register delivers a processing feedback to record submitted to the register.

10. Data distribution – Schemas – Service Request (pdf), 7 January 2019, version 1.06

    • This document presents the DataRequestToIR schema, which is used for submitting a service request for data distribution (real-time Web Service interface).

11. Data distribution – Schemas – Earnings payment reports (pdf), 26 September 2018, version 1.05

    • This document presents the WageReportsFromIR schema, which is used to distribute earnings payment reports from the Incomes Register.

12. Data distribution – Schemas – Employer's separate reports (pdf), 26 September 2018, version 1.05

    • This document presents the PayerSummaryReportsFromIR schema, by which employer´s separate reports are distributed from the Incomes Register.

13. Data distribution – Schemas – Benefits payment reports (pdf), 8 March 2019, version 1.02

    • This document presents the BenefitReportsFromIR schema, by which benefits payment reports are distributed from the Incomes Register.

14. Data distribution – Schemas – Messages (pdf), 26 September 2018, version 1.04

    • This document presents the MessagesFromIR schema, by which messages are distributed from the Incomes Register.

15. Data distribution – Schemas – Log Data (pdf), 26 September 2018, version 1.04

    • This document presents the LogDataFromIR schema, by which log data are distributed from the Incomes Register.

16. Data distribution – Schemas – Summary of payer's earnings payment data (pdf), 26 September 2018, version 1.02
    
    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 (pdf),  23 May 2019, version 1.15

• Codes used in the technical interface of the Incomes Register. The codes for the income types are presented in a separate document.
• Codes (xls), 23 May 2019, version 1.15

2. Codes – Income types (pdf), 26 September 2018, version 1.05

• Codes for income types and deductibles on earnings payment reports, reporting modes and social insurance premiums used as default in the income types.

• Employer´s separate report: codes for income types.

• Codes - Income types (xls), 26 September 2018, version 1.04

3. Benefits – Codes – Income types (pdf), 13 June 2018, version 1.00

• The codes and reporting methods of the benefits payment report's income types and items deductible from income.
• Benefits – Codes – Income types (xls), 13 June 2018, version 1.00

 4. Codes - Error codes (xls), 15 May 2019, version 1.08

• Codes in Finnish: Koodistot - Virhekoodit (xls), 11 June 2019, version 1.09

• Codes in Swedish: Koduppsättningar – Felkoder (xls), 15 May 2019, version 1.08

5. Codes – Classification of Occupations (18.5.2018)

• Classification of Occupations maintained by Statistics Finland and used in the Incomes Register is available on the Statistics Finland website in section Incomes Register.

Application developer’s guidelines

1. Technical interface – Application guidelines (pdf),  21 March 2018, version 1.03

   • 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 21 January 2019, version 1.10

   • A ZIP file that contains xsd descriptions, examples of the structure of schemas, and WSDL descriptions of services.

3. Technical interface – ZIP file for application developers (pdf), 21 January 2019, version 1.10

   • 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: Employer with insurance contract, basic case (pdf), 14.11.2017, version 1.0

2. Example 002: Temporary employer (pdf), 14.11.2017, version 1.0

3. Example 003: Foreign payer, foreign income earner (pdf), 14.11.2017, version 1.0

4. Example 004: Public sector payer (pdf), 14.11.2017, version 1.0

5. Example 005: Work abroad (pdf), 14.11.2017, version 1.0

6. Example 006: Insurance exception 1, foreign employer (pdf), 14.11.2017, version 1.0

7. Example 007: Insurance exception 2, based on age (pdf), 14.11.2017, version 1.0

8. Example 008: Income earner is a non-resident taxpayer (pdf), 14.11.2017, version 1.0

9. Example 009: Insurance information type for income type (pdf), 14.11.2017, version 1.0

10. Example 010: Absence data (pdf), 14.11.2017, version 1.0

11. Example 011: Unjust enrichment, overpayment previously reported as other income (pdf), 22.1.2018, version 1.0

12. Example 012: Unjust enrichment, overpayment noticed before report is submitted (pdf), 22.1.2018, version 1.0

13. Example 013: Recovery, gross recovery (pdf), 22.1.2018, version 1.0

14. Example 014: Recovery 2, net recovery (pdf), 22.1.2018, version 1.0

15. Example 015: Recovery 3, gross recovery, contains several income types (pdf), 22.1.2018, version 1.0

16. Example 016: Recovery 4, entire amount recovered at the same time (pdf), 22.1.2018, version 1.0

17. Example 17: Reimbursement of expenses (pdf), 23.4.2018, version 1.0

18. Example 18: Non-wage compensation for work, the income earner is a natural person (pdf), 23.4.2018, version 1.0

19. Example 19: Non-wage compensation for work, the income earner is an organisation (pdf), 23.4.2018, version 1.0

20. Example messages – Data delivery – Earnings payment reports – ZIP, 22.1.2018, version 1.01

• A ZIP file containing the XML files related to the example messages. Every example message is related to two files: the schema with which the information is delivered to the Incomes Register and the processing feedback provided to the report submitter in the example case.

Example messages: Data delivery – Record subscription

The documents contain examples of situations involving the delivery of record subscriptions.

1. Example 001: Earnings payment reports – all income earners, recurrent subscription (pdf), 15 December 2017, version 1.0

2. Example 002: Earnings payment reports – several income earners 1, recurrent subscription (pdf), 15 December 2017, version 1.0

3. Example 003: Earnings payment reports – several income earners 2, one-off subscription (pdf), 8 January 2018, version 1.01

4. Example 004: Earnings payment reports – several payers 1, recurrent subscription (pdf), 15 December 2017, version 1.0

5. Example 005: Earnings payment reports – several payers 2, one-off subscription (pdf), 8 January 2018, version 1.01

6. Example 006: Earnings payment reports – several payers, several income earners, recurrent subscription (pdf), 8 January 2018, version 1.01

7. Example 007: Earnings payment reports – several records, one-off subscription (pdf), 8 January 2018, version 1.01

8. Example messages – Data delivery – Record subscription – ZIP, 8 January 2018, version 1.01

• A ZIP file containing the XML files related to the example messages. Every example message is related to two files: the schema with which the data is delivered to the Incomes Register and the processing feedback provided to the report submitter in the example case.

 Sample implementation of message signing

1. Technical interface - ZIP - message signing, sample implementation (pdf), 23 March 2018, version 1.0

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