Käyttöönoton ja ylläpidon ohjeistus tiedonhakujärjestelmä
Tiedonhakujärjestelmän kyselyrajapintakuvaus
Deployment and maintenance instructions for the Data Retrieval System
Instruktioner för produktionssättning och underhåll av datasöksystemet
Beskrivning av datasöksystemets frågegränssnitt

Query interface description of the data retrieval system

Document version 2.0.12

Vesion history

Version	Date	Decription
1.0	21.10.2019	Version 1.0
1.0.1	1.11.2019	The section Investigation Period (InvstgtnPrd, paragraph 4.5) has been updated.
1.0.2	1.11.2019	WSDL added.
1.0.3	27.11.2019	The element Ccy was changed to mandatory.
1.0.4	27.11.2019	The guidance on and the scheme for reporting disputed data were added.
1.0.5	18.12.2019	The Contract element of submessage fin.013 was described. Tables were added in chapter 4.3 to describe the data content of the bank and payment account register with message-specific details. The format of PartyIdentification41 name field was determined. The conditions of the name search were specified. The incorrect indication “mandatory” was removed from the AdditionalSearchCriteria if submessage fin.012. The reference to the table OTHER in connection with the query parameters was removed. The description of investigation period was specified. The abstraction level of the owner code was raised. The incorrect reference to the Cd element was removed from Role OwnrTp. Details of a natural person to be returned were specified. The use of SdBoxAndParties was described.
1.0.6	21.1.2020	The use of ReturnIndicator when no search results were found for the submessage was clarified.
1.0.7	7.2.2020	The first name and last name were replaced with the complete name.
1.0.8	7.2.2020	The mandatory status of the start date of the rental period of the safety-deposit box was removed.
1.0.9	19.2.2020	The content of the field fin013 Beneficiaries was changed into PersonIdentification5, because only natural persons are allowed.
1.0.10	5.3.2020	It was confirmed that the safety-deposit box is used as a search criteria. The conditions for the message level signature were updated. SchmeNm was corrected to SchmeNm.
1.0.11	5.3.2020	The description of the legal basis was added.
1.0.12	10.3.2020	The description of the response message was updated concerning the roles related to the account.
1.0.13	12.3.2020	The use of the records of the searches by IBAN and by other code identifying the account was supplemented.
1.0.14	17.3.2020	The example of XML signature was updated.
1.0.15	17.3.2020	PartyIdentification41 was returned as the content of the field fin013 Beneficiaries. The field Contract was changed into an optional field.
1.0.16	26.3.2020	The scheme fin.013 and its use were updated.
1.0.17	26.3.2020	The description of the search by safety-deposit box ID was added. Updated InformationRequestFIN012 to version fin.012.001.02.
1.0.18	26.3.2020	The use and encoding of the registration number of a legal person.
1.0.19	31.3.2020	The terms were specified. The description of the presentation of long account identifiers was added. An unnecessary paragraph was removed. Specifications concerning the certificate parties. The requirements concerning signatures were specified.
1.0.20	17.4.2020	Start and end dates were added for the role in the field InformationResponseFIN013 Beneficiary. InformationResponseFIN013 was updated to version fin.013.001.03.
1.0.21	20.4.2020	The ability to search by the identification number of an ID was removed.
1.0.22	24.4.2020	The description of the field SearchCriteria1Choice in section 4.5 was updated.
1.0.23	29.4.2020	The figure 2.1 Query for bank and payment account details was clarified. Numbering was added for the error codes.
1.0.24	5.5.2020	Clarifications to chapter 4.3: a mention of the beneficiary details of a natural person, a mention of the persons involved in an account, a mention of the persons involved in a safety-deposit box.
1.0.25	6.5.2020	The limitations for the presentation of first names and surnames in connection with the ISO 20022 auth.001 message were clarified.
1.0.26	7.5.2020	The linking was fixed in sections 4.2 and 4.3.
1.0.27	11.5.2020	The mandatory status of the start date of the beneficiary role was removed; the schema fin.013 was updated to version fin.013.001.04.
1.0.28	14.5.2020	A clarification was added concerning the size limits for response messages.
1.0.29	28.5.2020	The error code Unauthorized was added to table 4.12.1.
1.0.30	2.6.2020	Spelling mistakes and formatting were fixed. Unnecessary passages were removed.
1.0.31	8.6.2020	fin.002.001.02.xsd and fin.012.001.02.xsd were updated.
1.0.32	11.6.2020	The InfRspnFin012 element of the schema fin.012 was renamed to InfReqFin012. The schema fin.012 was updated to version fin.012.001.03.
1.0.33	12.6.2020	The description of XML signature was updated. WSDL was updated.
1.0.34	3.7.2020	It was specified that the search criteria “company name” and “the natural person’s name” are not case sensitive.
1.0.35	23.7.2020	The links to the iso20022.org website were updated.
1.0.36	13.8.2020	In the table “Search by company name”, the tag for “company name” was amended (Id -> Nm).
1.0.37	24.8.2020	A specifying note regarding the lengths of keys used in data communications and message signatures was added.
1.0.38	24.8.2020	The paragraph “Limiting submessages in the search result” was added. The words “at most” were deleted from the sentence “one search result sub-message … is returned per Business ID for each search result type”.
1.0.39	25.8.2020	Both the Business ID and the VAT number are accepted as the serialNumber attribute in the data traffic certificate and the signature certificate.
1.0.40	17.9.2020	Corrected references to fin.002.001.01 message to correspond with version fin.002.001.02
1.0.41	18.9.2020	Query response size is too large -error was added to table 4.12.1.
1.0.42	25.9.2020	Replaced links to iso20022.org’s files with references to local files since iso20022.org often changes the file locations.
1.0.43	20.11.2020	Query response has multiple hits -error was added to table 4.12.1.
1.0.44	27.1.2021	Clarified the use of DtAndPlcOfBirth and DateOrDateTimePeriodChoice elements.
2.0.0	22.8.2022	Updated specifications to match the updated legal requirements.
2.0.1	16.9.2022	Updated WSDL and example files.
2.0.2	6.10.2022	Updated safety deposit box and beneficiary role date limitations. Updated example and fin.002.001.03 schema files. Clarified handling of duplicates in query for a person and query for an organisation in chapter 4.5.
2.0.3	24.11.2022	Updated instructions files.
2.0.4	13.12.2022	Updated limitations related to lawyer’s customer asset accounts. Lawyer’s customer asset accounts are not returned in InformationResponseSD1V01 supl.027.001.01 submessages, if the query type is natural person query or organisation query.
2.0.5	7.2.2023	Clarifications to chapter 4.12: Validation error can be used in case of incorrect investigation period. Maximum size for response message is 5 Mb. In chapter 3.1 replaced Population Register Centre with Digital and Population Data Services Agency.
2.0.6	15.2.2023	Updated ‘In use’ and ‘Description’ in tables 4.5 InformationRequestOpeningV01 (InvstgtnId, LglMndtBsis) and 4.6 AuthorityInquirySet (OfficialId, OfficialSuperiorId). Updated example files.
2.0.7	24.4.2023	Updated ‘Use of PersonIdentification5 and PersonIdentification5b elements’ description regarding different sub messages in chapter 4.11. Added SHA512 to allowed algorithms in chapter 3.1. Added a clarification of the ID format in Fr-element in chapter 4.4. Unified use of terminology regarding legal person and access right, legal person refers to organisations. Added instructions about returning NFOU for each submessage. Clarifications for using fields in LegalPersonInfo element. Clarifications in chapter 5.1 to rules for credit institutions on returning beneficiary and customership information: Beneficiary information can only be returned if the person/organisation who is the object of the query owns or has access right to an account or safety deposit box. Customership information can only be returned, if organisation who is the object of the query is the owner of an account or a safety deposit box in the credit institution.
2.0.8	4.7.2023	New example response messages added.
2.0.9	15.8.2023	New SoapFault examples added to chapter 4.12.
2.0.10	1.11.2023	In chapter 3 clarified instructions about the data traffic certificate to data suppliers and parties making the contact.
2.0.11	20.6.2024	In chapter 4.5, added the format for the natural person’s name used in the query message.
2.0.12	28.8.2024	Instructions for returning public guardian’s sequence number have been added to chapter 4.11.

