Documentation

Wages – Descriptions of income types and items deducted from income 2022 (pdf)

• Published on 15 August 2022
• The document describes
  • the income types of the earnings payment report used in the Incomes Register, code values of the income types and their descriptions
  • tax withholding and payment of social insurance contributions for each income type
  • the situations in which the income types are used.

• The description of income type 334 was changed.

Application instructions on the data contents of an earnings payment report 2022 (pdf)

• Published on 15 June 2022
• The document describes data content in earnings payment report and covers what to report under each individual section.

Application instructions on the data contents of an earnings payment report 2023 (pdf)

• Published on 15 June 2022

Document for 2022:

• Updates were made to reason code 3 and reason code 4 due to changed legislation on paid family leave. The changes apply when the payment date of the income is on 1 August 2022 or later.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• Updates were made to reason code 3 and reason code 4 due to changed legislation on paid family leave.

Application instructions for the employer's separate report 2022 (pdf)

• Published on 7 June 2021
• The document describes data content in employer´s separate report and covers what to report under each individual section.

• Document for 2022 published.
• Added a new data group, Other payer details (PayerOther), to the Payer details (Payer) data group

• Previous versions of data content application guidelines for wages

Benefits – Descriptions of income types and items deducted from income 2022 (pdf)

• Published on 11 March 2022
• The document describes
  • the benefits and pensions reported to the Incomes Register, with code values and descriptions
  • the situations in which the income types are used.

Benefits – Descriptions of income types and items deducted from income 2023 (pdf)

• Published on 28 October 2022

Document for 2022:

• Added the new income types 1422, 1423, 1424, and 1425.
• More complete names for the 1001, 1002, 1003, 1004 and 1005 income types were added.

Document for 2023:

• Added the income types 1427, 1428, 1429, 1430, 1431 and 1432.

Application instructions on the data contents of a benefits payment report 2022 (pdf)

• Published on 9 August 2022
• The document describes data content in benefits payment report and covers what to report under each individual section.

Application instructions on the data contents of a benefits payment report 2023 (pdf)

• Published on 9 August 2022

Document for 2022:

• Refined, where more detailed instructions can be found on the use of the 'Benefit unit'.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• Refined, where more detailed instructions can be found on the use of the 'Benefit unit'.

• Previous versions of data content application guidelines for benefits

Wages - Codes - Income types 2022 (xls)

Wages – Codes – Income types 2022 (pdf)

• Published on 6 June 2022
• The document contains
  • the codes for income types and deductibles on earnings payment report, reporting modes and social insurance premiums used as default in the income types
  • the codes for income types on employer´s separate report.

• Added to the excel file the ‘Markings used in the document’ section.

Benefits – Codes – Income types 2022 (xls)

Benefits – Codes – Income types 2022 (pdf)

• Published on 6 June 2022
• The document contains the codes for the income types of the benefits payment report, codes for the items deducted from income, reporting methods and whether additional information is mandatory.

Benefits – Codes – Income types 2023 (xls)

Benefits – Codes – Income types 2023 (pdf)

• Published on 28 October 2022

Document for 2022:

• Added to the excel file the ‘Markings used in the document’ section.

Document for 2023:

• Added the income types 1427, 1428, 1429, 1430, 1431 and 1432.

Codes 2022 (xls)

Codes 2022 (pdf)

• Published on 11 March 2022
• The document contains the codes used in the technical interface of the Incomes Register.

Codes 2023 (xls)

Codes 2023 (pdf)

• Published on 6 June 2022

Document for 2022:

• Changed the Labels for values 3 and 4 under Reason for paid absence (PaidAbsenceCauseCode).
• Changed the Labels for values 3 and 4 under Reason for unpaid absence (UnpaidAbsenceCauseCode).

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• The following value added to the Additional income earner data (IncomeEarnerTypes) codes: 16 Person receiving wages for insurance purposes under the Act on EPPO.
• The following value removed from the Deduction type (DeductionType) codes: 8 Deduction of employee contributions.

Codes - Error codes 2022 (xls)

• Published on 11 August 2022

• The codes contain the descriptions for the error codes of the technical interface.

Codes - Error codes 2023 (xls)

• Published on 11 August 2022

Document for 2022:

• The error code descriptions can be 450 characters long. In addition, the descriptions will be clarified and specified.
• The updated descriptions of error codes will be in use in prodution in November 2022.

Document for 2023:

• The error code descriptions can be 450 characters long. In addition, the descriptions will be clarified and specified.
• The updated descriptions of error codes will be in use in prodution in November 2022.

Incomes Register´s Classification of Occupations (TK10) (stat.fi)

