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.

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

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.

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

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.

• 22 May 2023:
  • A version of the document containing the 2024 changes to the data content has been published. The changes apply when the income payment date is 1 January 2024 or a later date.
  • Changed the description of value ‘Original earnings period’ (OrigEarningPeriod) to ‘Original payment period’ in the Additional repayment details (RecoveryData) data group.
• 12 December 2023:
  • 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.

• 22 May 2023:
  • 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 2024 or later.
  • Added the following new income types:
    • 366 Copyright royalties, earned income
    • 367 Stock grant paid in money
    • 368 Employee stock option paid in money
    • 369 Earnings from work paid by a JuEL employer to a worker-client of an invoicing service
• 21 August 2023:
  • Corrected the title for income type 224 “Monetary compensation from a working time bank” to “Monetary compensation regarding a working time bank.”
• 10 October 2023:
  • 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.

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

Codes 2024 (xls)

Codes 2024 (pdf)

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

• Added the following values (valid from 1.4.2024) to the codeset Applicable collective agreement (CBACode):
  • 220 Collective agreement for supervisors in hotel, restaurant and leisure industry
  • 221 Collective Agreement for Supervisors in Trade Logistics
  • 222 Collective agreement for retail supervisors
  • 223 Collective Agreement for Employment Industry
• The validity of the following values in the codeset Applicable collective agreement (CBACode) has ended on 31 March 2024 and they have been removed:
  • 36 Collective Agreement for the Personnel Services Sector
  • 88 Collective Agreement for Tourism, Restaurant and Recreational Services - Supervisors
  • 170 Collective Agreement for Warehouse and Transport Supervisors
  • 185 Collective Agreement for Supervisors in the Retail Trade

Codes - Error codes 2024 (xls)

• Published on 8 January 2024
• The codes contain the descriptions for the error codes of the technical interface.

• Description of error codes were updated for the following error codes: BEV0060, BEV0350, DDVS0115, DDVS0270, IEBV0080, MSE0010

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

• Published on 12 December 2023
• The document describes the transcripts generated from the Incomes Register for data providers, data users and income earners.

• New information, Returned withheld taxes (BenefitWithholdingReturn) and Returned tax at source (BenefitTaxAtSourceReturn), has been added to report 500 (Income earner’s extract from the Incomes Register).
• Changed the description of value ‘Original earnings period’ to ‘Original payment period’ in the transcript 620 Income type specific summary of payer’s benefits payment reports (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.

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.

• 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 2024 or later.
• 22 May 2023:
  • Added a new processing rule to the Occupation (Professions) data group. According to the processing rule (new item d), the “Occupational class or title” data group does not need to be entered if the report only includes income types in which “Recovery” is “true”.
  • Added a new processing rule to the “Earnings-related pension insurance (PensionInsurance)” data group. According to the processing rule (new item d), the “Earnings-related pension insurance” data group does not need to be entered if the report only includes income types in which “Recovery” is “true”.
  • In data group General details on the income type (TransactionBasic):
    • Added following new income types in the processing rule for Income type code (TransactionCode) data:
      • 366 Copyright royalties, earned income
      • 367 Stock grant paid in money
      • 368 Employee stock option paid in money
    • Added following new income types in the processing rule for Amount (Amount) data:
      • 366 Copyright royalties, earned income
      • 367 Stock grant paid in money
      • 368 Employee stock option paid in money
  • Added a processing rule for the General details on the income type (TransactionBasic) data in the Income type code (TransactionCode) data group: If the “Income type code” is 369, the earnings-related pension provider code (PensionProvIdCode) must be 20, 24,25, 27, 29 or 30.
  • Added a processing rule for the Other details (IncomeEarnerOther) data in the Type of additional income earner data (IncomeEarnerType) data group: If "Type of occupational title or classification" is ‘Statistics Finland's classification of occupations (TK10)’ and “Occupational class or title identifier” is ‘34210' (Athletes), the Type of additional income earner must be set as ‘Athlete’.
  • Corrected the data group ‘Stay periods in Finland’ (StayPeriodInFinland) to ‘Stay periods in Finland’ (StayPeriodsInFinland).
  • Corrected ‘Stay period in Finland’ (StayPeriodInFinland) data to ‘Stay period in Finland’ (Period).
• 15 August 2023:
  • Removed from the processing rule
    • for Income type code (TransactionCode) data in the data group General details on the income type (TransactionBasic): 366 Copyright royalties, earned income
    • for Amount (Amount) data in the data group General details on the income type (TransactionBasic): 366 Copyright royalties, earned income
• 11 September 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.

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.

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

• Published a version of the document containing the 2024 changes to data content. The changes apply when the payment date of the income is on 1 January 2024 or later.
• 22 May 2023:
  • Changed the description of value ‘Original earnings period’ (OrigEarningPeriod) to ‘Original payment period’ in the Additional repayment details (RecoveryData) data group.
• 11 September 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.

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

• 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 2024 or later.
• 22 May 2023:
  • Removed Payer's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Other payer details (PayerOther).
  • Removed Income earner's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Other details (IncomeEarnerOther).
  • Removed Representative's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Representative (Representative).
  • Removed Principal's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Principal (ServiceRecipient).
  • Added a new processing rule “Address information under an access restriction to personal data will not be shared” for the following data groups:
    • Payer's address (Address)
    • Income earner's addresses (Addresses)
    • Representative's address (Address)
    • Principal's address (ServiceRecipientAddress)
• 11 September 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.

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.

• 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 2024 or later.
• 22 May 2023:
  • Removed Payer's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Other payer details (PayerOther).
  • Added a new processing rule “Address information under an access restriction to personal data will not be shared” for the data group Payer's address (Address).
• 11 September 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.

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.

• Published a version of the document containing the 2024 changes to data content. The changes apply when the payment date of the income is on 1 January 2024 or later.
• 22 May 2023:
  • Changed the description of value ‘Original earnings period’ (OrigEarningPeriod) to ‘Original payment period’ in the Additional repayment details (RecoveryData) data group.
  • Removed Policyholder's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Insurance details (Insurance).
  • Removed Income earner's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Income earner details (IncomeEarner).
  • Removed Substitute recipient's details may include access-restricted data (SensitiveInfoIncluded) data from the data group Substitute recipient details (IncomeBeneficiary).
  • Added a new processing rule “Address information under an access restriction to personal data will not be shared” for the following data groups:
    • Income earner's address (Address)
    • Policyholder's address (Address)
    • Substitute recipient's address (Address)
• 11 September 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.

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.

• Published a version of the document containing the 2024 changes to data content.
• 22 May 2023:
  • 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).
• 11 September 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.

• 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