Table of contents

1. Introduction
2. Query for bank and payment account details from the data retrieval system
3. Information security
4. Query interface of the data retrieval system
   4.1 Message structure of the SOAP operations of the query interface
   4.2 Business Application Header (BAH)
   4.3 Messages of the query interface
   4.4 BusinessApplicationHeaderV01
   4.5 InformationRequestOpeningV01
   4.6 InformationRequestFIN012
   4.7 InformationRequestResponseV01
   4.8 InformationResponseSD1V01
   4.9 InformationResponseFIN002
   4.10 InformationResponseFIN013
   4.11 Use of Id element
   4.12 WS message traffic scenarios at the query interface
   4.13 Returning disputed details
5. Limitations of data returned by query based on servicer category
   5.1 Customer category 1
   5.1.1 Natural person query
   5.1.2 Organisation query
   5.1.3 Account query
   5.1.4 Safety deposit box query
   5.2 Customer category 2
   5.2.1 Natural person query
   5.2.2 Organisation query
   5.2.3 Account query

1. Introduction

1.1 Terms and abbreviations

Abbreviation or term	Definition
Interface	A standard practice or connection point that allows the transfer of information between devices, programmes and the user.
WS (Web Service)	Software operating in a network server, providing services for use by applications through standardised internet connection practices. The data retrieval system provides information queries as a service.
Endpoint	An interface service available at a certain network address.
WSDL	(Web Service Description Language) A structural description language describing the functionalities provided by the web service.

1.2 Purpose and scope of the document

This document is part of the order issued by Finnish Customs regarding a bank and payment account monitoring system. The purpose of the document is to issue instructions regarding the query interface of the data retrieval system. This document is supplemented by the deployment and maintenance instructions for the data retrieval system.

1.3 References

WSDL for the data retrieval system

ISO 20022 External Code Sets

ISO 20022 auth.001.001.01 InformationRequestOpeningV01 MDR

ISO 20022 auth.002.001.01 InformationRequestResponseV01 MDR

ISO 20022 head.001.001.01 schema

fin.002.001.03

fin.012.001.03

fin.013.001.04

Guidelines on the Information Security of e-Services

1.4 General description

Customs has established an Account Register Project implementing the bank and payment account monitoring system, based on Finnish legislation and implementing EU Directive 2018/843.

This document describes the query interfaces of the data retrieval system.

2. Query for bank and payment account details from the data retrieval system

This chapter describes the query of bank and payment account details from the data retrieval system.

There are limitations for the size of a single message in the systems of the authorities.

In connection with the implementation, the parties can agree together on a size limit for messages and on ways in which the size of a single message can be made smaller if need be or on an alternative method for delivering occasional messages that exceed the size limit.

Figure 2.1 shows the query for bank and payment account details from the data retrieval system as a flow diagram.

Figure2.1. Query for bank and payment account details

The figure shows that the query interface allows both the response to be sent instantly in a synchronous manner, or alternatively in an asynchronous manner.

Table 2.1. Shows the meaning of different variables in the flow diagram.

Table 2.1. Variables in the flow diagram

Variable	Description
POLLING_INTERVAL	Polling interface, the time the client has to wait before the next query. If the client polls the server too frequently, the server might reject the processing of the transaction (error code 3, see 4.12).
RETRY_LIMIT	The number of polls permitted before stopping. If there is still no response, either a new query must be made or the matter must be transferred for manual processing.

The values of variables shown in Table 2.1. Valid at the time are shown in the annex documents.

The flow of the query is as follows:

1. The client sends a query message
2. Depending on the capability and the context, the server can return the retrieval results either synchronously or asynchronously. The server either a. returns a response message including the retrieval result and the code COMP for example within five (5) seconds, or b. returns a response message including the code NRES
3. The client checks whether the response message has the code COMP or NRES
4. If the code is COMP, the process moves to step 10.
5. The code is NRES. The client waits for the time defined by variable POLLING_INTERVAL and then makes query request #2
6. The server either a. returns the retrieval result and the code COMP or b. returns a response message including the code NRES
7. The client checks whether the response message has the code COMP or NRES
8. If the code is COMP, the process moves to step 10.
9. The code is NRES. If the RETRY_LIMIT has not been reached, the process moves to step 5.
10. End.

The table describes the use of StatusResponse1Code values.

Table 2.2. Use of StatusResponse1Code values

Code	Name	Definition	Description
COMP	CompleteResponse	Response is complete.	The response message includes the retrieval results.
NRES	NoResponseYet	Response not provided yet.	The response message does not include retrieval results; make a new query later.
PART	PartialResponse	Response is partially provided.	Not used.

3. Information security

3.1 Identification

Table 3.1. Shows the certificates used in the data retrieval system.

Table 3.1. Certificates of the data retrieval system

Standard	Name of the certificate	Purpose
X.509 (version 3)	Data traffic certificate of the data retrieval system	Interface Data traffic certificate of the data utiliser or the party authorised by the data utiliser
X.509 (version 3)	Signature certificate of the data retrieval system	Signing the messages, verification of the authenticity of messages, identification of the data supplier

The utilisers of the data retrieval system interface and the data suppliers or the parties authorised by the data supplier are identified with X.509 certificates (Data traffic certificate). The query and response messages of the query interface are signed using XML signatures (Signature certificate).

Signature certificate of the data supplier

Data suppliers must sign the messages they send using the server certificate x.509 that indicates the Business ID or VAT identifier of the data supplier. The signatures in incoming messages must be checked. The recipient cannot accept a message without an acceptable signature. Accepting the signature requires that the XML signature is valid and that

either

a) the certificate was issued by the Digital and Population Data Services Agency, the certificate is valid and is not included in the certificate revocation list of the Digital and Population Data Services Agency, and the serialNumber attribute of the Subject field of the certificate consists of the Business ID or VAT identifier of the party submitting the information

or

b) the certificate is an eIDAS-approved website identification certificate, the certificate is valid and is not included in the certificate revocation list of party providing the certificate, and the organizationIdentifier attribute of the Subject field of the certificate consists of the Business ID or VAT identifier of the party submitting the information.

Please note: For the message signatures to meet the information security requirements of the National Cyber Security Centre referred to below, the RSA public key of the certificate used for signatures must have at least 3072 bits. The uses of the certificate used for signatures must also include “digital signature”. These factors must be taken into account when ordering a certificate.

Signature certificate of the competent authority

The competent authority must sign the messages it sends using the server certificate x.509 that indicates the Business ID of the authority. The signatures in incoming messages must be checked. The recipient cannot accept a message without an acceptable signature. Accepting the competent authority’s signature requires that the XML signature is valid and that

a) the signature certificate used for the signature was issued by the Digital and Population Data Services Agency, the certificate is valid and is not included in the certificate revocation list maintained by the Digital and Population Data Services Agency

b) the serialNumber attribute of the Subject field of the certificate consists of the Business ID of the competent authority that sent the message or of the identifier that is formed of the letters “FI” and the digit part of the authority’s Business ID without the hyphen (ID in the format of a VAT-number).

Data traffic certificate of the party making the contact

The data supplier or the party authorised by the data supplier identifies the competent authority contacting the query interface of the data retrieval system with the help of the server certificate. A contact made by the competent authority must be accepted provided that

a) the certificate of the competent authority was issued by the Digital and Population Data Services Agency

b) the certificate is valid and is not included in the certificate revocation list of the Digital and Population Data Services Agency

c) the serialNumber attribute of the Subject field of the certificate consists of the Business ID of the competent authority or the state service centre acting on its behalf, or of the identifier that is formed of the letters “FI” and the digit part of the authority’s or the centre’s Business ID without the hyphen (ID in the format of a VAT-number).

Please note: For the protection of data communications to meet the information security requirements of the National Cyber Security Centre referred to below, the RSA public key of the certificate used must have at least 3072 bits. In addition, the server certificate must be of type QWAC (Qualified Website Authentication Certificate), which includes extensions (X509v3 Extended Key Usage: TLS Web Client Authentication, TLS Web Server Authentication). These factors must be taken into account when ordering a certificate.

