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.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-staffwhen the employee also needs a FluideAuth staff seat in one request. employeeCodeshould be unique per company — your ERP employee ID maps cleanly here.- Direct-tenant integrations omit acting-client headers; JWT
tenantIdscopes the org.
Troubleshooting
Related
Bulk import
Import many employees from a spreadsheet.
Run payroll
Pay employees after HR records exist.
HR API reference
Full employee schema and playground.