Skip to main content

​
HR → Payroll employee sync

Fluide HR is the canonical source for employee and contract data. When you create or update records via the HR API, HR automatically mirrors them into Fluide Payroll using internal service-to-service calls.
As a Connect integrator you only call public HR and Payroll APIs. Mirroring happens inside the platform — this guide explains the behavior so you can debug sync issues.

​
When sync happens

HR actionPayroll effect
POST /api/v1/hr/employeesUpsert employee mirror row
PATCH /api/v1/hr/employees/{id}Update mirror
Create / update employment contractUpsert contract mirror
Company created under workspaceDefault wallet provisioned on Pay

​
Idempotency

Payroll employees.id equals the canonical HR employee UUID. Replaying the same create or update updates the same Payroll row — safe to retry. Contract rows may use the same UUID as hr_employment_contract.id when HR sends contract.id.

​
Steps (integrator workflow)

1

Create employee in HR

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 "Content-Type: application/json" \
  -d '{"firstName": "Ada", "lastName": "Lovelace", "email": "ada@example.com"}'
2

Wait for mirror (usually seconds)

HR publishes to Payroll internal endpoints asynchronously after commit.
3

Verify in Payroll API

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"
The employee id should match HR data.id.
4

Proceed to payroll run

Once mirrored, include the employee in a run — Run payroll.

​
Internal mechanics (reference)

HR calls Payroll with:
  • Header: x-internal-api-key (service mesh only — not for Connect developers)
  • POST /api/v1/payroll/internal/employees/mirror-from-hr
  • POST /api/v1/payroll/internal/contracts/upsert-from-hr
  • POST /api/v1/payroll/internal/employees/provision-wallet
See also HR payroll integration and Payroll HR mirror for service-side detail.

​
Troubleshooting

ProblemResolution
HR row exists, Payroll emptyWait and retry list. If still missing after minutes, contact support with HR employee UUID.
Employee in Payroll but not in runAdd active contract and payment rail in HR first.
Wrong company scope (partners)Confirm acting-client headers on both HR and Payroll calls.

Add an employee

Create the canonical HR record.

Run payroll

Process pay after sync.