CSV import

What does the CSV import do?

The CSV import creates or updates data of a front office in bulk from CSV files: parties, dossiers, the links between them (related parties, members and UBOs, signatories, insured parties, related dossiers), additional contact information of parties, partner users of the front office, and information exchanges for the counterparties of dossiers.

It is typically used to migrate the data of an FSP from its own system into Harmoney in one go, and to keep it in sync afterwards through a recurring feed. Each kind of data has its own import template; a CSV file always corresponds to exactly one template.

The same templates are available in two ways:

• Manually, through the Import button of the front-office application. A popup asks for the template, the delimiter and the file. When the import is finished, a result file can be downloaded (see Processing and result file).
• Automatically, through the CSV Import Scheduled Provider, which picks the file up from an SFTP/FTP server on a schedule.

Where to find the import button

Page in the front-office application	Templates	Required role / permission
Parties list	Parties, Party related parties, Party members and UBOs, Party contact information, Party signatories	Role PARTNER_MANAGER
Dossiers list	Dossiers, Dossier related parties, Dossier responsible parties, Dossier counterparties, Dossier insured parties, Dossier related dossiers	Permission IMPORT on FSP_DOSSIER_SET
Users of the front office (management)	Partner users	Permission IMPORT on FSP_MANAGEMENT_USER

The Financial service providers template is an administrator feature, available in the administrator application only.

File format

• One CSV file per template, UTF-8 encoded, at most 50 MB.
• The first row contains the column names. Column names are case-sensitive and must be written exactly as documented below.
• The delimiter is a comma or a semicolon and is selected when uploading the file (or configured). Every row uses the same delimiter; the first row must contain at least two columns, otherwise the delimiter is rejected.
• Values containing the delimiter, a newline or a double quote are surrounded by double quotes; a double quote inside a value is doubled ("").
• The required columns of a template must be present in the header, otherwise the whole file is refused before any row is processed. Optional columns may be left out completely. Remove the columns for which no data is available rather than leaving them empty.
• An empty cell means "no value": the import never removes existing data. When a row updates an existing record, only the cells with a value are applied, metadata columns are merged into the existing metadata and pipe-separated lists replace the existing list.

Value formats:

