Documentation

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

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

• Edited document's layout.
• Changed 'employer' to 'employee' in the description of income type 332.

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

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

• Added Introduction and Reading instructions.
• Removed descriptions of processing rules from chapters Occupational accident insurance (AccidentInsurance) and Additional income earner details (IncomeEarnerTypes).

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

• Changed document's layout.

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

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

• Added Introduction and Reading instructions.

• Previous versions of data content application guidelines for benefits

Wages - Codes - Income types 2022 (xls)

Wages – Codes – Income types 2022 (pdf)

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

• The excel file:
  • 'Title 'Label' changed to title 'Income type name'.
  • Font size changed to 12 pixels.
  • Added reading instructions.
• The pdf file:
  • Added Introduction.
  • Titel 'Code' changed to title 'Income type code'.
  • Titel 'Labe'l changed to title 'Income type name'.

Benefits – Codes – Income types 2023 (xls)

Benefits – Codes – Income types 2023 (pdf)

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

• The excel file:
  • Title 'Label' changed to title 'Income type name'.
  • Font size changed to 12 pixels.
  • Added reading instructions.
• The pdf file:
  • Title 'Code' changed to title 'Income type code'.
  • Title 'Label' changed to title 'Income type name'.

Codes 2023 (xls)

Codes 2023 (pdf)

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

• The codeset Applicable collective agreement (CBACode): seven values have been removed and three values added.
• The excel file:
  • Font size has been changed to 12 pixel.
  • Instructions have been added.
• The pdf file: 
  • Added Introduction.

Codes - Error codes 2023 (xls)

• Published on 27 December 2022
• The codes contain the descriptions for the error codes of the technical interface.

• Title 'Label' changed to title 'Error code definition'.
• Font size changed to 12 pixels.
• Added reading instructions.

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

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

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

• Previous versions of codes

Transcripts from the Incomes Register 2022 (pdf)

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

• Upload channel deleted from the channels on report Access log data for the data user 710.

Income data – Calculation rules 2023 (pdf)

• Published on 27 December 2022
• The document describes how the information for the Incomes Register transcripts is calculated.

• Added Section 1 ‘Introduction’.

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

• Published on 9 November 2022
• The document describes the schema WageReportsToIR, which is used to submit earnings payment reports to 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.
• Added a new processing rule for the Number of days of absence (AbsenceDays) in the Paid Absence (PaidAbsence) data group: The value must be a non-negative number. The correction has no impact on the implementation.

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

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

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

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

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

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

• Published on 6 June 2022
• The document describes the schema BenefitReportsToIR, which is used to submit benefits payment reports to 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.
• 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 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 2022 (pdf)

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

• Specified the permitted subscribers in Section 6.12 ‘Summary of payer’s earnings payment data’.
• Added a table to Section 1 regarding records distributed from the Incomes Register, their subscribers, and subscription and distribution channels.
• Removed a reference to schema changes from Section 2.2 as outdated data.

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

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

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

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

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

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

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

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

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

Data distribution – Schemas – Service Request 2021 (pdf)

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

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

Data distribution – Schemas – Log Data 2021 (pdf)

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

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

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

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

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

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

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

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

• Previous versions of content descriptions of data distribution

Technical interface – Application guidelines 2021 (pdf)

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

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

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

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

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

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

Technical interface – Message signing, sample implementation (zip)

Technical interface – Message signing, sample implementation (pdf)

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

• Previous versions of application developer's guidelines