Documentation

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

• Published on 21 December 2023
• 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.

• Clarified descriptions of the following income types:
  • 213 Holiday bonus
  • 224 Monetary compensation from a working time bank
  • 225 Compensation for accrued time off
  • 321 Wages paid by substitute payer: employer pays for employer’s social insurance contributions (earnings-related pension, health, unemployment, and accident and occupational disease insurance contributions)
  • 322 Wages paid by substitute payer: employer pays for employer’s earnings-related pension insurance contribution
  • 323 Wages paid by substitute payer: employer pays for employer’s unemployment insurance contribution
  • 324 Wages paid by substitute payer: employer pays for employer’s accident and occupational disease insurance contribution
  • 325 Wages paid by substitute payer: employer pays for employer’s health insurance contribution
  • 327 Reimbursement of private caretaker’s expenses
  • 328 Private caretaker’s fee
  • 316 Other taxable income deemed earned income
  • 353 Taxable reimbursement of expenses
  • 354 Private day care allowance municipal supplement

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

• Published on 22 May 2023
• 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 2025 (pdf)

• Published on 5 November 2024

Document for 2024:

• Published a version of the document containing the 2024 changes to data content and other updates of the Incomes Register Unit. The changes apply when the income payment date is 1 January 2024 or later.
• Added new value ‘A self-employed “light” entrepreneur, a client of an invoicing service, no Business ID’ for Type of additional income earner data (IncomeEarnerType).

Document for 2025:

• 3 June 2024:
  • Published a version of the document containing the 2025 changes to data content and other updates of the Incomes Register Unit. The changes apply when the income payment date is 1 January 2025 or later.
  • Added new reason for absence in data designation Paid Absence (PaidAbsence): Compensation for annual leave costs.
  • Added new payment data type in data designation Reimbursement application data (ReimbApp): Compensation for annual leave costs.
• 3 June 2024:
  • The following value removed from the Type of additional income earner data (IncomeEarnerType) data: Employed with assistance from the State employment fund

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

• Published on 27 December 2022
• The document describes data content in employer´s separate report and covers what to report under each individual section.

• Added Introduction and Reading instructions.

• Previous versions of data content application guidelines for wages

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

• Published on 21 August 2023
• 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 2025 (pdf)

• Published on 5 November 2024

Document for 2023:

• Corrected translation income types 1125, 1168, 1432 "physiotherapy" to "physical treatment".
• Translation corrected for income type 1427 "Disability pension" to "Occupational accident pension".

Document for 2025:

• 3 June 2024:
  • Published a version of the document containing the 2025 changes to data content.
  • Added the following new income types: 1433, 1434, 1435, 1436, 1437, 1438, 1439, 1440, 1441, 1442, 1443 and 1444.
  • The validity of the following income types has ended 31 December 2024 and they have been removed: 1130, 1131, 1134, 1125, 1126 and 1124.
  • Income types 1092 and 1328 have been removed from all years.
    Description for income types 1085 and 1289 updated.
• 3 June 2024:
  • The name and description for income type 1218 have been updated.
  • Description for income types 1026, 1043 and 1047 updated.

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

• Published on 12 December 2023
• The document describes data content in benefits payment report and covers what to report under each individual section.

• In the instructions for the data item ‘Original payment period (OrigEarningPeriod)’, it has been clarified when the repayment date or another date in the same month can be reported as the end date of a payment period.
• Corrected the Type of substitute recipient Municipality or another social welfare body -type definition, so that the municipality has been changed to wellbeing services counties. In addition added a mention, that a municipality may have been a substitute recipient on reports with a date of payment or other reporting date 31.12.2022 or earlier.
• Refined the reporting of benefit unit data in the Benefit unit (BenefitUnit) instructions, when reporting partial parental allowance.

• Previous versions of data content application guidelines for benefits

Wages – Codes – Income types 2024 (xls)

Wages – Codes – Income types 2024 (pdf)

• Published on 10 October 2023
• 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.

• Corrected translation "employee's pension insurance contribution" to "employee's earnings-related pension insurance contribution".

Benefits – Codes – Income types 2023 (xls)

Benefits – Codes – Income types 2023 (pdf)

• Published on 21 August 2023
• 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 2025 (xls)

Benefits – Codes – Income types 2025 (pdf)

• Published on 5 November 2024

Document for 2023:

• Corrected translation income types 1125, 1168, 1432 "physiotherapy" to "physical treatment".
• Translation corrected for income type 1427 "Disability pension" to "Occupational accident pension".

Document for 2025:

