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

curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/hr/employees" \
  -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" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "employeeCode": "EMP-001"
  }'
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:
curl -sS "$FLUIDE_BASE_URL/api/v1/payroll/employees" \
  -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"
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

ProblemResolution
403 on createMissing hr:employees:write or acting-client permission partner:client:act-as.
Employee not in PayrollMirror is async — wait and retry. See HR → Payroll.
Duplicate employeeCodeUse a unique code or update the existing record via PATCH.

Bulk import

Import many employees from a spreadsheet.

Run payroll

Pay employees after HR records exist.

HR API reference

Full employee schema and playground.