Incomes Register FAQs for software developers

Upload service

How to use the Incomes Register's upload service?

The record upload service is part of the Incomes Register's e-service, which users log in to using online banking codes, a mobile certificate or a certificate card. The service is used to submit records to the Incomes Register. The files must be in XML format and in accordance with the Incomes Register's schema documentation. It is not possible to retrieve records via the upload service.

Where are the features of the upload service described?

The format of a record submitted to the record upload service is the same as that of a record submitted via the technical interface, and is described in the service descriptions of the technical interface. Read more: Technical interface – Submitting data to the Incomes Register 2020 (PDF)

The format for processing feedback received from the upload service is the same as that of feedback from the technical interface; and it, too, is described in the service descriptions of the technical interface.

Does the upload service give error messages already during the uploading of the record?

When uploading the record, the service gives the user error messages related to the schema.

How is processing feedback received for a record submitted via the upload service?

Processing feedback is available via the upload service after the Incomes Register has performed all checks in accordance with the record processing rules.

Reconciliation, transcripts and codes

Will reconciliation be based on a return message or will data providers have access to the Incomes Register so that they can check the uploaded records and base the reconciliation on that?

Should they wish, the payers can obtain reconciliation reports on the data they submit to the Incomes Register. If the data in the Incomes Register differs from the data in the payroll system, any incorrect data in the Incomes Register must be corrected using the replacement method.

Read more about transcripts: Payers can request transcripts concerning data submitted to the Incomes Register

How will the parties be notified of any changes made to the Incomes Register codes?

The Incomes Register's internal codes and their values, which appear in the messages of the Incomes Register's technical interface, are described in the documents 'Codes', 'Wages – Codes – Income types', and 'Benefits – Codes – Income types'. The parties will be notified of any changes in the codes or the documents.

Codesets maintained outside the Incomes Register include Keva's codes, earnings-related pension policy numbers and Statistics Finland's classification of occupations. The owner of the codeset will notify the Incomes Register and the various parties concerned of any changes to them in the same way as now. The Incomes Register authority will also notify the parties concerned of any changes.

Using certificates when invoking the interface

Which part of the record to be sent is signed in different channels?

Regardless of the service channel, the record to be delivered to the Incomes Register is always what is signed, not the frame. When the Web Service channel is used, the signature is generated from the element that is located inside the Envelope/Body element and conforms to the root element (RootElement) in accordance with the Incomes Register schema. The root element, signed according to the documentation, is then placed inside a SOAP Body element before it is sent to the Incomes Register. The signed record must not be changed during this stage.

The stages of signature in the Web Service channel summarised:

  1. Generate an Incomes Register's XML record and SOAP Envelope.
  2. Retrieve the root element inside the SOAP Envelope's Body and make it into a new XML document.
  3. Sign this new XML document in accordance with the documentation.
  4. Remove the root element that was inside the Body and replace it with the new, signed root element.
  5. Send the SOAP Envelope.

WS  interfaces

Why does SSLHandshakeException (Incomes Register and certificate service interface) appear when using Web Service?

The problem is probably related to the TLS/SSL version used by the customer software and related crypto libraries. The Incomes Register and certificate service's Web Service interfaces use a TLSv1.2 protocol and the client software must use the same version. Known problems:

Java 7 and older versions → Upgrade to Java 8 or a later version.

SoapUI OpenSource, version 5.3.0 and older use an outdated Java version. → Upgrade SoapUI to version 5.4.0 or update/replace Java packaged by SoapUI to version 8.

SFTP interfaces

Which file naming convention is used to name the Incomes Register's XML files in the OUT directory?

The OUT directory’s file names are based on the following convention:

<QueryDataType>_<MainSubscriptionId>_<SubscriptionId>_<sequential number of the query>_<IRQueryId>_<total number of part files>_<sequential number of the part file>.xml

File naming is described in the following  document: Technical interface – Application guidelines (PDF).

Record subscriptions

