Bulk Import Employees from CSV
When you need to onboard many employees at once, you can upload a CSV file instead of adding each person by hand. The importer always shows you a preview of exactly what will happen before anything is saved, and every import can be rolled back afterwards.
To open the importer, visit the Employee Management page and click the Import from CSV button (next to Add Employee), or go straight to the Import Employees page.
Prepare your CSV file
The first row of the file must be a header row naming the columns. Column order does not matter, but the names must match exactly.
Required columns
| Column | Description |
|---|---|
name | The employee’s name. |
email | The employee’s primary email — used to sign in and receive notifications. |
Optional columns
| Column | Description |
|---|---|
employee_number | Your own reference/payroll number for the employee. |
department | The employee’s department. |
secondary_emails | Additional sign-in emails. |
access_codes | KioskForce Access Codes to assign to the employee. |
key_cards | Key card numbers to assign to the employee. |
tags | Tag UUIDs to apply to the employee. |
employee_group_uuid | The UUID of an employee group to add the employee to (takes precedence over the name). |
employee_group_name | The exact name of an employee group to add the employee to. Must match exactly one group, otherwise the row is flagged as an error. |
Notes:
- Multi-value columns (
secondary_emails,access_codes,key_cards,tags) can hold several values in one cell — separate them with a semicolon (;), for examplealex@work.com;alex@home.com. - Unknown columns are rejected. If the file contains a column the importer does not recognise, the whole file is refused so that data you expected to import is never silently dropped. Fix the header and re-upload.
- Up to 5,000 rows per file. Split larger lists into multiple files.
The quickest way to get the format right is to click Download CSV template on the upload screen and fill it in.
Step 1 — Upload and preview
- Choose your CSV file and click Preview.
-
The importer parses and checks the file without writing anything and shows a table where every row is marked with one of three statuses:
Badge Meaning Insert The row is valid and will create a new employee. Conflict The email already belongs to an existing employee. Error The row is invalid — e.g. missing name, malformed email, a duplicate email within the file, a key card or access code that is already assigned (or repeated in the file), or an employee group that can’t be matched. A summary above the table shows the totals (rows, to insert, conflicts, errors), and you can filter the table by status.
Step 2 — Import
What you can do next depends on what the preview found:
- All rows valid (no conflicts, no errors). A single Import N employees button runs the import.
- There are conflicts. You choose how to handle them:
- Import (reject if conflicts) — abort the whole import if any row conflicts. Nothing is written. Use this when conflicts mean the file is wrong and you want to fix it first.
- Import & skip conflicts — insert the valid rows and silently skip the conflicting ones. The skipped count is recorded on the batch.
- There are validation errors. Import is blocked until you fix the highlighted rows and re-upload. Validation errors always stop the import, regardless of the conflict choice.
The import runs as a single all-or-nothing operation: if anything unexpected happens midway, the entire batch is undone, so you never end up with a half-finished import. When it succeeds you see a confirmation with the number of employees inserted (and skipped, if any).
Import history and rollback
Every import is recorded. Open the Import History page (the Import History link on the importer, or Import from CSV → Import History) to see past imports with their file name, row counts, strategy and status.
To undo an import, click Rollback on its row and confirm. Rollback soft-deletes every employee that import created — the employees are removed from your active roster (their records are retained for reporting). Rollback only affects employees created by that import; it cannot be undone from here, and a batch can only be rolled back once.