Skip to main content

Add an employee

Use this guide when onboarding one hire through your integration. The employee record in Fluide HR is the source of truth; Payroll mirrors it automatically after create.

Prerequisites

  • API credentials — Authorization
  • For partners: workspaceId, companyId, and acting-client headers — Act as a client
  • Permission: hr:employees:write

Steps

1

Create the employee record

Direct-tenant integrations: omit X-Workspace-Id and X-Acting-Company-Id — JWT tenantId scopes the organization.
Save data.id — this UUID is reused as hrEmployeeId in Payroll.
2

Add employment details (optional)

Patch the employee or create an employment contract for start date, job title, and reporting manager. See Update employee and Employment contracts in HR API reference.
3

Confirm payroll mirror

After create, HR calls Payroll internal mirror endpoints. Verify the employee appears:
See HR → Payroll sync if the mirror is missing.

Tips

  • Use POST /api/v1/hr/employees/onboard-with-staff when the employee also needs a FluideAuth staff seat in one request.
  • employeeCode should be unique per company — your ERP employee ID maps cleanly here.
  • Direct-tenant integrations omit acting-client headers; JWT tenantId scopes the org.

Troubleshooting

Bulk import

Import many employees from a spreadsheet.

Run payroll

Pay employees after HR records exist.

HR API reference

Full employee schema and playground.