Importing a 18-User Roster CSV into Time Tracker: A Step-by-Step Guide
By Jordan Ellis Published 11 min read
On this page (8 sections)
In short: Most CSV imports fail because of one thing: dirty source data, not the software. Clean your 18 rows first, match each CSV column to the right tracker field, run the import in test mode if it offers one, then confirm all 18 users appear before anyone clocks in.
Part of our guide on tracking billable vs non-billable tasks
An 18-person roster imports in under two minutes; fixing a botched one costs an afternoon and a payroll argument.
| Roster size | 18 user rows plus a header |
|---|---|
| File format | CSV, UTF-8 encoded |
| Key field | unique email per employee |
| Typical import time | under 2 minutes |
| Rate format | decimal, no currency symbols |
| Dry run first | yes, whenever offered |
The short version
- Save the file as plain CSV, not Excel .xlsx; the importer usually rejects anything else.
- Email addresses must be unique and correctly spelled; they are the match key for every user.
- Map employee ID, name, email, department and hourly rate one column at a time.
- Delete duplicate rows before importing; the tool will not decide which one is right for you.
- Import to a test project or sandbox first, then check the roster shows exactly 18 active users.
What a roster CSV import actually does
An employee roster CSV import into time tracker software takes a spreadsheet of your staff and turns each row into a user account. Do it right and your 18 employees can clock in the same day. Do it wrong and you spend a week patching half-created accounts.
The importer reads a plain text file where commas separate fields. Row one is usually treated as headers, rows two onward as people. Every field it cannot match to a tracker column is either ignored or rejected, depending on the tool, so the file has to be shaped for the importer, not for you.
At 18 users you have a choice the 200-user crowd does not. You could enter people by hand in about 40 minutes. The import is still worth it, because a spreadsheet gives you a clean record of who was added, when, and with what rate. That record is what settles payroll disputes later.
One warning before you start. Some trackers treat an import as irreversible and charge per seat once accounts exist. Check whether deleting a bad import actually removes the seats or just deactivates them. That detail changes how bold you can be on the first attempt. People in this spot often ask about tracking new hire performance as well.
Preparing the CSV file before you import
Start from your payroll or HR export if you have one. It already holds names, emails and often employee IDs. If you are typing the roster by hand, build it with these columns at minimum: employee ID, first name, last name, email, department, and hourly rate if the tracker handles pay rates.
Save as CSV, UTF-8 encoded. Excel's default save usually produces this if you pick 'CSV (Comma delimited)' from the file type list. Do not save as .xlsx; most importers reject it outright. Avoid commas inside names like 'Smith, Jr' because they split into extra fields. Write Smith Jr instead.
Check the dates and numbers next. Hourly rates should be plain decimals such as 22.50, with no dollar signs or commas. Time formats, if your file has any, should match whatever the tracker uses, usually 24-hour. A rate entered as '$22.50' is the single most common import rejection I see at this size. If that sounds like your situation, read up on improving budget accuracy with tracking next.
Then count your rows. You want exactly 18 data rows under one header row. Blank rows mid-file cause 'empty record' errors, and a stray row 20 where someone pasted an old leaver causes a user nobody expected. Delete blank rows, delete leavers, save, count again.
- File type: saved as .csv, not .xlsx or .ods.
- Header row: exactly one, at the top, no blank row under it.
- Emails: all lowercase, no spaces, no duplicates.
- Rates: plain numbers, decimal point, no currency symbols.
- Names: no commas, no trailing spaces, consistent spelling.
A quick cleaning checklist
Run through this before the file goes anywhere near the importer. Two minutes here saves an hour of error messages.
Each check takes seconds at 18 rows. That is the advantage of a small roster; you can genuinely eyeball every line. The other half of this decision is managing 18 hourly staff shifts.
Mapping CSV fields to the time tracker columns
Field mapping is where the importer asks which CSV column feeds which tracker field. Most tools show two lists side by side: your headers on the left, their fields on the right. You match them one at a time. Email is the critical one, because it is the unique key the tracker uses to tell people apart and to spot duplicates.
Map employee ID to whatever the tracker calls a staff number or external ID. This matters more than it looks. If you ever re-import an updated roster, the ID lets the tool update existing people instead of creating doubles. Name fields usually map to first name and last name separately; if your file has one full-name column, split it first.
Department and rate mappings are optional in most tools but worth doing now. A rate mapped at import means timesheets cost out correctly from day one, which is the difference between a tracker and a project-budget tool. Leaving rates blank means every report shows zero costs until someone fills them in by hand.
Preview before you commit. Nearly every importer shows a sample of mapped rows before the final run. Read all the preview rows you can see, not just the first one. Errors cluster at the bottom of alphabetically sorted files, where the Zs and the odd formatting live.
| CSV column | Tracker field | Required? | Watch out for |
|---|---|---|---|
| employee_id | Staff / external ID | Recommended | Must stay unique across re-imports |
| Email / username | Yes | Duplicates and typos break the import | |
| first_name | First name | Yes | Trailing spaces |
| last_name | Last name | Yes | Commas in suffixes |
| department | Team or department | Optional | Spelling must match existing teams |
| hourly_rate | Pay rate | Optional | No $ sign, decimal point only |
Handling duplicate and missing employee data
Duplicates are the failure mode at this roster size. Two rows with the same email, or one employee listed under both a nickname and a legal name, will either split one person into two accounts or fail outright. Sort the file by email column and scan it; at 18 rows that takes under a minute and catches most of it.
Decide your rule before the import: email is the identity, and everything else can be fixed later. If someone has no company email, generate a consistent pattern such as firstname.lastname@yourdomain, and record it. An invented but consistent email beats a blank cell, because a blank email usually fails the row or creates an account nobody can log into.
Missing data is less dangerous than wrong data. A blank department imports fine and can be filled in later through the user screen. A wrong rate imports silently and corrupts every cost report until someone notices. So treat blanks as acceptable and wrong values as blockers, and double-check the rate column row by row.
Leavers deserve a mention. If your source export includes people who have left, remove them now rather than importing and deactivating. Some trackers still count a deactivated imported user against your seat total, and at 18 seats on a paid plan that is money for nobody.
Running and validating the import for 18 employees
Run the import in test or dry-run mode if the tool offers one. Most mid-range trackers do, and it processes the file without creating accounts, reporting what would happen. Read the summary line: it should say 18 created or 18 valid, with zero errors. Anything else, stop and fix before the real run.
If there is no dry-run option, import one person first. Delete all but one row, import, check the account looks right in the user list, then import the remaining 17. It feels slow. It takes ten minutes and it proves your mapping before 17 accounts depend on it.
Validation after the real import is four checks. Count the active users; it must read exactly 18. Spot-check two or three accounts against your source file: name spelling, department, rate. Log in as one test user, or trigger a password reset for one, and confirm the account actually works. Then run one dummy clock-in and check it lands on a timesheet.
Export the roster back out. Import your CSV, then export the tracker's own user list and compare the two side by side. Where they differ, the tracker changed something, and you want to know now, not during the first payroll run. Keep both files; they are your audit trail if a timesheet is ever disputed.
- Upload the cleaned CSV and confirm the file was read as 18 rows plus headers.
- Map each column, with email as the identity field.
- Run dry-run or single-user test import and read the result summary.
- Run the full import and check the user count reads exactly 18.
- Spot-check names, departments and rates against your source file.
- Trigger one password reset and one test clock-in to prove accounts work.
- Export the roster back out and compare it to your original CSV.
Troubleshooting common import errors
Most errors name the row number, so work top to bottom and fix them in the spreadsheet, then re-upload the whole file. Don't patch individual accounts inside the tracker; that guarantees your source file and the live roster drift apart.
'Invalid email' on specific rows means a space before or after the address, a missing @, or a stray comma from a name earlier in the row shifting everything left. That last one is sneaky: one bad comma in row 3 breaks every field after it, and the error shows on row 3's email even though the name is the culprit.
'Duplicate user' means the email already exists, either twice in your file or once in the file and once already in the tracker from a manual entry. Search the tracker's user list for the address before assuming the file is at fault. During a trial-to-paid migration this is the most common cause by far.
Encoding errors, shown as strange characters in names, mean the file saved in the wrong character set. Re-save as UTF-8. Names like José or Zoë break first, so check the rows where they appear. Nothing else in the file is usually wrong; the importer just read the accents as gibberish.
| Error message | Real cause | Fix |
|---|---|---|
| Invalid email format | Space, missing @, or shifted fields from an earlier comma | Clean emails, remove commas from names |
| Duplicate user found | Same email twice in file, or already in tracker | Sort by email, dedupe, search tracker first |
| Unrecognized file type | Saved as .xlsx or with wrong extension | Re-save as CSV, comma delimited |
| Row skipped: empty | Blank row in the middle of the file | Delete blank rows, re-count |
| Garbled characters in names | File not saved as UTF-8 | Re-save with UTF-8 encoding |
| Invalid number in rate | Currency symbol or thousands comma | Plain decimals only, e.g. 22.50 |
- Fixes the root cause in one file
- Source CSV stays the single source of truth
- Re-imports get faster each time
- Full re-upload needed per fix round
- Some tools limit re-import attempts per day
A clean CSV import is worth the prep time even at 18 users, because the spreadsheet doubles as your payroll audit trail.
Questions people still ask
Can I import the roster without an email address for each employee?
Rarely. Email is the unique key nearly every tracker uses to identify users, so blank emails either fail the row or create logins nobody can use. If someone has no company email, create a consistent pattern like firstname.lastname@yourdomain and use it for everyone in the same situation.
What happens if I import the same CSV twice?
It depends on whether the tool matches on email or employee ID. With IDs mapped, a re-import usually updates existing records. Without them, you risk 18 duplicate accounts. Always check the tool's behaviour on a one-row test file before re-importing the full roster.
Should I import hourly rates during the roster import?
Yes, if your tracker uses rates for cost reporting. A rate mapped at import means project budgets and payroll estimates are correct from the first timesheet. Leave it out only if rates change often and you manage them elsewhere.
How long should an import of 18 users take?
The import itself runs in seconds. Preparing and checking the file is the real work: about 20 to 40 minutes for a clean payroll export, longer if you're typing from paper. Budget half a morning including validation and a test clock-in.
Can I add employees later without re-importing everything?
Yes. Add them one at a time through the user screen, or import a small CSV containing only the new rows. If you use employee IDs, a later full re-import will update rather than duplicate, which is why mapping the ID field matters.
Why do accented characters in names look wrong after import?
The file was saved in a character set other than UTF-8, so the importer misreads accented letters. Re-save the CSV with UTF-8 encoding and import again. This affects José, Zoë and similar names first, so check those rows specifically.