• The Incomes Register uses the Incomes Register´s Classification of Occupations (TK10) that is available on Statistics Finland’s website.
• In the Incomes Register system, the classification is under the name ‘Statistics Finland’s classification of occupations (TK10)’.

• The classification of occupations has been renamed:
  • The new name is Incomes Register´s Classification of Occupations (TK10)
  • previously Statistics Finland’s Classification of occupations (TK10)

• Previous versions of codes

Transcripts from the Incomes Register 2022 (pdf)

• Published on 11 October 2022
• The document describes the transcripts generated from the Incomes Register for data providers, data users and income earners.

• Printed transcripts in CSV format (618, 619, 620, 621, 630, 632 and 710) have been completed with information that they can be downloaded in ZIP format as well.
• Printed transcripts in ZIP format will available in November 2022.

Income data – Calculation rules 2021 (pdf)

• Published on 7 October 2021
• The document describes how the information for the Incomes Register transcripts is calculated.

Income data – Calculation rules 2023 (pdf)

• Published on 6 June 2022

Document for 2021:

• Added new calculation rules.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• Calculation rule further specified: Type of deduction “Deduction of employee contributions” removed from rule 3.2.4, Deductions from gross payments total (BenefitGrossDeductionTotal).

• Previous versions of content descriptions of transcripts

Technical interface – Submitting data to the Incomes Register 2021 (pdf)

• Published on 6 June 2022
• The document
  • provides an overview of how data is submitted via the technical interface and the upload service
  • describes the data reception services of the Incomes Register and the structure of the records to be submitted
  • describes the recommendations for submitting data.

• Clarified the description of the cancellation and ending of a record subscription in Section 9.3.2.

Data delivery – Schemas – Earnings payment reports 2022 (pdf)

• Published on 9 August 2022
• The document describes the schema WageReportsToIR, which is used to submit earnings payment reports to the Incomes Register.

Examples of submitting earnings payment reports. The examples were published on 17 September 2021.

• Example 001: Exceptional insurance data – Income type 328 (pdf)
• Example 002: Exceptional insurance data – Income types 341 and 363 (pdf)
• Example 003: Unjust enrichment and recovery (pdf)
• Example 004: Type of additional income earner data: Key employee (pdf)
• Example 005: "Net-of-tax" employment contract (pdf)
• Example 006: Non-resident taxpayer (pdf)
• Example 007: Self-employed person, no obligation to take out YEL or MYEL insurance (pdf)

Data delivery – Schemas – Earnings payment reports 2023 (pdf)

• Published on 9 November 2022

Document for 2022:

• Added new processing rules for the Start date of the time period for reporting absences (AbsenceRepStartDate) and the End date of the time period for reporting absences (AbsenceRepEndDate) in the Absences (Absence) data group:
  • This information is mandatory if the report contains at least one Paid absence.
  • This information is mandatory if the report contains at least one Unpaid absence.
• Corrected ‘Data Designation ’ data in the data group ‘Countries of work’ (WorkCountries): Data Designation ´Country of work (WorkCountries)´ changed to ‘Country of work (WorkCountry)´. Added the correction to table Earnings payment reports (WageReportsToIR). The correction has no impact on the implementation.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• Added a new processing rule for the Number of days of absence (AbsenceDays) in the Paid Absence (PaidAbsence) data group: The value must be a non-negative number. The correction has no impact on the implementation.

Data delivery – Schemas – Employer's separate reports 2022 (pdf)

• Published on 6 June 2022
• The document describes the schema PayerSummaryReportsToIR, which is used to submit employer´s separate reports to the Incomes Register.

Examples of submitting employer’s separate reports. The examples were published on 17 September 2021.

• Example 001: Payer type and validity of pension policy number (pdf)

• Corrected the incorrect name of the schema name space in Section 1.1 ‘Schema – the employer’s separate report’. The correction has no impact on the implementation.
• Corrected ‘Type’ data in the general record structure described in Section 2 ‘Employer’s separate reports’ (PayerSummaryReportsToIR): type ‘psrfirt:’ changed to ‘psrtirt:’. In addition, corrected the location of the data groups ‘Service data’ (ReportData), ‘Reporting period’ (PaymentMonth) and ‘Income types’ (Transactions) in the general record structure described in Section 2 ‘Employer’s separate reports’ (PayerSummaryReportsToIR): the data groups transferred directly under the data group ‘Report’ (Report) from under ‘Report data’ (Reports). These corrections have no impact on the implementation.

Data delivery – Schemas – Benefits payment reports 2022 (pdf)

• Published on 6 June 2022
• The document describes the schema BenefitReportsToIR, which is used to submit benefits payment reports to the Incomes Register.

Examples of submitting benefits payment reports. The examples were published on 22 February 2021.

