Skip to main content

​
Bulk import employees

Use this guide when migrating or onboarding many employees from an HRIS or spreadsheet. Fluide HR provides a template endpoint and bulk import route.

​
Prerequisites

  • API credentials and hr:employees:write
  • Partner acting-client headers when scoping to a merchant
  • Spreadsheet filled per the template column definitions

​
Steps

1

Download the import template

curl -sS "$FLUIDE_BASE_URL/api/v1/hr/employees/import-template" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID" \
  -o employees-template.xlsx
Open the template and fill required columns. Do not rename header rows.
2

Upload the completed file

curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/hr/employees/import" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID" \
  -F "file=@employees-filled.xlsx"
The response includes per-row success and error details. Fix validation errors and re-upload failed rows if needed.
3

Verify and sync to Payroll

List employees to confirm counts, then check Payroll mirror — HR → Payroll.
curl -sS "$FLUIDE_BASE_URL/api/v1/hr/employees?limit=1" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID"

​
Tips

  • Run a small test file (5–10 rows) in sandbox before a full production import.
  • employeeCode must be unique per company — dedupe your source data first.
  • Large imports may take time; Payroll mirrors each employee as HR processes rows.

​
Troubleshooting

ProblemResolution
Row rejected — invalid emailFix format in spreadsheet; partial import still commits valid rows.
Template download emptyConfirm acting-client headers match the target company.
Payroll count lower than HRMirror is per-row async — allow a few minutes or see playbook troubleshooting.

Add an employee

Single-employee create flow.

HR API reference

Import endpoint schema and field definitions.