Data traffic certificate of the data supplier or the party authorised by the data supplier

The competent authority contacting the query interface identifies the data supplier or the party authorised by the data supplier with the help of the server certificate. The party authorised by the data supplier refers, for example, to a service centre which the data supplier has authorised to compile and/or send the reports on its behalf. A contact with the data supplier must be accepted provided that

either

a) the server certificate was issued by the Digital and Population Data Services Agency, the certificate is valid and is not included in the certificate revocation list of the Digital and Population Data Services Agency, and the serialNumber attribute of the subject of the certificate consists of the Business ID or VAT identifier of the party submitting the information or the party authorised by that party

or

b) the server certificate is an eIDAS-approved website identification certificate, the certificate is valid and is not included in the certificate revocation list of party providing the certificate, and the organizationIdentifier attribute of the subject of the certificate consists of the Business ID or VAT identifier of the party submitting the information or the party authorised by that party.

If the same Business ID or VAT identifier is used in the data traffic certificate and outgoing message signature certificate of the party submitting the information, the same certificate can be used for both purposes.

Please note: For the protection of data communications to meet the information security requirements of the National Cyber Security Centre referred to below, the RSA public key of the certificate used must have at least 3072 bits. In addition, the server certificate must be of type QWAC (Qualified Website Authentication Certificate), which includes extensions (X509v3 Extended Key Usage: TLS Web Client Authentication, TLS Web Server Authentication). These factors must be taken into account when ordering a certificate.

Forming XML signatures

The signature is of the enveloped signature type. The signature element is placed in BAH under the Sgntr element. Example 3.1. Example SignedInfo

<SignedInfo>
  <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
  <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
  <Reference URI="#applicationRequest">
    <Transforms>
      <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
      <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
    </Transforms>
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
    <DigestValue />
  </Reference>
</SignedInfo>

The signature algorithm therefore is RSA-SHA256 or RSA-SHA512 and C14N is Exclusive XML Canonicalization. The reference URI is “#applicationRequest” or “#applicationResponse“, depending on if it’s a query or response message. Only “ApplicationRequest” or “ApplicationResponse” element is signed. When forming the signature, either the SHA256 or SHA512 algorithm must be used for establishing the digests to be calculated.

In terms of cryptographic strength, the cryptographic algorithms used in signatures must correspond at least with the cryptographic strength requirements set out by the Finnish Transport and Communications Agency as concerns national protection level ST IV. Current strength requirements are described in the Finnish-language document available at this link: Cryptographic requirements for confidentiality - national protection levels (in Finnish) (Record No.: 190/651/2015).

The possibility of limiting the IP space of requests in the data retrieval system will be further specified at a later stage.

3.2 Protecting the connections

The connections of the query interface of the data retrieval system must be protected with TLS encryption using version 1.2 or later of the TLS protocol. Both ends of the connection are identified with the server certificates described above, using two-way handshaking. The connection must be established using the ephemeral Diffie-Hellman (DHE) key exchange protocol where a new unique private encryption key is created for each session. The purpose of this procedure is to ensure that encryption has the forward secrecy feature so that possible discovery of the encryption key afterwards would not lead to a disclosure of the encrypted information. The cryptographic algorithms used in TLS encryption must have a cryptographic strength at least equal to the cryptographic strengths the Finnish Transport and Communications Agency has specified for national protection level ST IV. The current strength requirements are described in document Cryptographic requirements for confidentiality - national protection levels (in Finnish) (Record no: 190/651/2015).

3.3 Permitted HTTP-version

The connections of the query interface of the data retrieval system use HTTP version 1.1.

3.4 Duty to report information security deviations

If the certificates or private key of the party implementing the data retrieval system are compromised, the party issuing the certificate and the competent authorities utilising the data retrieval system must be immediately informed of this. The competent authorities must also be informed if an information security deviation is observed in the data retrieval system.

If the certificates or private key of the competent authority utilising the data retrieval system are compromised, the party issuing the certificate and the parties implementing the data retrieval system whose implementation of the data retrieval system is utilised by the competent authority concerned must be immediately informed of this.

4. Query interface of the data retrieval system

The query interface will be implemented as a SOAP/XML Web Service, of which a WSDL will be published.

SOAP protocol version 1.1 is used.

ISO 20022 code set references are used in the messages. The code set references are found at the ISO 20022 page External Code Sets.

The query interface has one endpoint with its query and response message structure described in this chapter.

4.1 Message structure of the SOAP operations of the query interface

The SOAP body always consists of two parts, the ISO 20022 Business Application Header (BAH) and the actual business message.

4.2 Business Application Header (BAH)

The details of the Business Application Header message are shown in the table below.

Message id	Name of the message
head.001.001.01	Business Application Header

The BAH must always be the first element of the SOAP body.

4.3 Messages of the query interface

The query interface of the data retrieval system uses the ISO 20022 messages InformationRequestOpeningV01 (auth.001.001.01) and InformationRequestResponseV01 (auth.002.001.01) to which the required submessages (Supplementary Data) are appended.

The submessages used at the upper level are divided into three concepts: customership, account and safety deposit box. The customership and beneficiary details are returned in the message fin.013.001.04, the account details in the message supl.027.001.01 and the safety deposit box details in the message fin.002.001.03 (NB. here the same code as in the manual processing in some existing systems). These submessages are appended to auth.002.001.01 element InformationRequestResponseV01/RtrInd.

The tables 4.3.1–4.3.5 show the data content of the bank and payment account register as well as the Supplementary Data submessage, as part of which each detail is returned.

The tables 4.3.6–4.3.8 show the auth messages in accordance with the ISO 20022 catalogue, as well as the submessages appended to them.

The more detailed message descriptions are presented in the subchapters of this chapter, from 4.4 onwards.

Table 4.3.1: Natural person, details specified for each message

Detail	Message(s)	Description
Complete name	fin.002, fin.013, supl.027	Returned in the Pty/Nm element attached to the role, in source system format. In order to achieve compatibility with existent systems, one name field must be used to express all of the names of a person. The format of this element with regard to first and surnames has not been established in detail in the ISO 20022 message implementations that have been issued as a basis for the specification work (auth.001:Document/InfReqOpng/SchCrit/CstmrId/Pty/Nm). Furthermore, it should be noted that not everyone globally has first names and/or surnames.
Date of birth	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Personal identity code	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Nationalities	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Beneficiary	fin.013	Organisations in which the natural person is a beneficiary
Disputed	auth.002	Supplementary Data in accordance with the disputed schema

Table 4.3.2: Legal person, details specified for each message

Detail	Message(s)	Description
Name	fin.002, fin.013, supl.027	Returned in the Pty/Nm element attached to the role.
Registration number	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element.
Registration authority	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Registration date	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Unique identifier of the trader	fin.002, fin.013, supl.027	Returned as part of the Id element attached to the role, see Use of Id element
Disputed	auth.002	Supplementary Data in accordance with the disputed schema

Table 4.3.3: Bank and payment account, details specified for each message

Detail	Message(s)	Description
IBAN	supl.027	See Use of CustomerAccount
Date of opening the account	supl.027	Returned in the field AddtlInf
Date of closing the account	supl.027	See Use of CustomerAccount
Persons involved in the account	supl.027	Account holders and account access right holders
Account purpose	supl.027	See Use of CustomerAccount
Disputed	auth.002	Supplementary Data in accordance with the disputed schema

Table 4.3.4: Safety-deposit box, details specified for each message

Detail	Message(s)	Description
Identifier	fin.002	See Use of SafetyDepositBoxAndParties
Start date of the rental period	fin.002	See Use of SafetyDepositBoxAndParties
End date of the rental period	fin.002	See Use of SafetyDepositBoxAndParties
Persons involved in the safety-deposit box	fin.002	Safety-deposit box holders and safety-deposit box access right holders
Disputed	auth.002	Supplementary Data in accordance with the disputed schema

Table 4.3.5: Customership, details specified for each message

Detail	Message(s)	Description
Customership	fin.013	See InformationResponseFIN013
Start date	fin.013	See InformationResponseFIN013
End date	fin.013	See InformationResponseFIN013
Disputed	auth.002	Supplementary Data in accordance with the disputed schema