• 3 June 2024:
  • Published a version of the document containing the 2025 changes to data content. The changes apply when the payment date of the income is on 1 January 2025 or later.
  • Income types 1092 and 1328 have been removed from all years.
  • Added the income types 1433, 1434, 1435, 1436, 1437, 1438, 1439, 1440, 1441, 1442, 1443 and 1444.
  • The validity of the following income types has ended 31 December 2024 and they have been removed: 1130, 1131, 1134, 1125, 1126 and 1124.
• 5 November 2024:
  • Updated the name of income type 1218.

Codes 2024 (xls)

Codes 2024 (pdf)

• Published on 5 November 2024
• The document contains the codes used in the technical interface of the Incomes Register.

Codes 2025 (xls)

Codes 2025 (pdf)

• Published on 5 November 2024

Document for 2024:

• Added the following value to the codeset Applicable collective agreement (CBACode): 224 Collective Agreement for Universities of Applied Sciences

Document for 2025:

• 3 June 2024:
  • Published a version of the document containing the 2025 changes to data content. The changes apply when the payment date of the income is on 1 January 2025 or later.
  • Added the following value to codeset Reason for paid absence (PaidAbsenceCauseCode): 23 Compensation for annual leave costs
  • Added the following value to codeset Payment data type, compensation application (ReimbPaymentType): 3 Kela, compensation for annual leave costs
• 5 November 2024:
  • The following value removed from the Type of additional income earner data (IncomeEarnerType) codes: 1 Employed with assistance from the State employment fund
  • Added the following value to the codeset Applicable collective agreement (CBACode): 224 Collective Agreement for Universities of Applied Sciences

Codes – Error codes 2024 (xls)

• Published on 13 August 2024
• The codes contain the descriptions for the error codes of the technical interface.

Codes – Error codes 2025 (xls)

• Published on 13 August 2024

Document for 2024:

• The following error code added: PIV0150

Document for 2025:

• 3 June 2024:
  • Document for 2025 published.
  • The following error codes added: AV0380, BEV0530, IEV0140.
  • Description of error codes were updated for the following error codes: AV0230, AV0280, AV0290, AV0300, AV0310, AV0320, AV0330, AV0340, AV0360, EV0070, TRVA0390.
• 13 August 2024:
  • The following error code added: PIV0150

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

• The name of the Incomes Register's own occupational classification is “Incomes Register’s Classification of Occupations (TK10)”, but the old name “Statistics Finland’s Classification of Occupations (TK10)” is still used in the Incomes Register systems.
• Classification is available on Statistics Finland’s website.

• Previous versions of codes

Transcripts from the Incomes Register 2024 (pdf)

• Published on 5 November 2024
• The document describes the transcripts generated from the Incomes Register for data providers, data users and income earners.

• Published a version of the document containing the 2024 changes to data content.
• The parameter type for Report 610 has been changed from "Time range of the target period" to "Time range of receipt”.

Income data – Calculation rules 2023 (pdf)

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

• Corrected translation "employee's pension insurance contribution" to "employee's earnings-related pension insurance contribution".

• 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 2024 (pdf)

• Published on 11 September 2023
• The document describes the schema WageReportsToIR, which is used to submit earnings payment reports to the Incomes Register.

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

• Published on 3 June 2024

Document for 2024:

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

Document for 2025:

• Published a version of the document containing the 2025 changes to the data contents. The changes apply when the payment date of the income is on 1 January 2025 or later.
• Added a processing rule for the Original payment period (OrigPaymentPeriod) data in the Additional details on recovery (RecoveryData) data group:
  • The income type code for a recovery must be valid partially or completely during all the original payment periods or dates of payment.
• Added new value to processing rule for the Payment data type (PaymentType) data in the Paid Absence (PaidAbsence) data group: 2 (part-time sick leave)
• Added a processing rule for the Identifier type (Type) data in the Occupational accident insurance (AccidentInsurance) data group:
  • Type of identifier must not be a “Personal Identification Number (Finnish)” or a “Foreign personal identification number”
• Added a new value "3 (Kela, compensation for annual leave costs)" to processing rules for
  • the E-mail address (Email) and Field of responsibility (ResponsibilityCode) data in the Contact persons for the record (ContactPersons) data group
  • the Identifier type (Type) data in the Payer identifiers (PayerIds) data group
  • the Identifier type (Type) data in the Income earner identifiers (IncomeEarnerIds) data group
  • the Start date (StartDate), Employment period (EmploymentPeriods), Forms of payment (PaymentTypes), Form of payment (PaymentType) and Employment type (EmploymentCode) data in the Employment relationship data (Employment) data group
  • the End date (EndDate) and Payment data (ReimbPayment) data in the Paid Absence (PaidAbsence) data group
