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

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.

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.

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

Problem	Resolution
Row rejected — invalid email	Fix format in spreadsheet; partial import still commits valid rows.
Template download empty	Confirm acting-client headers match the target company.
Payroll count lower than HR	Mirror 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.

Overview

Service partner

HR & People

HR Operations

Payroll

Pay

Books

Access & Auth

Utils

Playbooks

Bulk import employees

Bulk import employees

Prerequisites

Steps

Tips

Troubleshooting

Add an employee

HR API reference

​Bulk import employees

​Prerequisites

​Steps

​Tips

​Troubleshooting

​Related

Add an employee

HR API reference

Bulk import employees

Prerequisites

Steps

Tips

Troubleshooting

Related