Table 4.3.6: Auth messages in accordance with the ISO 20022 catalogue

Message id	Name of the message	Purpose	Corresponding organisation	Msg Def Report
auth.001.001.01	InformationRequestOpeningV01	Query message of the query interface	FFI	MDR
auth.002.001.01	InformationRequestResponseV01	Response message of the query interface	FFI	MDR

Table 4.3.7: Submessage appended to the query message auth.001

Message id	Name of the message	ID of the extended ISO 20022 message	Purpose and functionality
FIN012	InformationRequestFIN012	auth.001.001.01	ISO 20022 message extension The competent authorities of the query interface use this message for querying information from the data retrieval interface. Includes the identifiers of the person making the enquiry and this person’s manager. Allows the use of auth.001.001.01 missing search criteria (for example safety deposit box)

Table 4.3.8: Submessages appended to the query message auth.002

Message id	Name of the message	ID of the extended ISO 20022 message	Purpose and functionality
supl.027.001.01	InformationResponseSD1V01	auth.002.001.01	Includes the account details corresponding to the search parameters
FIN002	InformationResponseFIN002	auth.002.001.01	Includes the details of safe-deposit boxes corresponding to the search parameters
FIN013	InformationResponseFIN013	auth.002.001.01	Includes customership details that correspond to the search parameters separated from account and safety deposit box information

4.4 BusinessApplicationHeaderV01

The use of BAH elements is shown in the table below. The element types are described in the head.001.001.01 schema.

Name	Type	In use	Description
BusinessApplicationHeaderV01
CharSet	UnicodeChartsCode	yes	“UTF-8”
Fr	Party9Choice	yes	Used as follows: Element Fr/OrgId/Id/OrgId/Othr/SchmeNm/Cd includes the value “Y” and element Fr/OrgId/Id/OrgId/Othr/Id includes the sender’s Business ID. When comparing the Business ID with the ID contained in the signature certificate, it must be noted that the ID in the certificate can be in either Business ID or VAT-number format.
To	Party9Choice	Yes	Used as follows: Element To/OrgId/Id/OrgId/Othr/SchmeNm/Cd includes the value “Y” and element To/OrgId/Id/OrgId/Othr/Id includes the sender’s Business ID (For example in the data retrieval system, the Business ID 0245442-8)
BizMsgIdr	Max35Text	yes	Use in accordance with the standard
MsgDefIdr	Max35Text	yes	Includes the message id. The query messages use “auth.001.001.01”, the response messages include “auth.002.001.01”
BizSvc		No
CreDt	ISONormalisedDateTime	yes	The date and time of creating the BAH. Must be normalised using Z notation (UTC).
CpyDplct		no
PssblDplct		no
Prty		no
Sgntr		yes	The XML signature formed by the business message sender. See Creating XML signatures
Rltd	BusinessApplicationHeader1	yes	Used in a response message, includes the BAH included in the query message.

4.5 InformationRequestOpeningV01

The table describes the use of records in the message.

Name	Type	In use	Description
InformationRequestOpeningV01
InvstgtnId	Max35Text	Yes	Always “Customs_aggr”
LglMndtBsis	LegalMandate1	Yes	Always “Customs_aggr”
CnfdtltySts	YesNoIndicator	Yes	Always “true”
DueDt	DueDate1	No
InvstgtnPrd	DateOrDateTimePeriodChoice	Yes	Date or date interval that the search concerns. The date interval is always today or in the past. The interval search must be performed in such way that if some interval determined in the data content (all date records in the tables 4.3.1–4.3.5) are included partly or entirely in the given InvstgtnPrd interval, the data row in question must be added to the search result. Only the Dt element is used.
SchCrit	SearchCriteria1Choice	Yes	Search criterion. The search criterion used must always be as specific as possible. See further specifications below.
SplmtryData	SupplementaryData1	Yes	Includes message extension InformationRequestFIN012

Limiting submessages in the search result

The system only returns the submessages requested in the search criteria (supl.027.001.01, fin.002.001.03, fin.013.001.04). Each submessage is requested in a separate element of the type AuthorityRequestType1, and 1–3 of these elements must be included in the search criteria.

Tag	Scheme path InfReqOpng/SchCrit/	Description
<MsgNmId>	Search by natural person’s personal identity code, by the combination of the name, nationality and date of birth of a natural person, by the registration number of a legal person, by legal person’s name or by safety-deposit box ID: CstmrId/AuthrtyReq/Tp Search by IBAN or other unique identifier of the account: Acct/AuthrtyReqTp	“supl.027.001.01”, “fin.002.001.03” or “fin.013.001.04”

Search by personal identity code

Tag	Scheme path InfReqOpng/SchCrit/	Description	Rule
<Id>	CstmrId/Pty/Id/PrvtId/Othr	Personal identity code	Valid personal identity code.
<Cd>	CstmrId/Pty/Id/PrvtId/Othr/SchmeNm	“PIC” (Personal Identity Code)
<Cd>	CstmrId/AuthrtyReq/InvstgtdRoles	“ALLP”

Search by the registration number of a legal person

Tag	Scheme path InfReqOpng/SchCrit/	Description	Rule
<Id>	CstmrId/Pty/Id/OrgId/Othr	Business ID or other identifier of a legal person
<Cd>	CstmrId/Pty/Id/OrgId/Othr/SchmeNm	“COID”
<Cd>	CstmrId/AuthrtyReq/InvstgtdRoles	“ALLP”

Search by company name

Tag	Scheme path InfReqOpng/SchCrit/	Description	Rule
<Nm>	CstmrId/Pty	Compan name	Exact match 1:1. Not case sensitive.
<Id>	CstmrId/Pty/Id/OrgId/Othr	The value is set as “1”
<Cd>	CstmrId/Pty/Id/OrgId/Othr/SchmeNm	“NAME”
<Cd>	CstmrId/AuthrtyReq/InvstgtdRoles	“ALLP”

If the given search criteria results in more than one matching company, fault code 7 is returned (see fault codes).

Search by IBAN

Tag	Scheme path InfReqOpng/SchCrit/	Description
<IBAN>	Acct/Id/Id	IBAN
<Cd>	Acct/InvstgtdPties	“ALLP”

Search by other identification code

Tag	Scheme path InfReqOpng/SchCrit/	Description
<Id>	Acct/Id/Id/Othr	Other code identifying the account
<Cd>	Acct/Id/Id/Othr/SchmeNm	OTHR
<Cd>	Acct/InvstgtdPties	“ALLP”

Search by a combination of the natural person’s name, nationality and date of birth

Tag	Scheme path InfReqOpng/SchCrit/	Description	Rule
<Nm>	CstmrId/Pty	Name	Exact match 1:1, incl. special characters. Not case sensitive. Format is “Lastname, Firstname Middlenames”.
<Id>	CstmrId/Pty/Id/PrvtId/Othr	Country code
<Cd>	CstmrId/Pty/Id/PrvtId/Othr/SchmeNm	“NATI”
<BirthDt>	CstmrId/Pty/Id/PrvtId/DtAndPlcOfBirth	Date of birth. “XX” is set as the value of CtryOfBirth, and “not in use” is set as the value of CityOfBirth
<Cd>	CstmrId/AuthrtyReq/InvstgtdRoles	“ALLP”

If the given search criteria results in more than one matching person, fault code 7 is returned (see fault codes).

Search by safety-deposit box ID

Due to the ISO message restrictions, some data must be entered in Document/InfReqOpng/SchCrit. CstmrId is completed:

Tag	Scheme path InfReqOpng/SchCrit/	Description
<Pty>	CstmrId	Is left blank
<Cd>	CstmrId/AuthrtyReq/InvstgtdRoles	“ALLP”

The actual search criterion, the safety-deposit box ID, is set in the SafetyDepositBoxId element of fin.012.001.03 message extension, which is set in the Supplementary Data of auth.001.001.01, as shown in the next table.

Tag	Scheme path InfReqOpng/SplmtryData/Envlp/	Description	Rule
<SafetyDepositBoxId>	Document/InfReqFin012/AdditionalSearchCriteria/	Safety-deposit box ID	Exact match 1:1, incl. special characters. Free-form format.

