Importing colleagues from a spreadsheet

Learn how, as an HR admin, you can add all your colleagues to Heartsome in one go with an Excel or CSV file. Useful when you're starting with more than a handful of people, or switching from another system.

Where do you find it?

1. Go to People in the left menu.
2. Click Add people in the top right.
3. Choose Import via sheet.

To add one colleague at a time, use Add single colleague instead. See Adding colleagues to Heartsome.

What do you need?

• An .xlsx, .xls or .csv file of up to 10 MB.
• Column headers in the first row, with one row per colleague below.
• Up to 1,000 rows per import. If your file has more, Heartsome only imports the first 1,000. Split the file instead.

It's easiest to start from the template. In the first step, click Download template. The template has every column Heartsome knows, an example row, and dropdowns for fields with fixed values.
Note: the template includes an example row (John Doe). Overwrite or delete it, or it will be imported too.

You can also use an export from your payroll system or a list of your own. Heartsome recognises many column names by itself, including Dutch ones such as Voornaam, Achternaam and Startdatum.

Required fields

Every row needs these four fields:

• First name
• Last name
• Work email: the address the colleague will log in with. Use their work address, not their personal one.
• Job title

All other fields are optional. You can always fill them in later on the profile.

Which other columns can you import?

About the person: Preferred name, Pronouns, Language (en or nl), Date of birth, Gender identity, Personal email, Phone number, Street address, Postal code, City, Country of residence, Nationality, Identification number (such as the Dutch BSN), Bank account number and emergency contact details.
About their work: Teams, Manager email and Manager name.
About the contract: Employment type, Job level, Salary currency, Salary amount, Salary interval, Working hours per week, Contract start date, Probation end date and Contract end date.
Current time off balances: one column per time off policy. See below.

Bringing over current time off balances

For every time off policy you've set up, you can include a balance column. In the Map columns step these fields are called, for example, "Vacation current balance". In the template the column is called "[policy name] Balance".

Fill in how many days the colleague has left today. Not their entitlement for the whole year, but what they have left right now. That number becomes their starting balance in Heartsome. Half days are fine: 12.5 and 12,5 both work.

How to go about it:

1. Set up your time off policies first. See Setting up time off policies. A balance column only appears once the policy exists.
2. Turn on Auto-assign to new employees for that policy, so it's linked to everyone in the import straight away.
3. Only then download the template, so it includes the balance columns.

Step 1: Upload

Drag your file into the box, or click Browse files. Heartsome reads the file and shows how many rows it found.

Step 2: Map columns

You now see every column from your file, next to the Heartsome field it's mapped to. Heartsome maps as much as it can by itself. It's still worth checking:

1. For each column, check that the right field is chosen under Map to field. Required fields are marked with an asterisk (*).
2. Choose Skip column for columns you don't want to import.
3. Look at the Preview. It shows the value from the first row the way Heartsome will store it.
4. For fields with fixed values (such as Employment type) you'll see which values are accepted. If your file contains values Heartsome doesn't recognise, they're listed in an orange warning. Fix them in your file, or just carry on: only those rows will be rejected.
5. Click Validate data.

Step 3: Validate

Heartsome checks every row. This usually takes a few seconds. Then you'll see:

• At the top, how many rows are valid.
• A What needs fixing box, showing per column what's wrong, how many rows it affects and which values are in your file.
• A status per row: Valid (green), Invalid (red, with the reason underneath) or Already exists (orange).

All valid rows are already ticked. Untick any rows you don't want to import (yet). You can't tick rows with an error: they'll be skipped.

Click Import [number] employees.

Steps 4 and 5: Import and complete

Heartsome creates the colleagues and shows the progress as a percentage. Then you'll see the list of Imported employees.
Everyone from the import has the status Not invited yet, so no emails have gone out. That gives you time to check everything first. When you're ready, you have two options:

• Click Send invitations to all to invite all imported colleagues at once.
• Or invite people one by one later. See Inviting, suspending and removing colleagues.

Common errors

"Please map all required fields": one of the four required fields isn't mapped to any column. Choose it in step 2.
"Each field can only be mapped once": two columns point to the same field. Set one of them to Skip column.
"Duplicate email in import file": the same work email appears in more than one row. Every colleague needs their own address.
Already exists: there's already a colleague in Heartsome with this email address. The row is skipped and the existing colleague isn't changed.
"Not recognised, this value will fail validation": a field with fixed values contains something Heartsome doesn't know. Use one of the accepted values, in English or Dutch. For Employment type, for example: Permanent contract, Temporary contract, Contractor, Flex worker, Freelancer, Intern or Volunteer.
Wrong date: use a real date cell in Excel, or write the date as 2026-01-15. A date like 01/02/2026 can be read the wrong way round. The Contract end date can't be before the Contract start date.
Invalid bank account number: Heartsome checks that the IBAN is valid. A typo or a missing digit gives an error.
"The file contains no data rows": there's nothing below the column headers. Check that you saved the right sheet.

Good to know

• Manager: use the Manager email column where you can. It also works when the manager is in the same file. The Manager name column only works for managers who are already in Heartsome. If Heartsome can't find the manager, Reports to stays empty. Fill it in later via Setting the team, manager and work location.
• Teams: put several teams in one cell, separated by commas ("Sales, Marketing"). If a team doesn't exist yet, Heartsome creates it. So watch the spelling, or you'll end up with "Marketing" and "Marketng" side by side.
• No start date? The contract then starts today. Fill in the real start date if you know it: it counts towards things like work anniversaries and time off.
• No salary currency? It's set to EUR.
• No language? The colleague gets the same language as you.
• Stepped away? Heartsome remembers where you were. Open Import via sheet again and you'll pick up at the step you left.
• Each import creates a first contract per colleague. How to change contracts later is explained in Recording and changing contracts.
• No onboarding: imported colleagues don't get an onboarding checklist. If you do want one, add the colleague with Add single colleague instead.

Who can do this?

Only HR admins and the account owner can import colleagues.

Updated on: 21/10/2026