How do I import employees from a file?
An import is the route for many employees at once — setting Velory up, or moving off a spreadsheet. It can also start a configured onboarding for each hire in the file, which is what makes it worth using for a joining cohort rather than just a backfill.
In this guide
Before you begin
You need Admin access. Your file needs at least an email, a first name and a last name per row.
Import employees
- Go to Employees → Employees.
- Click Add Employee → Import from file.
- Upload the file. CSV, XLSX, XML and JSON are accepted, up to 10 MB.
- Map your columns to Velory's fields. Velory proposes a mapping; correct anything it got wrong.
- Review the result. Rows with problems are flagged here.
- Import.
Up to 5,000 rows per import. Split a larger file.
The upload step offers a template so you can see the expected column names before building the file.
If your company has an import-filter workflow configured, the stepper shows it as an extra stage before the import: it can accept or reject each candidate row before any record is created, and it reports how many it admitted and dropped.
Supported fields
| Field | Required | Description |
|---|---|---|
| Yes | Work email — the primary identifier | |
| first_name | Yes | |
| last_name | Yes | |
| employee_id | No | Your internal employee identifier |
| department | No | |
| job_title | No | |
| phone | No | Work phone number |
| location | No | Office location or city |
| work_location | No | Onsite or remote. Decides where they return devices. Accepts onsite/office/on-site or remote/offsite/home/wfh |
| office | No | The office they work from. Must match a Delivery & Return address, matched case-insensitively; an unmatched name is skipped with a warning |
| start_date | No | YYYY-MM-DD |
| manager_email | No | Links the reporting relationship by email |
| tags | No | Existing tag names, comma- or semicolon-separated |
Onboarding columns
These four start and configure an onboarding per row:
| Field | Description |
|---|---|
| trigger_onboarding | yes creates an onboarding for this hire. By default it waits on the confirm step for an admin |
| auto_trigger | yes starts it immediately. Needs a start date on the same row |
| invite_mode | now, scheduled or manual. Defaults to now |
| invite_scheduled_at | YYYY-MM-DD. Required when invite_mode is scheduled |
The review step turns these into real controls — a toggle and an invite selector — and blocks any row whose onboarding is incomplete until you fix it. See How do I start an onboarding?.
How duplicates are handled
Every row is matched against the employees you already have. Velory scores the match and acts on the score:
| Signal | Confidence |
|---|---|
| Email — checked against both work and personal email | 100% |
| Personal email — same, both ways | 100% |
| Employee number | 95% |
| Employee ID | 95% |
| External ID | 90% |
| First and last name, fuzzily | 50% |
- 90% and above — merged into the existing person automatically.
- 50% to 89% — held for you to confirm or skip. This is where a name-only match lands, which is the right place for it.
- Below 50% — treated as a new person and created.
Because email is matched against both address fields in both directions, someone whose record was created from a private address is still recognised when you import their work address.
What happens after the import
- New employees appear on the Employees list.
- Updated records show their changes at once.
- Each imported person's Activity tab records the import.
- A summary reports how many were created, updated and skipped.
Good to know
Which file format should I use?
Whatever you already have. CSV and XLSX are the usual ones; for CSV, use commas and UTF-8 so accented names survive.
Can I update existing employees by importing?
Yes. That is what the matching is for — a file with an email column updates rather than duplicates.
What about manager relationships?
A manager_email column resolves to an existing person. The manager has to exist already, or be somewhere in the same file.
What happens to tag names I made up?
They are skipped with a warning. Importing never creates a tag, so a typo silently drops rather than polluting your tag list. Matching ignores case.
Will imported employees be invited?
Only if you used the onboarding columns. Otherwise an import creates records and nothing else — use Start onboarding, singly or in bulk, afterwards.
Was this article helpful?