Why are the time stamps of the record subscription and the response message not in the same format? In the subscription, we provide the query start and query end times, as presented below. As I understand it, the time of day is in Finland’s time zone when it is in format “+02:00”.

<ModifiedTimespanStart>2018-01-01T00:00:00+02:00</ModifiedTimespanStart>

<ValidFrom>2018-05-17</ValidFrom>

<OnetimeDeliverySchedule>

<Time>13:00:00+02:00</Time>

The response had the retrieved timespan. However, the timespan was in a different format – “+02:00” was missing from it.  

<QueryTimespanStart>2017-12-31T22:00:00Z</QueryTimespanStart>

<QueryTimespanEnd>2018-05-17T11:00:00Z</QueryTimespanEnd>

Why does the time zone in the response differ from the time zone in the subscription?

The query timespan is saved in the Incomes Register’s database based on the time in UTC, regardless of what the time zone is on the subscription.

The time of day stated on the subscription is based on standard time in Finland, which is two hours ahead of the time in UTC:

<ModifiedTimespanStart>2018-01-01T00:00:00+02:00</ModifiedTimespanStart>

In the Incomes Register’s database, time is in UTC as follows:

<QueryTimespanStart>2017-12-31T22:00:00Z</QueryTimespanStart>

Queries are always launched on the basis of the time in Finland.

If the processing feedback returns any given Error element – MessageErrors, DeliveryErrors or ItemErrors – does it always mean that the actual response file cannot be generated?

If the record has a message-level error (MessageErroros) or record-level error (DeliveryErrors), the record cannot be processed any further. If the record returns an item-level error (ItemErrors), processing it will be possible in terms of its viable items if the record's settings allow it.

Sending a record

Does the Incomes Register accept compressed records?

The Incomes Register does not accept compressed records.

If a record is so large that it must be sent in several parts, are these parts individual submissions or do they have to have an identifier which indicates that they are part of a larger entity?

Every record is an individual record. In other words, a record cannot consist of separate parts. You can include a version number on a report, which the information provider can use to target their corrections at a valid report. However, one record cannot contain the combinations 'new-replacement' or 'new-cancellation' targeted at the same report.

If a report contains an error, how does the Incomes Register process the report?

Invalid reports submitted via the technical interface are rejected and always returned to the payer. The processing feedback provides the payer with information on the errors detected in the report. The rules according to which the correctness of an earnings payment report is checked are described in the document 'Data delivery – Schemas – Earnings payment reports'.

If an invalid report is subjected to an investigation by the Incomes Register, will the data user receive any information on the submitted report (e.g. for the purpose of monitoring reporting obligations)?

If a report submitted to the Incomes Register contains an error that causes the report to be rejected, the report is not saved in the Incomes Register and the Incomes Register will not investigate it. The payer is notified of errors in the report in the processing feedback. The payer must submit a corrected report within five calendar days of the payment date.

Only reports successfully saved in the Incomes Register are distributed to data users. Data users have their own basic register data, allowing them to monitor how payers fulfil their reporting obligations. A payer is neglecting its reporting obligation if it does not submit a corrected report by the deadline.

Distribution of records

Version 1, which was selected in the first query, was submitted to the Incomes Register in query time range 1. Versions 2 and 3 are submitted in query time range 2. If the query criterion was IncludeAllVersions = ”False”, will the only version selected from query time range 2 be version 3?

Only version 3 is selected.

From the Incomes Register's perspective, are replacement and cancellation comparable? In other words, if the previous question's version 3 was a cancellation rather than a replacement, would the query work in the same way and only the cancellation (version 3) be selected?

Yes, that is exactly right.

What about in a situation in which version 1 and the cancellation (version 2) were submitted in the same query time range? In such a case, is only the cancellation (version 2) selected for the message based on the criterion IncludeAllVersions = ”False”?

Yes.

How does the timing element work with messages in SFTP traffic? If I give the current day as the ValidFrom data item and the time of day is a past time, will the query be launched immediately?

