Bulk-Importing Leave Balances from CSV: Migration Without the Mess

Migrating from spreadsheets to leave management software usually means one painful step: getting existing leave balances into the new system. If you have 50 employees with carryover balances from last year, manual entry is slow. If you have 500 employees, it is practically impossible. CSV import solves this by letting you upload a spreadsheet and have Leave Balance process every record in one batch.

The Leave Balance CSV import handles employee records, leave balances, and policy assignments in a single upload. It validates each row, reports errors before committing changes, and lets you preview the import before it goes live.

Key Takeaways

• The CSV import processes employee records, leave balances, and policy assignments in one upload
• Validation runs before the import commits, so errors are caught before data goes live
• You can preview the import and rollback if something goes wrong

Why CSV Import Matters for Leave Management

When a business moves from spreadsheets to leave management software, the first question is always “what about our existing data?” The answers are usually:

• Current leave balances that employees have accrued
• Policy assignments (who is on which leave policy)
• Employee records that may not be in the new system yet

Without CSV import, each of these must be entered manually. For a 100-person company, that is hundreds of data points. For a 1,000-person company, it is a project.

CSV import turns this from a multi-day project into a single upload. The spreadsheet you already have — the one tracking balances in Excel or Google Sheets — becomes the source for the migration. You do not need to reformat your data into a custom tool or hire a consultant. You prepare the CSV, upload it, and Leave Balance handles the rest.

How to Import Leave Balances via CSV

Step 1: Download the CSV Template

From your Leave Balance account, navigate to Settings > Import > Leave Balances and click “Download Template.” The template includes the correct column headers and sample data.

The template columns are:

Column	Required	Description
employee_id	Yes	Unique identifier for the employee
first_name	Yes	Employee first name
last_name	Yes	Employee last name
email	Yes	Employee email address
leave_type	Yes	Leave type (e.g., annual, sick, personal)
balance_days	Yes	Current balance in days
accrued_days	No	Days accrued this period
carryover_days	No	Days carried over from previous year
policy_name	No	Leave policy to assign
department	No	Employee department

Step 2: Prepare Your Data

Fill in the template with your existing data. Key preparation steps:

1. Standardise leave type names. If your spreadsheet uses “Annual” and the template expects “annual”, normalise the column before uploading.
2. Verify employee emails. The email column must match the email you will use for employee login. Duplicate emails cause import errors.
3. Check numeric columns. Balance days, accrued days, and carryover days must be numbers, not text. A balance of “5.00” is fine; “5 days” will fail validation.
4. Remove blank rows. Empty rows between data rows cause validation errors.

Step 3: Upload the CSV

In Leave Balance, go to Settings > Import > Leave Balances and drag your CSV file into the upload area, or click to browse for the file.

Leave Balance will:

1. Parse the file and check for formatting errors
2. Validate each row against the database (existing employee emails, valid leave types)
3. Display a preview of the import with row-by-row status

Step 4: Review the Validation Report

The validation report shows three categories:

Status	Meaning	Action
Ready to import	Row passes all checks	No action needed
Warning	Row has minor issues (e.g., missing optional fields)	Review and decide whether to fix or proceed
Error	Row has issues that prevent import (e.g., duplicate email, invalid leave type)	Fix the row and re-upload

Common errors include:

• Duplicate employee_id or email in the CSV
• leave_type that does not match a configured type in Leave Balance
• balance_days that is negative or exceeds the annual entitlement
• Missing required fields (employee_id, email, leave_type)

Step 5: Confirm and Import

After reviewing the validation report, click “Import” to commit the changes. Leave Balance processes the import in the background. For large files (500+ rows), this may take a few minutes.

You receive an email confirmation when the import is complete, along with a summary of records imported, warnings, and errors.

Step 6: Verify the Import

After import, spot-check a few records:

1. Open an employee profile and confirm the balance matches your spreadsheet
2. Check the leave policy assignment is correct
3. Review the import history in Settings > Import > History for any rows that were skipped

What Data Can Be Imported

Data Type	CSV Import	API	Manual Entry
Employee records	Yes	Yes	Yes
Leave balances	Yes	Yes	Yes
Policy assignments	Yes	Yes	Yes
Leave history	Yes (separate template)	Yes	No
Accrual rules	No (configured in-app)	Yes	Yes

Best Practices

• Import employees first, then balances. Leave Balance can create employee records during import, but it is cleaner to import employees in a separate step and then import balances. This makes error tracking easier.
• Use a staging environment if available. Import into a test workspace first to catch issues before committing to production.
• Back up your spreadsheet. Keep a copy of the original CSV after import. If you need to roll back or re-import, you have the source data.
• Import during off-hours. Large imports can take a few minutes. Run them outside business hours to avoid any temporary slowdowns for your team.
• Schedule recurring imports if needed. If your employee data comes from an HRIS that exports CSVs, you can schedule regular imports through the API instead of manual uploads.

FAQ

What is the maximum CSV file size?

The CSV import supports up to 10,000 rows per file. For larger datasets, split the file into multiple uploads. Leave Balance processes each upload independently.

Can I import leave history (past approved leave)?

Yes. Leave Balance has a separate CSV template for leave history. This imports past approved leave requests so that employee records show a complete leave history from the date of import.

What if an employee already exists in Leave Balance?

The import matches employees by email address. If an employee already exists, the import updates their balance and policy assignment. It does not create a duplicate record.

Can I undo an import?

You can reverse an import by navigating to Settings > Import > History and clicking “Rollback” on the import batch. This removes all records created or modified by that import.

Does the import trigger notifications?

No. CSV imports do not trigger individual notifications to employees. Only the admin who runs the import receives a confirmation email. If you want employees to see their updated balances, publish a company-wide announcement after import.