Documentation

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

• Published on 28 June 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 319 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:

• Updates were made to reason code 3 and reason code 4 due to changed legislation on paid family leave.
• Published a version of the document containing the 2023 changes to data content and other updates of the Incomes Register Unit. The changes apply when the income payment date is 1 January 2023 or later.
  • In Occupational accident insurance (AccidentInsurance), a note was added that the occupational accident insurance policy number must not contain non-printable whitespace characters, such as spaces.
  • In the Additional income earner details (IncomeEarnerTypes), a note was added that the type of additional income earner data Organisation cannot be used if the type of income earner identifier is Finnish personal identity code.
  • A new type of additional income earner data, Person receiving wages for insurance purposes under the EPPO Act, and a description for the type added in Additional income earner data (IncomeEarnerTypes).

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

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.

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

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

• Published on 25 January 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 10 June 2022

Document for 2022:

• Clarified the description 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 date.
  • From the Type of deduction codes in the Deduction details (Deduction) data group, code value 8, Deduction of employee contributions, removed.
  • Typographical errors corrected: IncomeEarnerType (16) changed to "Person receiving wages for insurance purposes under the Act on EPPO".

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 6 June 2022

Document for 2022:

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

Document for 2023:

• Published a version of the document containing the 2023 changes to data content. The changes apply when the payment date of the income is on 1 January 2023 or later.
  • For the income types 1001, 1002, 1003, 1004, 1005, 1422, 1423, 1424 and 1425, the “Benefit unit” data has been made mandatory.

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:

• Published a version of the document containing the 2023 changes to data content. The changes apply when the payment date of the income is on 1 January 2023 or 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 28 June 2022

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

Codes - Error codes 2023 (xls)

• Published on 28 June 2022

Document for 2022:

• Description of error code AV0350 was updated.

Document for 2023:

• Changed code's AV0350 text.

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)

Transcripts from the Incomes Register 2022 (pdf)

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

• An extra line was removed from the Query criteria for reports 610 and 611 under 15 - Payer's suborganisation identifier. This way, the new version no longer makes reference to Benefit payer’s suborganisation identifier type, which had been incorrect. This correction of an error has no impact on the implementation of the system.

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 date.
  • Calculation rule further specified: Type of deduction “Deduction of employee contributions” removed from rule 3.2.4, Deductions from gross payments total (BenefitGrossDeductionTotal).

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 15 June 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 15 June 2022

Document for 2022:

• Data group Paid Absence (PaidAbsence): updates were made to reason code 3 and reason code 4. The changes apply when the payment date of the income is on 1 August 2022 or later.

Document for 2023:

• Data group Paid Absence (PaidAbsence): updates were made to reason code 3 and reason code 4.
• Published a version of the document containing the 2023 changes to the data contents. The changes apply when the payment date of the income is on 1 January 2023 or later.
  • A table of non-printable whitespace characters that are not to be included in the occupational accident insurance policy number added to Section 1.2.
  • A processing rule added to the Income earner’s identifier data group (IncomeEarnerIds): If the “Identifier type” is “Finnish personal identity code”, the type of additional income earner data cannot be “Organisation”.
  • A processing rule added in the Occupational accident insurance data group (AccidentInsurance) for the data Occupational accident insurance policy number (AccInsPolicyNo): The data must not contain non-printable whitespace characters, such as spaces.
  • A processing rule for the data group General details on the income type (TransactionBasic) added for the Six-month rule (SixMonthRule) data type: The data cannot be provided if the “Income earner type” (IncomeEarnerType) specified in the report is “Person receiving wages for insurance purposes under the EPPO Act” (16).

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’: name ‘http://www.tulorekisteri.fi/2017/1/PayerSummaPayerSummaryR’ changed to ‘http://www.tulorekisteri.fi/2017/1/PayerSummaryReportsToIR’. 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:

• Published a version of the document containing the 2023 changes to data content. The changes apply when the payment date of the income is on 1 January 2023 or 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 date.
  • 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.

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.

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.