Importing Employees
Bulk-import employees from a CSV template to onboard your team quickly
If you have more than a handful of employees to add, use the Import function instead of creating profiles one by one. You download a template, fill it in with your employee data, and upload it. Hopshift validates each row and creates the profiles in bulk.
Before You Start
Make sure the following exist in Hopshift before importing, as the template references them by name:
- Companies: each employee row must match an exact company name in your group
- Departments: must exist in Settings → Departments
- Positions: must exist in Settings → Positions
If a row references a department or position that does not exist, it will fail validation.
Step 1: Download the Template
- Go to Group → Employees.
- Click Import (top-right, next to Add Employee).
- Click Download Template.
The template is a .xlsx file with one header row and column descriptions in row 2. Delete row 2 before uploading: it is for guidance only.
Template Columns
| Column | Required | Notes |
|---|---|---|
first_name | Yes | Legal first name in English |
last_name | Yes | Legal last name in English |
first_name_th | No | First name in Thai script |
last_name_th | No | Last name in Thai script |
email | Yes | Must be unique across the company |
employee_id | No | Your internal HR code (e.g. EMP001) |
hire_date | Yes | Format: YYYY-MM-DD (e.g. 2024-03-15) |
employment_type | Yes | One of: full-time, part-time, contract, intern |
company | Yes | Exact company name as it appears in Hopshift |
department | Yes | Must match an existing department name |
position | No | Must match an existing position name |
monthly_salary | No | Numeric, no currency symbol (e.g. 35000) |
pay_type | No | One of: salary, hourly, daily. Defaults to salary |
national_id | No | 13-digit Thai national ID. Required for TH payroll |
birthday | No | Format: YYYY-MM-DD. Required for TH payroll |
gender | No | One of: male, female, other. Required for TH payroll |
phone | No | International format recommended (e.g. +66812345678) |
send_invite | No | true or false. Defaults to true |
For Thai companies, filling in national_id, birthday, and gender at import time is strongly recommended. Employees missing these fields will be blocked from payroll finalization and will need to be updated individually afterwards.
Step 2: Fill in the Template
Fill one employee per row. A few tips:
- Dates must be in
YYYY-MM-DDformat. Excel may reformat dates automatically: check the cell format is set to Text or that dates display as2024-03-15not15/03/2024. - Company, department, and position values must match exactly (case-insensitive). A value of
kitchenwill match a department namedKitchen. - Emails must be unique. If an email already exists in the system, that row will fail.
- Leave optional columns blank: do not delete the column headers.
Step 3: Upload and Validate
- Go back to Group → Employees → Import.
- Click Upload File and select your completed template.
- Hopshift validates every row before importing anything.
The validation screen shows:
- Valid rows: ready to import (shown in green)
- Rows with errors: shown in red with a description of each error
Common errors:
| Error | Fix |
|---|---|
Email already exists | The email is already registered: skip or update the existing profile |
Department not found | Create the department in Settings first, or correct the spelling |
Invalid date format | Change the cell to text format and re-enter as YYYY-MM-DD |
Invalid employment_type | Use one of the accepted values exactly |
Step 4: Confirm Import
Once you are satisfied with the validation results:
- If there are errors you want to skip: check Import valid rows only. Invalid rows will be skipped.
- If you want to fix all errors first: click Cancel, correct the file, and re-upload.
- Click Import to proceed.
Hopshift creates all valid employee profiles immediately. If send_invite is true, each employee receives a welcome email with a link to set their password.
After Import
Once the import completes, you will see a summary:
- Number of employees created
- Number of rows skipped (with reasons)
Go to Group → Employees to verify the imported records. For Thai employees, confirm that national_id, birthday, and gender are filled before running payroll.
If you need to update existing employees in bulk (e.g. change salaries or departments), use the Export function to download current data, make changes, and re-upload. The system matches rows by email address and updates existing records rather than creating duplicates.
Related
- Adding an Employee: add employees one at a time
- Employee Management: manage profiles after import