Documentation

• Published on 25 November 2024
• 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.

• Published a version of the document containing the 2025 changes to data contents and other updates of the Incomes Register Unit. The changes apply when the payment date of the income is on 1 January 2025 or later.
• The descriptions of the following income types were clarified:
  • 201 Time-rate pay
  • 216 Other compensation
  • 224 Monetary compensation from a working time bank
  • 317 Other fringe benefit
  • 328 Private caretaker's fee
  • 336 Non-wage compensation for work
  • 353 Taxable reimbursement of expenses

• Published on 8 January 2025
• The document describes data content in earnings payment report and covers what to report under each individual section.

• 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.
• 5 November 2024:
  • The following value removed from the Type of additional income earner data (IncomeEarnerType) data: Employed with assistance from the State employment fund
• 8 January 2025:
  • Added the missing tax treaty countries, Albania and Spain, to the description of the Additional income earner details (IncomeEarnerTypes) type "Leased employee living abroad" The listing has been reordered alphabetically.

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

• Published on 5 November 2024
• 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.

• 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 2025 (xls)

Wages – Codes – Income types 2025 (pdf)

• Published on 8 January 2025
• 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.

• Published a version of the document containing the 2024 changes to the data contents. The changes apply when the payment date of the income is on 1 January 2025 or later.
  The name of the income type code 363 has been corrected from “Tax-exempt share of bicycle benefit” to “Bicycle benefit, tax-exempt share”.

Benefits – Codes – Income types 2025 (xls)

Benefits – Codes – Income types 2025 (pdf)

• Published on 5 November 2024
• 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

• 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 2025 (xls)

Codes 2025 (pdf)

• Published on 8 January 2025
• The document contains the codes used in the technical interface of the Incomes Register.

• 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
• 8 January 2025:
  • Added the following values to codeset Query criterion type for record subscription (ParameterType):
    
    • 28 Displaying user IDs
    • 29 Action target (customer)
  • Added new codeset Displaying user IDs (ShowUserIDs).
  • Added file types to the code definitions of the codeset Record type, distributed from Incomes Register (QueryDataType). Removed the word "file" from the code definition for record types 630, 632 and 710.
  • Added to the codeset 'Record type, distributed from Incomes Register’ (QueryDataType) the record types 601 and 631 for recurrent subscription.

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

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

• Published on 8 January 2025
• 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 2025 changes to data content.
• Filetypes have been added to the record type descriptions in chapter 1.1 Transcript subscription and distribution channels, chapter 4 Payer's transcripts, and chapter 5 Data user's transcripts. The word "file" has been deleted from the names of the reports 630 Summary of payer's earnings payment data (csv) and 632 Summary of payer's benefits payment reports (csv).
• New query criteria ‘Displaying user IDs’ and ‘Action target (customer)’ have been added for reports 702 and 710.
• New transcript data has been added for transcript 702:
  
  • User’s name
  • Data user’s role
• New transcript data has been added for transcript 710:
  
  • User’s name
  • Data user’s role
  • Action target (customer identifier type)
  • Action target (customer identifier)
  • Identifier Country code and the name of the country.
• Added to transcripts 702 and 710: Transcript data can be subscribed from January 1, 2019.
• Added new reports 601 Summary of payer’s earnings payment data (recurrent subscription, pdf) and 631 Summary of payer’s earnings payment data (recurrent subscription, csv)

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.

• Published on 3 June 2024
• The document describes the schema WageReportsToIR, which is used to submit earnings payment reports to the Incomes Register.

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

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

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

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

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

• Published on 8 January 2025
• 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 2025 changes to the data content has been published. The changes apply when the income payment date is 1 January 2025 or a later date.
• Updated the description of the section “Cancellation or ending of a record subscription” in the data group Items to be Cancelled (Items).

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

• Published on 8 January 2025
• 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 2025 changes to the data contents.
• File formats have been added to the description of the following records:
  
  • Earnings payment reports – all income earners (xml)
  • Earnings payment reports – several income earners (xml)
  • Earnings payment reports – several payers (xml)
  • Earnings payment reports – several payers, several income earners (xml)
  • Earnings payment reports – several pension insurance companies (xml)
  • Earnings payment reports – missing pension policy number (xml)
  • Employer's separate reports – all payers (xml)
  • Employer's separate reports – several payers (xml)
  • Employer's separate reports – several earnings-related pension providers (xml)
  • Access log data for the party's users (xml)
  • Summary of payer's earnings payment data (one-off subscription, xml)
  • Summary of payer's earnings payment data (recurrent subscription, xml)
  • Earnings payment reports – several report references (xml)
  • Benefits payment reports – all income earners (xml)
  • Benefits payment reports – several income earners (xml)
  • Benefits payment reports – several payers, several income earners (xml)
  • Benefits payment reports – several report references (xml)
  • Benefits payment reports – several payers (xml)
  • Rejected reports submitted on paper form (xml)
  • Earnings payment reports – one income earner (xml)
  • Earnings payment reports – one payer (xml)
  • Earnings payment reports – one pension policy number (xml)
  • Employer's separate reports – one payer (xml)
  • Employer's separate reports – one pension policy number (xml)
  • Earnings payment reports – one payer, one income earner (xml)
  • Benefits payment reports – one income earner (xml)
  • Benefits payment reports – one payer, one income earner (xml)
  • Benefits payment reports – one report reference (xml)
• Added to chapter 6.11 310 Access log data for the party's users: The record data can be subscribed from January 1, 2019.

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

• Published on 8 January 2025
• The document describes the schema LogDataFromIR, which is used to distribute log data from the Incomes Register.

• Document for 2025 published.
• Added new data to Log events (LogEvents) data group:
  • User’s name
  • Data user’s role

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 2025 (zip)

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

• Published on 8 January 2025
• 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 2025 changes to the data contents.
• Description of changed data content added.

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