• Example 001: Compensation for loss of earnings (motor liability insurance), related deduction of employee contributions and tax withholding (pdf)
• Example 002: Partial disability pension paid retroactively when the income earner has already received sickness allowance (pdf)
• Example messages: Data delivery – Benefits payment report (zip)

Data delivery – Schemas – Benefits payment reports 2023 (pdf)

• Published on 6 June 2022

Document for 2022:

• Corrected ‘Type’ data in the data group ‘Additional recourse details’ (RecourseData): type ‘brtirt:RecourseData’ changed to ‘brfirt:RecourseData’. In addition, this missing data group was added to the general record structure described in Section 2 ‘Benefits payment reports’ (BenefitReportsFromIR). The correction has no impact on the implementation.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• In data group Basic substitute recipient details (IncomeBeneficiaryBasic): A new processing rule added for the data Substitute recipient does not have a customer identifier (MissingId): If the “Action type” is “Replacement report”, the data should match that of the report’s previous version.

Data delivery – Schemas – Record subscriptions 2021 (pdf)

• Published on 1 June 2020
• The document describes the schema SubscriptionsToIR, which is used to submit record subscriptions to the Incomes Register.

• Published a version of the document containing the 2021 changes to the data contents.
• Added a new possible code value 950 (Rejected reports submitted on paper form) for the Record type (QueryDataType) element in the Secondary subscriptions (Subscriptions) data group.
• Removed the mention that there may be several query criteria from the query criteria (SubscriptionParameters). It is stated on the main level of the data group that the number of query criteria is record type specific.

Data delivery – Schemas – Cancellation data 2021 (pdf)

• Published on 6 June 2022
• The document describes the schema InvalidationsToIR, which is used for cancelling incomes payment reports, record subscriptions and records from the Incomes Register.

Data delivery – Schemas – Cancellation data 2023 (pdf)

• Published on 6 June 2022

Document for 2021:

• Clarified the processing rules of the cancellation and ending of a record subscription in Section 2.2 'Items to be cancelled (Items)'.

Document for 2023:

• A version of the document containing the 2023 changes to the data content has been published.
• The changes apply when the income payment date is 1 January 2023 or a later.
• Data source (Source) processing rule in the data group Delivery data (DeliveryData) further specified to also cover records 107 Cancellation of benefits payment reports and 111 Cancellation of a record containing benefits payment reports.

Data delivery – Schemas – Acknowledgement of receipt 2021 (pdf)

• Published on 1 June 2020
• The document describes the schema AckFromIR, which the Incomes Register uses to delivers an acknowledgement of receipt for the record submitted to the register.
• The schema is used in the deferred Web Service interface.

• Contents of the document correspond to the document for 2020.

Data delivery – Schemas – Request for processing feedback 2021 (pdf)

• Published on 6 June 2022
• The document describes the schema StatusRequestToIR, by which the record submitter can submit a request for processing feedback to the Incomes Register concerning the submitted record.
• The schema is used in the deferred Web Service interface.

• Corrected ‘Type’ data in the data groups ‘Record owner’ (DeliveryDataOwner), ‘Record creator’ (DeliveryDataCreator) and ‘Record sender’ (DeliveryDataSender): type ‘mtirt:Id’ changed to ‘smt:Id’. The correction has no impact on the implementation.

Data delivery – Schemas – Processing feedback 2021 (pdf)

• Published on 1 June 2020
• The document describes the schema StatusResponseFromIR, by which the Incomes Register delivers a processing feedback to record submitted to the register.

• Contents of the document correspond to the document for 2020.

• Previous versions of content descriptions of data delivery

Technical interface – Distribution of data from the Incomes Register 2022 (pdf)

• Published on 6 June 2022
• The document
  • provides an overview of the distribution of data from the Incomes Register via the technical interface
  • describes the services distributing data from the Incomes Register and the structure of the records to be distributed
  • describes the query criteria for the records distributed on the basis of a record subscription
  • describes the recommendations for the distribution
  • describes the records for payers Summary of payer’s earnings payment data (312/313).

• Deleted the reference to message exchange in the figures 3 and 4. This correction of an error has no impact on the implementation of the system.

Data distribution – Schemas – Earnings payment reports 2022 (pdf)

• Published on 6 June 2022
• The document describes the schema WageReportsFromIR, which is used to distribute earnings payment reports from the Incomes Register.

