Data Import
This guide covers the technical details of Luna HR's CSV import — field specifications, mapping rules, and how to handle common issues.
For a general overview, see Importing Data.
Data Import is the one spreadsheet route for people — existing staff and new starters alike. (Admin > Onboarding has no separate CSV upload; its Import a spreadsheet link opens the employee import here.)
Import process
- Select data type — org structure, employees, leave, expenses, assets, or training
- Upload CSV — drag and drop or click to browse
- Map columns — match your CSV headers to Luna HR fields
- Preview — review each row with validation feedback
- Import — create the records
Import order
Some imports depend on others. The wizard lists them in the order they should be run:
- Org structure — offices, departments, teams
- Employees — references roles and org nodes
- Leave, expenses, training — reference employees
- Assets — independent, but assignment references employees
Field specifications
Org structure fields
| Field | Required | Format | Notes | |-------|----------|--------|-------| | Name | Yes | Text | | | Type | Yes | Text | company, region, office, division, department, team, cost_centre, project, custom | | Parent | No | Text | Name of the parent node. May be another row of the same file — parents are created before their children regardless of row order. Unresolvable parents attach to the company root and are reported | | Code | No | Text | | | Description | No | Text | |
A node is a duplicate only if a node with the same name and type already exists under the same parent — so a "Support" team in each office is fine.
Employee fields
Only first name, last name and email are required. Every other column in the table below is filled in for you when the file leaves it out or a cell is blank — the mapping screen lists what is filled in before you upload, and the preview shows what each row will get.
| Field | Required | Format | Notes |
|-------|----------|--------|-------|
| First name | Yes | Text | |
| Last name | Yes | Text | |
| Email | Yes | Email | Must be unique within the company. Stored lower-cased — this is the address the employee signs in with |
| Employee # | No — generated on import | Text | A blank cell gets the next free EMP-number. A number you give must be unique within the company, ignoring capitals and spaces; the preview checks it against existing employees as well as the file — your own record is usually EMP-001 |
| Start date | No — today, marked as not yet known | Date | YYYY-MM-DD or DD/MM/YYYY. A blank start date is stored as the import day but never quoted to the person (invite emails and the onboarding wizard leave it out) until you set the real one. A row with an end date in the past needs a start date |
| Role | No — the standard Employee role | Text | Must match an existing permission role name. Not auto-matched from a "Job Title" column — see below. A blank cell gets the role Add Employee starts with (code EMP); if your company has none, the row asks you to add a Role column |
| Status | No — default active | Text | active, inactive, onboarding, leaver, suspended. "active" is stored as "invited" until the employee creates their login. See Statuses below |
| Employment type | No — default full-time | Text | full-time, part-time, contractor, intern |
| Contract type | No — default permanent | Text | permanent, fixed-term, casual |
| FTE | No — default 1.0 | Number | Between 0 and 1 |
| Job title | No | Text | Display label only. Created on the fly if it doesn't exist yet |
| Department | No | Text | Must match an existing org node name. If two nodes share the name, write the place in the tree, e.g. London > Sales — see below |
| Line manager | No | Text | Match by email or full name |
| Working pattern | No | Text | Must match an existing pattern name |
| End date | No (required for a leaver) | Date | Must not be before the start date |
| Payroll reference | No | Text | |
| Emergency contact name / phone / relationship | No | Text | A contact record is created when both a name and a phone are present |
| NI number, address, demographics | No | Text | See the mapping step for the full list |
Role vs Job title. Role is the permission tier and decides what the
person can do in Luna; Job title is the label shown on their profile. A
"Job Title" column is deliberately not auto-mapped onto Role — mapping it
there would grant permissions from a spreadsheet label. Map both explicitly if
your export has one column serving both purposes.
Roles that grant more than employee access. If any row would get a role that carries permissions — Administrator, HR Manager, Accounts, or a role of your own with permissions — the preview lists each such role with how many people get it and their names, and the import waits until you tick the box to say you mean it. The seeded Employee role grants nothing and needs no confirmation.
Names two records share. Department, role and working pattern are matched
by name. When more than one matches — say a "Sales" team under London and
another under Manchester — the row is an error that names the candidates
instead of quietly picking one. For a department, write the place in the tree:
London > Sales (the company name may be included at the front). For a role or
working pattern, rename one of them first.
Statuses
- offboarding cannot be imported: such a person would have no offboarding
to finish. Import them as
active, then start offboarding in Luna. - leaver can be imported (bringing over history), but needs an End date.
inactive,suspendedandleaverpeople are not billable and are not offered an invite.
Leave fields
| Field | Required | Format | Notes | |-------|----------|--------|-------| | Employee | Yes | Text | Match by email or full name | | Leave type | Yes | Text | Must match an existing leave type | | Start date | Yes | Date | | | End date | Yes | Date | | | Days | Yes | Number | Must be greater than 0 | | Status | Yes | Text | approved, pending, rejected, cancelled, taken, draft | | Notes | No | Text | |
The end date must not be before the start date. Approved and taken leave
adjusts the employee's taken / booked counters; pending leave is reserved
against pending. Entitlement itself always comes from the resolved leave
policy — the import never sets it.
Expense fields
| Field | Required | Format | Notes | |-------|----------|--------|-------| | Employee | Yes | Text | Match by email or full name | | Expense date | Yes | Date | | | Category | Yes | Text | Must match an existing expense category | | Amount | Yes | Number | Currency symbols and commas are stripped automatically | | Status | Yes | Text | draft, submitted, approved, rejected, paid | | Report title | No | Text | Items with same employee + title are grouped into one report | | Description | No | Text | | | Currency | No | Text | Defaults to GBP | | Tax rate | No | Number | Percentage (e.g. 20 for 20%) | | Payment reference | No | Text | | | Payment method | No | Text | bank_transfer, payroll, petty_cash |
Asset fields
| Field | Required | Format | Notes | |-------|----------|--------|-------| | Name | Yes | Text | | | Asset tag | Yes | Text | Must be unique | | Category | Yes | Text | Must match an existing asset category | | Status | Yes | Text | available, assigned, maintenance, retired, disposed | | Condition | Yes | Text | new, good, fair, poor | | Serial number | No | Text | | | Manufacturer | No | Text | | | Model | No | Text | | | Assigned to | No | Text | Match by email or full name | | Purchase date | No | Date | | | Purchase cost | No | Number | | | Warranty expiry | No | Date | |
Training fields
| Field | Required | Format | Notes | |-------|----------|--------|-------| | Employee | Yes | Text | Match by email or full name | | Course name | Yes | Text | Must match an existing course, or create one from the preview step | | Completion date | Yes | Date | | | Status | Yes | Text | passed, failed, incomplete | | Duration (hours) | Yes | Number | | | Provider, course code, valid from/until, cost, score, certificate # | No | | See the mapping step |
Common source-system wordings are translated: "completed" and "pass" become
passed, "in progress" and "not started" become incomplete. Anything else is
reported so you can map it explicitly rather than have it guessed at.
Column matching
Luna HR automatically matches common column header names. For example:
- "Staff Name", "Employee Name", "Name" → Employee
- "Date", "Receipt Date", "Transaction Date" → Expense Date
- "Cost", "Total", "Value", "Price" → Amount
Matching is exact-alias first, then a fuzzy pass restricted to aliases of five or more characters, so short generic tokens ("type", "name", "mail") can't hijack a longer header.
If auto-matching doesn't find the right column, set the mapping yourself in the mapping step. Two columns cannot point at the same Luna field — only one would be imported, so the wizard blocks until you skip the extras.
Validation
Before importing, every row is validated:
- Errors (red) — must be fixed before import. Examples: required field missing, employee not found, duplicate email or employee number (in the file or already in Luna), a name that matches more than one department, role or working pattern, a value outside the allowed list for that column, an end date before its start date, a leaver with no end date
- Warnings (amber) — can proceed but may need attention. Example: a line manager who isn't in Luna yet (the link can be made later)
Rows the import would skip are errors, not warnings, so the count on the "Import N records" button is the number you actually get.
You can edit rows inline in the preview to fix issues without going back to your CSV. Going Back to the mapping step keeps your file, your mapping and those fixes; uploading a different file or changing the mapping clears the fixes.
On an employee import the preview also says when the people in the file are billable seats: on a paid plan, how many seats your subscription goes to; on the free plan, when the import takes your team past the free allowance (which gives you seven days to set up billing).
Results
Rows are sent in batches of 50. The result screen says how many records were imported and lists every skipped row — its row number, address and the reason. If a whole batch fails, the batches before it stay imported and the rest are never tried: the heading then reads Import stopped early and says how many rows were never attempted. Upload the same file again to finish — rows already imported show as existing in the preview and are left out. An import that created nothing says Nothing was imported.
After an employee import
The import emails nobody. Its last step asks what these people should receive: nothing for now, a login invite, or the onboarding wizard (the same invite dialog as on the Employees page). Only people who can be invited are offered — not leavers, inactive or suspended people. For new starters, choose the onboarding wizard: each person is sent the wizard invite, to complete before their first day.
Luna sends at most 500 invitation emails a day per company, counting every login invite, onboarding invite and resend. A request for more than what is left today is refused as a whole, so an import of more than 500 people offers the first 500; invite the rest from Employees the next day.
Tips
- Create categories first — expense categories, asset categories, and leave types must exist before you import data that references them
- Match employee names — the import resolves employees by email first, then full name. Ensure your CSV uses the same names as Luna HR
- Test small — import 10-20 rows first to verify your column mapping
- Dates — YYYY-MM-DD is preferred. DD/MM/YYYY also works and is read day first, so a US-style
06/15/2024is rejected rather than misread. Impossible dates (31 February) are rejected too - Quoted fields — commas, quotes, and line breaks inside a quoted field are handled, so multi-line addresses import intact
- Amounts — currency symbols (GBP, $, EUR) and thousand separators (commas) are handled automatically
Related
- Importing Data — overview of the import process
- Employee Management — managing employees after import