• Added a processing rule for the Payment data type (PaymentType) data in the Paid Absence (PaidAbsence) data group:
  • If ‘Payment data type’ = 3 (Kela, compensation for annual leave costs), the ‘Reason for paid absence’ must be 23 (compensation for annual leave costs).

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

• Published on 11 September 2023
• The document describes the schema PayerSummaryReportsToIR, which is used to submit employer´s separate reports to the Incomes Register.

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

• Published on 3 June 2024

Document for 2023:

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

Document for 2025:

• Published a version of the document containing the 2025 changes to the data contents. The changes apply when the payment date of the income is on 1 January 2025 or later.
• Added a processing rule for the Identifier type (Type) data in the Occupational accident insurance (AccidentInsurances) data group:
  • Type of identifier must not be a “Personal Identification Number (Finnish)” or a “Foreign personal identification number”.

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

• Published on 11 September 2023
• The document describes the schema BenefitReportsToIR, which is used to submit benefits payment reports to the Incomes Register.

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

• Published on 3 June 2024

Document for 2024:

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

Document for 2025:

• Published a version of the document containing the 2025 changes to data content. The changes apply when the payment date of the income is on 1 January 2025 or later.
• Added a processing rule for the Original payment period (OrigEarningPeriod) data in the Additional repayment details (RecoveryData) data group:
  • The income type code for a recovery or unprompted refund must be valid partially or completely during the original payment period or date of payment.
• Changed the data Substitute recipient's address (Address) in the Substitute recipient’s data group to be mandatory data in the following cases:
  • No identifiers where "Identifier type" is "Business ID" or "Finnish Personal Identification Number" have been specified in the "Substitute recipient identifiers" data group.
  • The value of "The substitute recipient does not have a customer identifier" is "true".

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 2023 (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.

• 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 2024 (pdf)

• Published on 3 June 2024
• 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.

• Corrected Record owner's record reference (DeliveryId) data in the data group Details of the received record (DeliveryData) to be voluntary (V).

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 2024 (pdf)

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

• Corrected Record owner's record reference (DeliveryId) data in the data group Details of the received record (DeliveryData) to be voluntary (V).

• Previous versions of content descriptions of data delivery

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

• Published on 12 December 2023
• 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).

• Published a version of the document containing the 2024 changes to the data contents.
• Added to chapters 2.4 and 4.1 details of the distribution of records 312 and 313.
• The distribution channel value 7 has been added to record subscription data in chapter 6.12: Technical interface SFTP (service provider acting on behalf of the payer).
• Corrected chapter 1, Subscription channel: Web Service (Table 1).
  • Corrected the descriptions of the records to be ordered in table 1 (402-406).
  • Removed record type 405, corrected record type 950 from payer service to data user service.
• Corrected the language of the record types 312 & 313 in table 1.
• Added to chapter 2.2. the scheme of the material to be distributed according to material order 950 Rejected reports submitted on paper form – RejectedPaperReportsFromIR.
• Changed in chapter 2.4. Figure 3 according to the material to be distributed.

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

• Published on 11 September 2023
• The document describes the schema WageReportsFromIR, which is used to distribute earnings payment reports from the Incomes Register.

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

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

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

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

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

• Published on 11 September 2023
• The document describes the schema BenefitReportsFromIR, which is used to distribute benefits payment reports from the Incomes Register.

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

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 2024 (pdf)

• Published on 11 September 2023
• 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.

• Added a processing rule for the Payer identifiers (PayerIds) data in the Payer's identifier (Id) data group: A payer can have up to three identifiers.

• Previous versions of content descriptions of data distribution

Technical interface – Application guidelines 2024 (pdf)

• Published on 12 December 2023
• 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.

• Published a version of the document containing the data content changes for 2024.
• Details of the distribution of records 312 and 313 to the record creator’s SFTP folder have been added in paragraph 4.1.1.

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

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

• Published on 8 January 2024
• 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 2024 changes to the data contents.
• Changes in schema RejectedPaperReportsFromIRTypes:
  • Removed from the data group Record subscription details (Subscription) following data: Data access profile (QueryProfile)
  • Removed from the data group Reports data (Reports) following data: Date of payment or other report (PaymentDate)
  • Added a missing maxOccurs indicator in PaymentPeriod data group (maxOccurs="1")

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