4.6 Message extension InformationRequestFIN012

The message extension is appended to the Xpath location of the ISO 20022 message listed in the table.

Name	[min..max]	Type	Description	Appended to message	XPath
InformationRequestFIN012				auth.001	/Document/InfReqOpng/SplmtryData/Envlp
AuthorityInquiry	[1..1]	AuthorityInquirySet	Authority details associated with the query
AdditionalSearchCriteria	[0..*]		Used for the search by safety-deposit box ID.

AuthorityInquirySet

Name	Type	In use	Description
AuthorityInquirySet
OfficialId	Max140Text	Yes	Always “Customs_aggr”
OfficialSuperiorId	Max140Text	Yes	Always “Customs_aggr”

4.7 InformationRequestResponseV01

The table describes the use of records in the message.

Name	Type	In use	[min..max]	Description
InformationRequestResponseV01
RspnId	Max35Text	Yes	[1..1]	Id of the response message
InvstgtnId	Max35Text	Yes	[1..1]	Case id sent in the query message
RspnSts	StatusResponse1Code	Yes	[1..1]	Status of the response message, “COMP”
SchCrit	SearchCriteria1Choice	Yes	[1..1]	The query message included the Document/InfReqOpng/SchCrit as such
RtrInd	ReturnIndicator1	Yes	[0..*]	See below for the use of ReturnIndicator1
SplmtryData	SupplementaryData1	Yes	[0..1]	See Returning disputed details

Use of ReturnIndicator1

ReturnIndicator1 includes the presence of a single type of search result.

XPath	Type	Description
RtrInd/AuthrtyReqTp/MsgNmId	Max35Text	Includes the message ID of a message extension (supl.027.001.01, fin.013.001.04 or fin.002.001.03)
RtrInd/InvstgtnRslt	InvestigationResult1Choice	Rslt element of type SupplementaryDataEnvelope1 is returned, including either supl.027.001.01, InformationResponseFIN002 or InformationResponseFIN013 or InvstgtnSts with code NFOU.

One search result sub-message (supl.027.001.01, fin.013.001.04 or fin.002.001.03) is returned per Business ID for each search result type.

Example 1.

Three results corresponding to the Document/InfReqOpng/SchCrit search criterion present in the query message have been found: one customer and two accounts. No safety-deposit boxes were found.

To the response message, three RtrInd elements shall be appended: regarding supl.027.001.01 and fin.013.001.04, the search results are appended to Rslt elements and regarding fin.002.001.03, InvstgtnSts shall be returned using code NFOU:

<!-- xmlns:n1="urn:iso:std:iso:20022:tech:xsd:auth.002.001.01" -->
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>supl.027.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:Rslt>
      <n2:Document xmlns:n2="urn:iso:std:iso:20022:tech:xsd:supl.027.001.01" ...>
        <n2:InfRspnSD1>
          <!-- Search result for account #1, account #2 -->
        </n2:InfRspnSD1>
      </n2:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:Rslt>
      <n1:Document xmlns:n3="fin.013.001.04" ...">
      	<n1:InfRspnFin013>
          <!-- Search result for customership #1 -->
        </n1:InfRspnFin013>
      </n1:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.03</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

Example 2.

The interface is a compilation: one interface returns search results under several different Business IDs.

Four results corresponding to the Document/InfReqOpng/SchCrit search criterion present in the query message have been found: one account (account #1) for Business ID 0190983-0 and three accounts (account #2, account #3, account #4) for Business ID 0828972-6.

To the response message, four RtrInd elements shall be appended: regarding supl.027.001.0, the search results are appended to Rslt elements and regarding fin.013.001.04 and fin.002.001.03, InvstgtnSts shall be returned using the code NFOU:

<!-- xmlns:n1="urn:iso:std:iso:20022:tech:xsd:auth.002.001.01" -->
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>supl.027.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:Rslt>
      <n2:Document xmlns:n2="urn:iso:std:iso:20022:tech:xsd:supl.027.001.01" ...>
        <n2:InfRspnSD1>
          <n2:InvstgtnId>a</n2:InvstgtnId>
            <n2:CreDtTm>
              <!-- -->
            </n2:CreDtTm>
            <n2:AcctSvcrId>
              <n2:FinInstnId>
                <n2:Othr>
                  <n2:Id>0190983-0</n2:Id>
                  <n2:SchmeNm>
                    <n2:Cd>Y</n2:Cd>
                  </n2:SchmeNm>
                </n2:Othr>
              </n2:FinInstnId>
            </n2:AcctSvcrId>
            <n2:AcctAndPties>
              <!-- Search results for Business ID 0190983-0, account #1-->
            </n2:AcctAndPties>
        </n2:InfRspnSD1>
      </n2:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>supl.027.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:Rslt>
      <n2:Document xmlns:n2="urn:iso:std:iso:20022:tech:xsd:supl.027.001.01" ...>
        <n2:InfRspnSD1>
          <n2:InvstgtnId>a</n2:InvstgtnId>
          <n2:CreDtTm>
            <!-- -->
          </n2:CreDtTm>
          <n2:AcctSvcrId>
            <n2:FinInstnId>
              <n2:Othr>
                <n2:Id>0828972-6</n2:Id>
                <n2:SchmeNm>
                  <n2:Cd>Y</n2:Cd>
                </n2:SchmeNm>
              </n2:Othr>
            </n2:FinInstnId>
          </n2:AcctSvcrId>
          <n2:AcctAndPties>
            <!-- Search results for Business ID 0828972-6, account #2, account #3, account #4 -->
          </n2:AcctAndPties>
        </n2:InfRspnSD1>
      </n2:Document>
    </n1:Rslt>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.03</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

Example 3.

No results matching the search term Document/InfReqOpng/SchCrit in the query message were found.

To the response message, three InvstgtnSts elements shall be appended using the code NFOU.

<!-- xmlns:n1="urn:iso:std:iso:20022:tech:xsd:auth.002.001.01" -->
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>supl.027.001.01</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.013.001.04</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>
<n1:RtrInd>
  <n1:AuthrtyReqTp>
    <n1:MsgNmId>fin.002.001.03</n1:MsgNmId>
  </n1:AuthrtyReqTp>
  <n1:InvstgtnRslt>
    <n1:InvstgtnSts>NFOU</n1:InvstgtnSts>
  </n1:InvstgtnRslt>
</n1:RtrInd>

4.8 InformationResponseSD1V01 supl.027.001.01

The table describes the use of records in the message.

If the response does not contain any account information, supl.027 submessage is marked with status code NFOU in the response message, see use of ReturnIndicator1.

Name	Type	In use	[min..max]	Description
InformationResponseSD1V01 supl.027.001.01
InvstgtnId	Max35Text	Yes	[1..1]	Case id of the investigation
CreDtTm	ISODateTime	Yes	[1..1]	Time of creating the message
AcctSvcrId	BranchAndFinancialInstitutionIdentification4	Yes	[1..1]	Used as follows: Element AcctSvcrId/FinInstnId/Othr/SchmeNm/Cd Cd includes the value “Y” and element AcctSvcrId/FinInstnId/Othr/Id includes the sender’s Business ID.
AcctAndPties	AccountAndParties2	Yes	[1..*]	See table below

Use of AccountAndParties2

Name	Type	In use	[min..max]	Description
AccountAndParties2
Acct	CustomerAccount1	Yes	[1..1]	For account details, see the use of CustomerAccount1
Role	AccountRole1	Yes	[1..*]	For the account-related roles, see the second table below. Every role must be provided separately. For example, if a natural person is both the account holder and has access right to the account, there are two Role elements, one of which has OwnrTp=OWNE and the other OwnrTp=ACCE, see Use of AccountRole1. Every role can have a start date and optional end date. In addition to this, the customership connected to each role must be indicated in the fin.013 submessage once per party, if this is not forbidden by the data limitations rules. For example, in this case one customership is indicated for the person in the example.
AddtlInf	Max256Text	Yes	[0..1]	The date of opening the account, as a string of characters in ISODate format.

Use of CustomerAccount1

Name	Type	In use	[min..max]	Description
CustomerAccount1
Id	AccountIdentification4Choice	Yes	[1..1]	Either IBAN or other account identifier, see supl.027.001.01 scheme. Regarding long identifiers, the code GLID (Generic Long Id) is set in the Acct/Id/Othr/SchmeNm/Cd element and “1” is set as the Acct/Id/Othr/Id value. The actual ID (credit card number) is set in the Acct/Nm element.
Nm		No
Sts		No
Tp		No
Ccy		Yes	[1..1]	“EUR”
MnthlyPmtVal		No
MnthlyRcvdVal		No
MnthlyTxNb		No
AvrgBal		No
AcctPurp	Max140Text	Yes	[0..1]	Returned only when the account is lawyer’s customer asset account. In this case the calue is “customer_asset_account”.
FlrNtfctnAmt		No
ClngNtfctnAmt		No
StmtCycl		No
ClsgDt	ISODate	Yes	[0..1]	Date of closing the account
Rstrctn		No

Use of AccountRole1

Name	Type	In use	[min..max]	Description
AccountRole1
Pty	PartyIdentification41	Yes	[1..*]	See Use of Id element
OwnrTp	OwnerType1	Yes	[1..1]	“RLTP” is set as the content of OwnrTp/Prtry/SchmeNm, and “OWNE” (account holder, “owner”) or “ACCE” (holder of access right to the account, “access right”) is set as the content of OwnrTp/Prtry/Id. In OwnrTp/Tp, enter value “TRUS”, which doesn’t mean anything here.
StartDt	ISODate	Yes	[0..1]	Start date of the role
EndDt	ISODate	Yes	[0..1]	End date of the role

4.9 InformationResponseFIN002

The message extension is appended to the Xpath location of the ISO 20022 message listed in the table.

If the response does not contain any safety deposit box information, FIN002 submessage is marked with status code NFOU in the response message, see use of ReturnIndicator1.

Name	[min..max]	Type	In use	Description	Appended to message	XPath
InformationResponseFIN002					auth.002	/Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
InvstgtnId	[1..1]	Max35Text	Yes	Case id of the investigation
CreDtTm	[1..1]	ISODateTime	Yes	Time of creating the message
SvcrId	[1..1]	BranchAndFinancialInstitutionIdentification4	Yes	Used as follows: Element SvcrId/FinInstnId/Othr/SchmeNm/Cd includes the value “Y”, and element SvcrId/FinInstnId/Othr/Id includes the sender’s Business ID.
SdBoxAndPties	[0..*]	SafetyDepositBoxAndParties	Yes	Safety-deposit box and parties, see Use of SafetyDepositBoxAndParties

Use of SafetyDepositBoxAndParties

Name	Type	In use	[min..max]	Description
SafetyDepositBoxAndParties
SdBox	SdBox	Yes	[1..1]	Account details see Use of SdBox
Role	SdBoxRole	Yes	[1..*]	For the safety-deposit box-related roles, see the second table below. Every role must be indicated separately for the code OwnrTp=OWNE. In addition to this, the customership connected to each role must be indicated in the fin.013 submessage once per party.

Use of SdBox

Name	Type	In use	[min..max]	Description
CustomerAccount1
Id	Max34Text	Yes	[1..1]	Unique safety-deposit box ID
OpngDt		Yes	[0..1]	Start date of the rental period**
ClsgDt		Yes	[0..1]	End date of the rental period**

*) The length of the rental period must be indicated as start date or end date or date interval.