<Schedule>

<OnetimeDeliverySchedule>

<Time>11:00:00+02:00</Time>

</OnetimeDeliverySchedule>

</Schedule>

If I want to set the time for the early hours of the next day, do I need to give the next day as the ValidFrom date?

If the ValidFrom date of a one-off subscription is the current day and the time is a past time, the query will be launched immediately. In other words, if the intention is to have the query launched the next day, a future date must be set for the one-off subscription.

In a timed subscription, the query will be launched when the time set is reached next.

Reports and reporting

If the report has been uploaded as a file, can a different channel, for example the e-service, be used for correcting errors?

Yes. Data can be submitted and corrected using different channels. The channel used to submit the original report need not be used to correct the data.

Are there restrictions to the service hours of the Incomes Register's SFTP interface or Web Service interface? For example, can data be retrieved only on weekdays, or can data also be retrieved during holidays and weekends?

There are no restrictions related to service hours in the use of the services of the technical interface. The services can be used at any time. The Incomes Register's maintenance breaks during which the interfaces are not available will be announced in advance. Read more: Incomes Register’s maintenance breaks

What is a report?

A report refers to data on one payment transaction paid to a single income earner. If a single transaction includes several payments to an individual wage earner, only one report needs to be submitted. One report can contain several income types.

Can several reports be submitted for a single person if the employer has pay data in many different systems?

Yes. Several reports concerning the same person can be given for a single pay period, and the data can be generated from a number of different systems. When you select the report type 'New', the previous report is not overwritten, and both remain valid.

What reference data can be used to allocate corrections and cancellations to the original reports?

In the Incomes Register, reports can have two separate uniquely identifying references: the Incomes Register report reference and the payer's report reference. The Incomes Register automatically assigns an Incomes Register report reference to a report when it is saved in the Incomes Register. The payer must also provide a payer's report reference they can freely choose when submitting data via the technical interface or the upload service. Corrections and cancellations can be allocated to the original report both with the Incomes Register report reference and the payer's report reference.

What data cannot be corrected with a replacement report? When does the previous report have to be cancelled and a new report submitted?

The data must be corrected by cancelling the previous report and then submitting a new one in the following situations:

  • Correction of a payment date
  • Correction of a pay period
  • Correction of the payer's and income earner's customer identifications
  • Correction of Type of additional income earner data when changing the additional data Athlete or Organisation
  • Correction of Payer type when changing the data Temporary employer
  • Correction of the customer identifiers of the actual employer in the Substitute payer data group
  • Correction of the Acts as substitute payer data
  • Correction of the income earner's birth date
  • Correction of a pension policy number
  • Correction of the Occupational accident insurance company identifier or policy number
  • Corrections to Type of exception to insurance data:
    • Retroactive changes to No obligation to provide insurance data
    • Retroactive changes to Not subject to Finnish social security data.
    • Retroactive changes to Voluntary insurance in Finland (earnings-related pension insurance) data.

We do not recommend cancelling the data before the new report has been submitted. The recommendation is that the cancellation of the previous report and the submitting of the new report be made on the same day.

Can the cancellation of a record and a report be submitted on the same earnings payment report on which new and replacement reports are submitted?

The cancellation of a record or a report should not be submitted with the same earnings payment report with which the new and replacement reports are submitted. The cancellation of reports has been separated into its own record type. This record type can be used to cancel an individual report, the entire earnings payment record, an employer's separate report, or a record subscription. Because cancellation has been separated into a separate schema structure, having to resubmit the mandatory data of the earnings payment report can be avoided when cancelling, for example, an individual earnings payment report.

Does the Incomes Register perform the same data content checks on electronically submitted reports and reports submitted on paper? Does the Incomes Register check in both submitting channels, for example, that the payer and income earner are not the same person?

The Incomes Register performs the same data content checks on all reports, regardless of the reporting channel (technical interface, e-service, paper).

According to the processing rules, the report's payer and income earner cannot be the same person.