How to import data

Last updated: November 9, 2026

You can import your existing cases into Ondorse in bulk, with their related natural persons and documents. You upload one file per type of data (.csv or .xlsx, plus a .zip for document files). Ondorse validates each file and imports the valid rows. You can then fix the rows that failed and re-upload only those.

Import page

Overview

  1. Copy the import template and fill one tab per type of data.

  2. Go to Settings > Data > Import / export, tab Import.

  3. Upload your files in this order: cases, then related natural persons, then documents.

  4. Check the result of each import and fix failed rows with the Error report.

1. Prepare your files with the template

Start by copying our import template.

Import template

Each tab of the template matches one section of the Import page:

Template tab

Import section

Use it for

Business cases

Business cases

Cases whose subject is a business (KYB)

Natural person cases

Natural person cases

Cases whose subject is a natural person (KYC)

Related persons

Related natural persons

Persons attached to your business cases (UBOs, shareholders, legal representatives…)

Documents

Documents

Documents attached to cases or persons, with a .zip of the document files

The tabs prefixed ref: list the accepted values for some columns, such as legal types.

Column names don't have to match the template exactly: you can remap them during the import.

2. Format of each file

Business cases

Column

Description

Constraint

external_reference

Your reference for the customer or case (account ID, client ID…). The other files use it to point to this case.

Required. Unique within your account.

incorporation_country

Registration country of the company

Required. ISO 3166 alpha-3 code, e.g. FRA, GBR

registration_number

Registration number of the company

Required

organization_name

Name of the company

Required

legal_type

Legal form of the company

Required. One of the values in the ref: legal types tab

onboarding_date

Date the customer was onboarded, e.g. date of first KYC or start of the business relationship

YYYY-MM-DD

address_*

Address of the company

See Address format

custom_fields.XXX

Value of a custom field. Replace XXX with the custom field's API field name (Settings > Data > Custom fields). Add one column per custom field.

Must match the custom field's type, e.g. one of its dropdown values

Business cases example

Natural person cases

Column

Description

Constraint

external_reference

Your reference for the customer (account ID, client ID…)

Required. Unique within your account.

custom_fields.XXX

Value of a custom field, XXX being its API field name. Add one column per custom field.

Must match the custom field's type

Fill the other columns of the Natural person cases template tab (identity, address) the same way as for related natural persons below.

Related natural persons

Column

Description

Constraint

external_reference

Your reference for the person. If you have none, use any unique identifier.

Required

case_external_reference

The external_reference of the case this person is attached to

Required

given_names

First name(s) of the person

last_name

Last name of the person

birth_date

Date of birth

birth_city

City of birth

email

Email address of the person

is_signatory

The person is the signatory of the case

TRUE or FALSE

is_UBO

The person is an ultimate beneficial owner

TRUE or FALSE

is_shareholder

The person is a shareholder

TRUE or FALSE

is_director

The person is a legal representative

TRUE or FALSE

address_*

Address of the person

See Address format

Documents

Upload this file together with a .zip file containing the document files. The path_to_file column points to each file in the .zip.

Column

Description

Constraint

external_reference

Your reference for the document. If you have none, use any unique identifier.

Required

case_external_reference

The external_reference of the case to attach the document to

Required if no person_external_reference

person_external_reference

The external_reference of the person to attach the document to

Required if no case_external_reference

path_to_file

Path of the file in the .zip. Example: for id_card.pdf in the documents folder of documents.zip, use documents/id_card.pdf

Required

expected_document_id

The expected document of your account this document corresponds to

ID of the expected document

country

Issuing country of the document

ISO 3166 alpha-3 code, e.g. FRA, GBR

expiration_date

Expiry date of the document

Address format

Addresses can use one of two formats. Set the format in the address_type column.

Single line: the whole address in one column.

Column

Constraint

address_type

single_line

address_single_line

Full address on one line (street, postal code, city)

address_country

ISO 3166 alpha-3 code, e.g. FRA, GBR

Multi-line: one column per component.

Column

Constraint

address_type

multi_line

address_line1

Street and number

address_city

City

address_postal_code

Postal code

address_country

ISO 3166 alpha-3 code, e.g. FRA, GBR

3. Upload your files

  1. Go to Settings > Data > Import / export and open the Import tab.

  2. Upload your files in the matching sections, in this order (persons and documents refer to cases that must already exist):

    • Business cases and/or Natural person cases: your cases file (.csv or .xlsx).

    • Related natural persons: your persons file (.csv or .xlsx).

    • Documents: your documents file (.csv or .xlsx), then the .zip of document files.

  3. Map your columns if their names differ from the template, then confirm. Ondorse validates the file before importing it.

Import sectionsUpload a file

4. Check the result and fix errors

Each import appears in the list under its section:

  • Import: in progress while it runs.

  • Once done: the import date, the number of rows, and how many were imported and failed.

If some rows failed, you don't need to start over:

  1. Click Error report to download a file with only the failed rows, and the reason for each error in a dedicated column.

  2. Fix the errors directly in that file.

  3. Upload it again in the same section. Only these rows are imported.

  4. Repeat until all rows are imported.

Import resultError report

If the report can't be generated, the import shows Report unavailable: contact support@ondorse.co.

To import your configuration (workflow, rules, custom fields…) rather than your data, see How to export and import configuration between environments.