Use of SdBoxRole

Name	Type	In use	[min..max]	Description
AccountRole1
Pty	PartyIdentification41	Yes	[1..*]	See Use of Id element
OwnrTp	OwnerType1	Yes	[1..1]	Use OwnrTp/Prtry/SchmeNm with value “RLTP”, as well as OwnrTp/Prtry/Id, in which the values “OWNE” (safety-deposit box holder, “owner”) or “ACCE” (holder of access right to the safety-deposit box, “access right”).
StartDt	ISODate	Yes	[0..1]	Start date of role
EndDt	ISODate	Yes	[0..1]	End date of role

4.10 InformationResponseFIN013

The message extension is appended to the Xpath location of the ISO 20022 message listed in the table.

If the response does not contain any beneficiary information or customership information (start and possible end date of customership), FIN013 submessage is marked with status code NFOU in the response message, see use of ReturnIndicator1.

Name	In use	[min..max]	Type	Description	Appended to message	XPath
InformationResponseFIN013					auth.002	/Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
InvstgtnId	Yes	[1..1]	Max35Text	Case id of the investigation
CreDtTm	Yes	[1..1]	ISODateTime	Time of creating the message
SvcrId	Yes	[1..1]	BranchAndFinancialInstitutionIdentification4	Used as follows: Element SvcrId/FinInstnId/Othr/SchmeNm/Cd includes the value “Y”, and element SvcrId/FinInstnId/Othr/Id includes the sender’s Business ID.
LegalPersonInfo	Yes	[1..*]	LegalPersonInfo	Legal person or natural person. See Use of LegalPersonInfoelement table below

Use of LegalPersonInfo element

Otherwise in this document, the term legal person refers to companies, associations, organisations and other not natural persons, but the LegalPersonInfo element can contain information about both a natural person and a legal person depending on the situation.

If the response message does not contain customership dates (CustomerInfo element) nor beneficiary information (Beneficiaries element), FIN013 submessage is not included in the response message at all. In this case, FIN013 submessage is marked with status code NFOU in the response, see use of ReturnIndicator1.

Name	Type	In use	[min..max]	Description
Id	PartyIdentification41b	Yes	[1..1]	In this field, credit institutions return the information of the legal person who is related to the customership information (CustomerInfo element) or beneficiary information (Beneficiaries element) included in the message. Other data suppliers return in this field the information of the legal or natural person related to customership information (CustomerInfo element). See Use of Id element
CustomerInfo	CustomerInfo	Yes	[0..1]	Customership information i.e. the start date and possible end date of the customership. See Use of CustomerInfo element
Beneficiaries	Beneficiaries	Yes	[0..1]	Information on beneficiaries. See Use of Beneficiaries

Use of CustomerInfo element

Name	Type	In use	[min..max]	Description
OpngDt	ISODate	Yes	[1..1]	Customership start date
ClsgDt	ISODate	Yes	[0..1]	Customership end date

Use of Beneficiaries

Name	Type	In use	[min..max]	Description
Id	Beneficiary	Yes	[1..*]	See Use of Beneficiary element

Use of Beneficiary element

Name	Type	In use	[min..max]	Description
Nm	Max140Text	Yes	[1..1]	Beneficiary’s name. Free-form format.
PrvtId	PersonIdentification5b	Yes	[1..1]	Natural person. See Use of PersonIdentification5b element
StartDt	ISODate	Yes	[0..1]	Start date of role
EndDt	ISODate	Yes	[0..1]	End date of role

4.11 Use of Id element

All messages use the equivalent identification structure for legal persons and natural persons under the Id-element (Party8Choice). Use of the Id element at the query interface is described here.

Name	Type	In use	[min..max]	Description
Nm	Max140Text	Yes	[1..1]	Free-form format.
Id	Party8Choice	Yes	[1..1]

Party8Choice

Name	Type	[min..max]	Description
Party8Choice
OrgId	OrganisationIdentification6	[0..1]	Used as follows: Element OrgId/Othr/SchmeNm/Cd includes the type code of the organisation identifier and element OrgId/Othr/Id includes the identifier. For codes, see the table below. Furthermore, the date of registration of a legal person can be returned in connection with the query response, see the Example below. If the organisation in question is a public guardian with a sequence number, the number is returned in its own OrgId/Othr/Id element along with sequence number code in OrgId/Othr/SchmeNm/Cd element, see the Example below.
PrvtId	PersonIdentification5	[0..1]	See Use of PersonIdentification5 element

Use of PersonIdentification5 and PersonIdentification5b elements

PersonIdentification5 element is used with InformationResponseSD1V01 supl.027.001.01 and InformationResponseFIN002 submessages.