Type	Format
Date	yyyy-MM-dd, for example 2026-01-31.
Boolean	true or false.
Decimal	Comma as decimal separator, for example 1250,50. Dots, spaces and the euro sign are ignored.
Country code	ISO 3166-1 alpha-2, uppercase, for example BE.
Language	ISO 639-1 code, for example nl.
Phone number	International format, for example +32470010203.
E-mail address	Must be a valid e-mail address.
Metadata	A JSON object with key-value pairs, for example {"segment":"retail"}. Empty or blank values inside the JSON are treated as no value.
List	Values separated by a pipe (`
Reference	The external reference of a party, dossier or FSP, as known in the system of the front office. Used to find existing records.

Processing and result file

Rows are processed one by one, each in its own transaction: a row that fails is reported and skipped, the other rows are imported. Rows are matched with existing data through their external references, so a file can be re-imported without creating duplicates.

Every import produces a result file csv_import_<date>.csv with one line per row of the input file:

Column	Value
row_index	Identifies the row of the input file the message refers to; rows are numbered in file order.
message	OK, or the reason why the row was not imported (for example Validation error on row 12: Dossier reference invalid).
duration	The processing time of the row in milliseconds.

In the front-office application the result file is offered for download when the import has finished. For the scheduled provider it is stored as a document of the front office.

Recommended approach for a migration

1. Prepare one sheet per template, starting from the column lists below, and export every sheet to its own CSV file.
2. Open each CSV file in a text editor and check the formats (dates, country codes, company numbers, decimal separators) before importing.
3. Import on a test environment with a small, representative sample (five to ten parties and dossiers) and correct the files based on the result file.
4. Import in this order: parties first, then dossiers, then the links between parties and dossiers (related parties, members, insured parties, related dossiers, responsible parties or counterparties).
5. Repeat on production once the sample imports without errors.

Templates

Parties

Template HARMONEY_PARTY_IMPORT. Creates or updates the parties of the front office. One row can contain up to one company, one indivision, one partnership and up to five individuals; the columns of an individual are prefixed with individual1_ to individual5_.

Required: there are no mandatory columns, but every row must contain at least one party: a reference or a name of an individual (individual1_reference or individual1_lastname), a company (company_reference or company_name), an indivision (indivision_reference or indivision_name) or a partnership (partnership_reference or partnership_name).

Rules:

• A party is created when its reference is unknown and updated when it exists. A reference can be used for one party only: a company, indivision or partnership reference cannot be equal to an individual reference, and the individuals of a row must have different references.
• The individuals of a row become the members of the indivision or partnership of that row, each with an equal percentage.
• When a row contains individual1_… and individual2_… columns and no company, indivision or partnership, an indivision is created for the two individuals, named <lastname 1> - <lastname 2>.
• The type of a party that is the client of a dossier cannot be changed.
• indivision_name is limited to 255 characters.

Columns of an individual (replace individualN_ by individual1_ … individual5_):

Column	Type
individualN_reference	Reference
individualN_firstname, individualN_lastname	Text
individualN_gender	MALE or FEMALE
individualN_language	Language
individualN_mobile_phone	Phone number
individualN_email	E-mail address
individualN_date_of_birth	Date
individualN_place_of_birth	Text
individualN_country_of_birth, individualN_nationality	Country code
individualN_additional_nationalities	List of country codes
individualN_marital_status	Text
individualN_marital_status_since	Date
individualN_address_country_code, individualN_address_full_street, individualN_address_postal_code, individualN_address_city, individualN_address_subdivision	Official address
individualN_postal_address_country_code, individualN_postal_address_full_street, individualN_postal_address_postal_code, individualN_postal_address_city, individualN_postal_address_subdivision	Postal address
individualN_national_registration_number	Text
individualN_card_number	Text
individualN_card_expiry_date	Date
individualN_social_state	Text
individualN_social_state_since	Date
individualN_occupation	Text
individualN_occupation_since	Date
individualN_employer_name, individualN_employer_address	Text
individualN_nace_code	Text
individualN_state	Text
individualN_state_since	Date
individualN_legal_capacity	Text
individualN_metadata, individualN_external_metadata	Metadata

Columns of a company:

Column	Type
company_reference	Reference
company_name	Text
company_number, company_legal_form, company_type, company_nace_code	Text
company_address_country_code, company_address_full_street, company_address_postal_code, company_address_city, company_address_subdivision	Official address
company_postal_address_country_code, company_postal_address_full_street, company_postal_address_postal_code, company_postal_address_city, company_postal_address_subdivision	Postal address
company_website	Text
company_phone	Phone number
company_email	E-mail address
company_establishment_country_code	Country code
company_establishment_date	Date
company_vat_liable, company_lei_liable	Boolean
company_vat_number, company_lei_number	Text
company_iban	IBAN without spaces; creates a bank account on the company
company_state	Text
company_state_since	Date
company_metadata, company_external_metadata	Metadata

Columns of an indivision:

Column	Type
indivision_reference	Reference
indivision_name, indivision_type	Text
indivision_postal_address_country_code, indivision_postal_address_full_street, indivision_postal_address_postal_code, indivision_postal_address_city, indivision_postal_address_subdivision	Postal address
indivision_state	Text
indivision_state_since	Date
indivision_metadata, indivision_external_metadata	Metadata

Columns of a partnership:

Column	Type
partnership_reference	Reference
partnership_name, partnership_type, partnership_registration_number	Text
partnership_address_country_code, partnership_address_full_street, partnership_address_postal_code, partnership_address_city, partnership_address_subdivision	Official address
partnership_postal_address_country_code, partnership_postal_address_full_street, partnership_postal_address_postal_code, partnership_postal_address_city, partnership_postal_address_subdivision	Postal address
partnership_state	Text
partnership_state_since	Date
partnership_metadata, partnership_external_metadata	Metadata

Dossiers

Template HARMONEY_DOSSIER_IMPORT. Creates or updates dossiers for existing clients of the front office.

Column	Required	Type / meaning
client_reference	yes	Reference of an existing party, the client of the dossier.
dossier_name	yes	Name of the dossier.
dossier_number	yes	Number of the dossier, unique within the front office.
dossier_type	yes	Identifier of the dossier type.
dossier_product	yes	Identifier of the dossier service (product).
dossier_reference	no	External reference of the dossier. An existing dossier with this reference is updated; the other link templates refer to dossiers through this reference.
dossier_start_date	no	Date. Creation date of the dossier.
dossier_status	no	Dossier status. On an existing dossier the status is changed without executing the actions linked to the status change.
dossier_lifecycle	no	Lifecycle of the dossier.
dossier_internal_info	no	Notes on the dossier.
dossier_intermediary_reference	no	Reference of the intermediary FSP linked to the dossier.
dossier_metadata, dossier_external_metadata	no	Metadata.
dossier_external_source	no	External source of the dossier.
dossier_task_identifiers	no	List of task identifiers.
dossier_rba_result_manual_assessment	no	Manual assessment of the risk-based assessment.
dossier_rba_result_comments	no	Comment on the manual assessment.
dossier_transaction_amount	no	Decimal. Amount of the transaction of the dossier.
dossier_transaction_currency	no	Currency of the transaction (3 characters).
dossier_transaction_metadata	no	Metadata of the transaction.
dossier_premium	no	Decimal. Insurance dossiers: value of the premium.
dossier_periodicity	no	Insurance dossiers: payment frequency of the premium.
dossier_reserve	no	Decimal. Insurance dossiers: value of the reserve.
dossier_reserve_date	no	Date. Insurance dossiers: date of the reserve value.
iban	no	Insurance dossiers: IBAN.
dossier_account_type	no	Investment dossiers: type of the account.

Rules:

• The combination of dossier_type, dossier_product and the type of the client must correspond to a dossier definition of the front office.
• The client, type and product of an existing dossier cannot be changed.

Party related parties

Template HARMONEY_PARTY_RELATED_PARTIES_IMPORT. Links a related party to a party. Both parties must exist; a party cannot be related to itself.

Column	Required	Meaning
party_reference	yes	Reference of the party.
related_party_reference	yes	Reference of the related party.
relation_type	no	Identifier of the relation type.
metadata	no	Metadata of the relation.
comments	no	Comment on the relation.

Party signatories

Template HARMONEY_PARTY_SIGNATORIES_IMPORT. Links a signatory to a party. Both parties must exist; a party cannot be its own signatory. Only available through the scheduled provider.

Column	Required	Meaning
party_reference	yes	Reference of the party.
signatory_party_reference	yes	Reference of the signatory party.
signatory_type	no	Type of signatory.
metadata	no	Metadata of the signatory link.

Party members and UBOs

Template HARMONEY_PARTY_OWNERS_IMPORT. Adds an individual as member or UBO of a company, indivision or partnership. Both parties must exist; the party cannot be an individual and the member must be an individual.

Column	Required	Meaning
party_reference	yes	Reference of the party.
party_member_reference	yes	Reference of the individual added as member or UBO.
member_percentage	no	Decimal between 0 and 100.
ubo_type	no	Type of UBO.
member_metadata	no	Metadata of the membership.

Party contact information

Template HARMONEY_PARTY_CONTACT_INFO_IMPORT. Adds an additional e-mail address, phone number or address to an existing party.

Column	Required	Meaning
party_reference	yes	Reference of the party.
type	yes	EMAIL, PHONE or ADDRESS.
email	for EMAIL	The e-mail address. Not allowed for the other types.
phone	for PHONE	The phone number. Not allowed for the other types.
address_country_code, address_full_street, address_postal_code, address_city, address_subdivision	for ADDRESS	At least one of them. Not allowed for the other types.
sub_type	no	Sub type of the contact information.
metadata	no	Metadata of the contact information.

Dossier related parties

Template HARMONEY_DOSSIER_RELATED_PARTIES_IMPORT. Links a related party to a dossier. The dossier and the party must exist.

Column	Required	Meaning
dossier_reference	yes	Reference of the dossier.
related_party_reference	yes	Reference of the related party.
relation_type	no	Identifier of the relation type.
metadata	no	Metadata of the relation.
comments	no	Comment on the relation.

Dossier responsible parties

Template HARMONEY_DOSSIER_RESPONSIBLE_PARTIES_IMPORT. Adds a responsible party to a dossier, for front offices using the responsibility matrix of the Investor Flow module. The dossier and the party must exist.

Column	Required	Meaning
dossier_reference	yes	Reference of the dossier.
responsible_party_reference	yes	Reference of the responsible party.

Dossier counterparties

Template HARMONEY_DOSSIER_COUNTERPARTIES_IMPORT. Creates an information exchange on a dossier for an individual or intermediary counterparty, for front offices using the Information Exchange module.

Column	Required	Meaning
dossier_reference	yes	Reference of the dossier.
counterparty_reference	yes	Reference of the counterparty: the party reference of an individual, or the external reference of an intermediary FSP.
counterparty_type	no	INDIVIDUAL (default) or INTERMEDIARY.

For each row:

• The information exchange is created in status CREATED. The counterparty is not invited by the import; the information exchange is completed afterwards from the dossier page or through the configured automated actions.
• When the counterparty already has a pending or a completed information exchange on the dossier, the row is reported as OK and nothing changes. The import can therefore be re-run with the same file.
• When the dossier has a pending information exchange for another counterparty, that one is cancelled (rejection reason Replaced by CSV import, without executing the actions linked to the status change) and a new information exchange is created for the imported counterparty. Two rows for the same dossier thus end with the counterparty of the last row.
• The dossier must be in a status in which an information exchange can be created, and the flow configuration of the dossier definition must support the counterparty type; otherwise the row is reported with an error.

Dossier insured parties

Template HARMONEY_DOSSIER_INSURED_PARTIES_IMPORT. Links an insured party to a dossier. The dossier and the party must exist.

Column	Required	Meaning
dossier_reference	yes	Reference of the dossier.
insured_party_reference	yes	Reference of the insured party.

Dossier related dossiers

Template HARMONEY_DOSSIER_RELATED_DOSSIERS_IMPORT. Links a dossier to another dossier. Both dossiers must exist; a dossier cannot be related to itself.

Column	Required	Meaning
dossier_reference	yes	Reference of the dossier.
related_dossier_reference	yes	Reference of the related dossier.

Partner users

Template HARMONEY_PARTNER_USER_IMPORT. Creates the users of the front office and assigns their roles. All columns are required.

Column	Meaning
partner_first_name	First name of the user.
partner_last_name	Last name of the user.
partner_gender	MALE or FEMALE.
partner_language_iso	Language of the user.
partner_email	E-mail address of the user, must be valid.
partner_mobile_phone	Mobile phone number of the user, in international format.
partner_roles	List of role identifiers. At least one role; every role must be a role allowed for the front office.

Financial service providers

An administrator can import financial service providers in the administrator application. The columns are prefixed with financial_sp_: financial_sp_name (required), financial_sp_external_reference, financial_sp_language, financial_sp_email, financial_sp_phone, financial_sp_website, financial_sp_enterprise_number, financial_sp_fsma_number, financial_sp_legal_person_register, financial_sp_address_full_street, financial_sp_address_postal_code, financial_sp_address_city, financial_sp_address_country_code, financial_sp_definition_identifier (identifier of the FSP definition to apply) and financial_sp_external_metadata.