• Corrected ‘Type’ data in the data group ‘Details on foreign leased workforce’ (ForeignLeasedWork): type ‘wrtirt:ForeignLeasedWork’ changed to ‘wrfirt:ForeignLeasedWork’. The correction has no impact on the implementation.
• Corrected the name of the data group in the data group ‘Details on foreign leased workforce’ (ForeignLeasedWork): the name ‘Finnish employers (FinServiceRecipients)’ changed to ‘Finnish employer (FinServiceRecipient)’. The correction has no impact on the implementation.
• Corrected permitted values in the data group ‘Representative’ (Representative): added the permitted value ‘true’ that was missing from the element ‘Representative acts as submitter’ (RepresentativeReports). The correction has no impact on the implementation.
• Corrected ‘Type’ data in the data group ‘Unpaid absence’ (UnpaidAbsence): type ‘wrfirt:UnpaidAbsencePeriods’ changed to ‘wrfirt:UnpaidAbsence’. The correction has no impact on the implementation.
• Corrected ‘Type’ data in the data group ‘Paid absence’ (PaidAbsence): type ‘wrfirt:PaidAbsencePeriods’ changed to ‘wrfirt:PaidAbsence’. The correction has no impact on the implementation.

Data distribution – Schemas – Employer's separate reports 2022 (pdf)

• Published on 3 February 2022
• The document describes the schema PayerSummaryReportsFromIR, which is used to distribute employer´s separate reports from the Incomes Register.

• The codeset for permissible values is now corrected, i.e. changed to PayerSubOrgType under the 'Suborganisation's identifier type' in the 'Payer's suborganisations' element.

Data distribution – Schemas – Benefits payment reports 2021 (pdf)

• Published on 6 June 2022
• The document describes the schema BenefitReportsFromIR, which is used to distribute benefits payment reports from the Incomes Register.

• Corrected ‘Type’ data in the data group ‘Additional recourse details’ (RecourseData): type ‘brtirt:RecourseData’ changed to ‘brfirt:RecourseData’. In addition, this missing data group was added to the general record structure described in Section 2 ‘Benefits payment reports’ (BenefitReportsFromIR). The correction has no impact on the implementation.

Data distribution – Schemas – Service Request 2021 (pdf)

• Published on 1 June 2020
• The document describes the schema DataRequestToIR, which an Incomes Register data user uses to submit a service request (requests information from the Incomes Register).
• The schema is used in the real-time Web Service interface.

• Contents of the document correspond to the document for 2020.

Data distribution – Schemas – Log Data 2021 (pdf)

• Published on 6 June 2022
• The document describes the schema LogDataFromIR, which is used to distribute log data from the Incomes Register.

• Corrected the name of element in the data group ‘Query summary data ’ (Summary): the name of element ‘The number of queried items (NrOfReports)' changed to ‘The number of queried items (NrOfEvents)'. The correction has no impact on the implementation.
• Corrected ‘Type’ data in the data group ‘Log event targets (TargetItems)': type "mfirt:QueryTargetItem" changed to "ldt:QueryTargetItem". The correction has no impact on the implementation.

Data distribution – Schemas – Summary of payer's earnings payment data 2021 (pdf)

• Published on 6 June 2022
• The document describes the schema WageReportSummaryFromIR, which is used to distribute the summary of payer’s earnings payment data (312/313) from the Incomes Register.
• The record is intended for payers of contributions.

• Missing ‘Type’ data of data groups were added to the general record structure described in Section 2 ‘Summary of payer's earnings payment data (WageReportSummaryFromIR)‘. The correction has no impact on the implementation.

Data distribution – Schemas – Rejected reports submitted on paper form 2021 (pdf)

• Published on 26 January 2022
• The document describes the schema RejectedPaperReportsFromIR, which is used to distribute the Rejected reports record submitted on paper form (950) from the Incomes Register. The record contains the rejected earnings payment reports and employer’s separate reports submitted on paper form.

• Corrected the Type of the "Report data" data group's Record's clearance reference element. The Type is now irct:String40.

• Previous versions of content descriptions of data distribution

Technical interface – Application guidelines 2021 (pdf)

• Published on 24 May 2022
• This document describes the principles governing the implementation of the technical interface of the Incomes Register from the perspective of the party implementing system integration.

• More precise information was added under 7.1.2 regarding SOAP errors.

Technical interface – ZIP file for application developers 2022 (zip)

Technical interface – ZIP file for application developers 2022 (pdf)

• Published on 21 October 2021
• The ZIP file that contains xsd descriptions and WSDL descriptions of services.
• The PDF document describes the ZIP file’s contents.

• Published a version of the document containing the 2022 changes to the data contents.

Technical interface – Message signing, sample implementation (zip)

Technical interface – Message signing, sample implementation (pdf)

• Published on 23 March 2018
• The ZIP file contains a client implementation of a call sent to the Echo service (EchoService) and the signing of the request message sent.
• The PDF document describes the ZIP file’s contents.

• Previous versions of application developer's guidelines