XPath	Type	Description
Othr/SchmeNm/Cd	ExternalPersonIdentification1Code	Contains the person identification type code or nationality code, if the person doesn’t have a personal identity code.
Othr/Id	Max35Text	Contains the identification or country code. See codes table below.
DtAndPlcOfBirth	DateAndPlaceOfBirth	See table below.

PersonIdentification5b element is used with InformationResponseFIN013 submessage.

XPath	Type	Description
Othr/SchmeNm/Cd	ExternalPersonIdentification1Code	Contains the person identification type code or nationality code, if the person doesn’t have a personal identity code.
Othr/Id	Max35Text	Contains the identification or country code. See codes table below.
DtAndPlcOfBirth	DateAndPlaceOfBirth2	See table below.

OrgId codes

Code	Description
Y	Business ID
PRH	Association register number
COID	Other business identifier, type not known
ORDN	Public guardian sequence number

PrvtId codes

Code	Description
PIC	Finnish personal identity code
NATI	Nationality

Date of birth

Name	Type	Description
DtAndPlcOfBirth	DateAndPlaceOfBirth
BirthDt	ISODate	Date of birth.
CityOfBirth	Max35Text	The value of CityOfBirth is set to “not in use”.
CtryOfBirth	CountryCode	The value of CtryOfBirth is set to “XX”.

Name	Type	Description
DtAndPlcOfBirth	DateAndPlaceOfBirth2
BirthDt	ISODate	Date of birth.

An example of returning the date of registration of a legal person

The date of registration of a legal person is returned as an Othr element parallel to the identification element (for example Business ID):

The date of registration is returned in the Id element. Code RGDT is returned in the SchmeNm/Cd element, and the name of the registering authority is returned in the Issr element.

<OrgId>
  <Othr>
    <Id>1234567-8</Id>
    <SchmeNm>
      <Cd>Y</Cd>
    </SchmeNm>
  </Othr>
  <Othr>
    <Id>2000-01-01</Id>
    <SchmeNm>
      <Cd>RGDT</Cd>
    </SchmeNm>
    <Issr>Verohallinto</Issr>
  </Othr>
</OrgId>

An example of returning the public guardian sequence number of a legal person

The guardian sequence number of a legal person is returned as an Othr element parallel to the identification element (for example Business ID) and possible date of registration element:

The sequence number is returned in the Id element. Code ORDN is returned in the SchmeNm/Cd element.

<OrgId>
  <Othr>
    <Id>1234567-8</Id>
    <SchmeNm>
      <Cd>Y</Cd>
    </SchmeNm>
  </Othr>
  <Othr>
    <Id>2000-01-01</Id>
    <SchmeNm>
      <Cd>RGDT</Cd>
    </SchmeNm>
    <Issr>Verohallinto</Issr>
  </Othr>
  <Othr>
    <Id>1</Id>
    <SchmeNm>
      <Cd>ORDN</Cd>
    </SchmeNm>
  </Othr>
</OrgId>

4.12 WS message traffic scenarios at the query interface

This chapter describes the WS message traffic scenarios at the query interface.

Scenario 1 - OK

Description	The message was successfully processed in its entirety.
HTTP status code	202
Consequence	Head.001.001.01 and auth.002.001.01 messages and any submessages are returned.

Scenario 2 - An error has occurred

Description	An error has occurred.
HTTP status code	500
Consequence	SOAP Fault is returned, see table below.

Table 4.12.1: Fault codes

Error condition	Fault code	Fault string	Detail	Error code
The asynchronously initiated query has been lost	SOAP-ENV:Server	The query has been lost. Please re-send initial query.	<errorcode>1</errorcode>	1
The XML signature is invalid	SOAP-ENV:Client	The provided signature is invalid.	<errorcode>2</errorcode>	2
The transaction was rejected due to a too frequent polling interval	SOAP-ENV:Client	Too many requests	<errorcode>3</errorcode>	3
There are validation errors in the message, for example incorrect investigation period	SOAP-ENV:Client	Bad Request	1 ValidationError element per validation error eg. <errorcode>4</errorcode> <ValidationError>Description of validation error</ValidationError>	4
The user indicated in the message does not have access rights	SOAP-ENV:Client	Unauthorized	<errorcode>5</errorcode>	5
Query response size is too large (over 5 Mb)	SOAP-ENV:Client	Query response size is too large. Please refine the query.	<errorcode>6</errorcode>	6
Query response has multiple hits	SOAP-ENV:Client	Query response has multiple hits. Please refine the query.	<errorcode>7</errorcode>	7
Server error	SOAP-ENV:Server	Internal Server Error	<errorcode>0</errorcode>	0

Listing 4.12.1: Example of a returned SoapFault with errorcode 7

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Client</faultcode>
            <faultstring xml:lang="en">Query response has multiple hits. Please refine the query.</faultstring>
            <detail>
                <errorcode>7</errorcode>
            </detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Listing 4.12.2: Example of a returned SoapFault with errorcode 4, when there are multiple validation errors

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Client</faultcode>
            <faultstring xml:lang="en">Bad Request</faultstring>
            <detail>
                <errorcode>4</errorcode>
                <ValidationError>Validation error 1 description</ValidationError>
                <ValidationError>Validation error 2 description</ValidationError>
            </detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.13 Returning disputed details

Some of the details presented in the query response could be disputed. In that case, supplementary data in accordance with disputed.xsd is appended to auth.002.001.01 message under Document/InfReqRspn/SplmtryData element, where the identifiers of disputed records are listed.

Listing 4.13.1: Example of reporting disputed details in Supplementary Data

<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="disputed.xsd">
	<Disputed>
		<DisputedEntityId>
			<Id>290408-616V</Id>
			<Code>PIC</Code>
		</DisputedEntityId>
		<FinancialInstitutionId>
			<Id>0245442-8</Id>
			<Code>Y</Code>
		</FinancialInstitutionId>
	</Disputed>
</Document>

Table 4.13.1: Id codes of disputed details

Code	Description
PIC	Personal identity code
Y	Business ID
PRH	Registration number in the Finnish Register of Associations
COID	Other identifier of a legal person
ACCT	Account identifier, e.g. IBAN
SDBX	Safety-deposit box ID
NAME+NATI+BDAT	A special case when the personal identity code is not known. In this case, the complete name, nationality and date of birth must be returned, see example below.

Listing 4.13.2: Example of reporting disputed details in Supplementary Data A special case when the personal identity code is not known. In this case, the complete name, nationality and date of birth must be returned

<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="disputed.xsd">
<Disputed>
    <DisputedEntityId>
      <Id>Markkanen, VNokko</Id>
      <Code>NAME</Code>
    </DisputedEntityId>
    <DisputedEntityId>
      <Id>FI</Id>
      <Code>NATI</Code>
    </DisputedEntityId>
    <DisputedEntityId>
      <Id>2008-04-29</Id>
      <Code>BDAT</Code>
    </DisputedEntityId>
    <FinancialInstitutionId>
      <Id>0245442-8</Id>
      <Code>Y</Code>
    </FinancialInstitutionId>
  </Disputed>
</Document>

5. Limitations of data returned by query based on category

The data returned by a query varies based on the search criteria used. This chapter describes how the data returned by each query type depends on the customer category, in addition to the search criteria.

Data providers have been divided into two categories: customer category 1 that represents the credit institutions and customer category 2 that represents payment institutions, electric money institutions and virtual currency providers.

5.1 Customer category 1

5.1.1 Natural person query

If person who is the object of the query owns or has access right to an account or a safety deposit box in the credit institution, the response includes the information of organisations where the person is a beneficiary, and information of accounts and safety deposit boxes the person owns or has access right to during the investigation period. Other natural or legal persons who own or have access right to these accounts or safety deposit boxes are not returned. Customership information is not returned. Lawyer’s customer asset accounts are not returned. If the person has no accounts or safety deposit boxes in the credit institution, response “NFOU” is returned.

Table 5.1.1.1: Limitations to queries for a person. This query category contains queries with a personal ID and queries with a natural person’s name, nationality and birth date combination

Limitation	Submessage	Element	Description
Customership information	InformationResponseFIN013	/LegalPersonInfo/CustomerInfo	CustomerInfo element is not returned
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndDt	Account role end date is not returned.
Other legal or natural persons related to an account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role	In natural person query, only the role related to the natural person defined in the query is returned with the account data.
Other legal or natural persons related to a safety deposit box	InformationResponseFIN002	/SdBoxAndPties/Role	In natural person query, only the role related to the natural person defined in the query is returned with the safety deposit box data.
Other persons related to an organisation	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries	In natural person query, only the role related to the person defined in the query is returned with the organisation data.
Safety deposit box role start date	InformationResponseFIN002	/SdBoxAndPties/Role/StartDt	Safety deposit box role starting date is not returned.
Safety deposit box role end date	InformationResponseFIN002	/SdBoxAndPties/Role/EndDt	Safety deposit box role ending date is not returned.
Beneficiary role starting date	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries/Beneficiary/StartDt	Beneficiary role starting date is not returned.
Beneficiary role ending date	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries/Beneficiary/EndDt	Beneficiary role ending date is not returned.
Lawyer’s customer asset account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties	An account is not returned, if it is a lawyer’s customer asset account.

5.1.2 Organisation query

If organisation who is the object of the query owns or has access right to an account or a safety deposit box in the credit institution, the response includes the information of persons who are beneficiaries of the organisation and information of accounts and safety deposit boxes the organisation owns or has access right to during the investigation period. Other natural or legal persons who own or have access right to these accounts or safety deposit boxes are not returned. If the organisation owns any accounts or safety deposit boxes in the credit institution, organisation’s customership information is returned. If the organisation has only access right to an account or a safety deposit box, customership information is not returned. Lawyer’s customer asset accounts are not returned. If the organisation has no accounts or safety deposit boxes in the credit institution, response “NFOU” is returned.

Table 5.1.2.1: Limitations to queries for an organisation. This query category contains queries with a company’s name and queries with legal person’s registration number

Limitation	Submessage	Element	Description
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndDt	Account role end date is not returned.
Other legal or natural persons related to an account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role	In organisation query, only the role related to the legal person defined in the query is returned with the account data.
Other legal or natural persons related to a safety deposit box	InformationResponseFIN002	/SdBoxAndPties/Role	In organisation query, only the role related to the legal person defined in the query is returned with the safety deposit box data.
Safety deposit box role start date	InformationResponseFIN002	/SdBoxAndPties/Role/StartDt	Safety deposit box role starting date is not returned.
Safety deposit box role end date	InformationResponseFIN002	/SdBoxAndPties/Role/EndDt	Safety deposit box role ending date is not returned.
Beneficiary role starting date	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries/Beneficiary/StartDt	Beneficiary role starting date is not returned.
Beneficiary role ending date	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries/Beneficiary/EndDt	Beneficiary role ending date is not returned.
Lawyer’s customer asset account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties	An account is not returned, if it is a lawyer’s customer asset account.

5.1.3 Account query

In customer category 1 account query the response includes the information of the account that was the object of the query and information of the legal and natural persons who are account owners or have access right to the account during the investigation period. Customership information is returned for account’s owners who are organisations. Customership information is not returned for organisations that have only access right to the account. Organisation’s beneficiary information is not returned.

Table 5.1.3.1: Limitations to queries for an account. This query category contains queries with an account’s IBAN number and queries with other account identifications

Limitation	Submessage	Element	Description
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndDt	Account role end date is not returned.
Account opening date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/AddtlInf	Account opening date is not returned if the account in question is lawyer’s customer asset account. See Use of CustomerAccount.
Account closing date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Acct/ClsgDt	Account closing date is not returned if the account in question is lawyer’s customer asset account. See Use of CustomerAccount.
Customership information	InformationResponseFIN013	/LegalPersonInfo/CustomerInfo	CustomerInfo is not returned about a natural person.
Beneficiaries	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries	Beneficiaries related to a legal person are not returned.

5.1.4 Safety deposit box query

In customer category 1 safety deposit box query the response includes the information of the safety deposit box that was the object of the query and information of the legal and natural persons who are own or have access right to the safety deposit box during the investigation period. Customership information is returned for safety deposit box’s owners who are organisations. Customership information is not returned for organisations that have only access right to the safety deposit box. Organisation’s beneficiary information is not returned.

Table 5.1.4.1: Limitations to queries for a safety deposit box. This query category contains queries with a safety deposit box’s identification

Limitation	Submessage	Element	Description
Safety deposit box role start date	InformationResponseFIN002	/SdBoxAndPties/Role/StartDt	Safety deposit box role starting date is not returned.
Safety deposit box role end date	InformationResponseFIN002	/SdBoxAndPties/Role/EndDt	Safety deposit box role ending date is not returned.
Customership information	InformationResponseFIN013	/LegalPersonInfo/CustomerInfo	CustomerInfo is not returned about a natural person.
Beneficiaries	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries	Beneficiaries related to a legal person are not returned.

5.2 Customer category 2

5.2.1 Natural person query

In customer category 2 natural person query, the response includes the customership information of the person who was the object of the query and information of accounts the person owns or has access right to during the investigation period. Other natural or legal persons who own or have access right to these accounts are not returned. Organisation’s beneficiary information is not returned. Lawyer’s customer asset accounts are not returned.

Table 5.2.1.1: Limitations to queries for a person. This query category contains queries with a personal ID and queries with a natural person’s name, nationality and birth date combination

Limitation	Submessage	Element	Description
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndDt	Account role end date is not returned.
Account opening date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/AddtlInf	Account opening date is not returned.
Account closing date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Acct/ClsgDt	Account closing date is not returned.
Organisations based on beneficiary role	InformationResponseFIN013	/LegalPersonInfo	No data related to legal persons where the queried natural person is a beneficiary is returned with the InformationResponseFIN013 Submessage.
Other legal or natural persons related to an account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role	In natural person query, only the role related to the natural person defined in the query is returned with the account data.
Lawyer’s customer asset account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties	An account is not returned, if it is a lawyer’s customer asset account.

5.2.2 Organisation query

In customer category 2 organisation query, the response includes the customership information of the organisation that was the object of the query and information of accounts the organisation owns or has access right to during the investigation period. Other natural or legal persons who own or have access right to these accounts are not returned. Organisation’s beneficiary information is not returned. Lawyer’s customer asset accounts are not returned.

Table 5.2.2.1: Limitations to queries for an organisation. This query category contains queries with a company’s name and queries with legal person’s registration number

Limitation	Submessage	Element	Description
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndDt	Account role end date is not returned.
Account opening date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/AddtlInf	Account opening date is not returned.
Account closing date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Acct/ClsgDt	Account closing date is not returned.
Beneficiaries	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries	Beneficiaries related to a legal person are not returned.
Other legal or natural persons related to an account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role	In organisation query, only the role related to the legal person defined in the query is returned with the account data.
Lawyer’s customer asset account	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties	An account is not returned, if it is a lawyer’s customer asset account.

5.2.3 Account query

In customer category 2 account query the response includes the information of the account that was the object of the query and information of the legal and natural persons who are account owners or have access right to the account during the investigation period. If the account in question is a lawyer’s customer asset account, customership information is not returned for natural persons. Otherwise customership information is returned for all natural and legal persons who are account owners or have access right to the account. Organisation’s beneficiary information is not returned.

Table 5.2.3.1: Limitations to queries for an account. This query category contains queries with an account’s IBAN number and queries with other account identifications

Limitation	Submessage	Element	Description
Account role start date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/StartDt	Account role start date is not returned.
Account role end date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Role/EndtDt	Account role end date is not returned.
Account opening date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/AddtlInf	Account opening date is not returned.
Account closing date	InformationResponseSD1V01 supl.027.001.01	/AcctAndPties/Acct/ClsgDt	Account closing date is not returned.
Customership information	InformationResponseFIN013	/LegalPersonInfo/CustomerInfo	CustomerInfo is not returned for natural persons if the account in question is lawyer’s customer asset account. See Use of CustomerAccount.
Beneficiaries	InformationResponseFIN013	/LegalPersonInfo/Beneficiaries	Beneficiaries related to a legal person are not returned.