Connect other systems with the HR open API

The HR open API lets another system read your people, attendance, time off and final payroll, and send punches, with a key you make. HR webhooks tell that system when something happens.

Before you start

• You must be the owner. Managers cannot make keys, even with every HR right.
• HR is switched on.

Make a key

1. Open HR → HR settings and, in Self-service and the team, select HR open API.
2. Tick The open API is on and select Save. The page shows the Base address.
3. Under Make a key, type What for (for example "payroll bureau").
4. Under May, tick only what the system needs: read people, read attendance, send punches, read leave, read final payroll, manage webhooks.
5. Select Make the key.
6. Copy the key now and give it to the other system. It is shown once; Kluvan keeps only a hash.

Add a webhook

1. Under Add a webhook, type the URL of your system (it must start with https).
2. Tick the events: employee.created, employee.left, punch.recorded, leave.approved and payroll.paid. All are ticked to start with.
3. Select Add it and copy the signing secret, which is shown once.
4. Check Deliveries to see what was sent, its status and the number of tries.

Good to know

• Separate keys. HR keys are their own system, separate from any other Kluvan API keys, and they reach your organisation's HR data only.
• A key never reads bank details, documents or biometric data. read final payroll returns paid runs only, never drafts, and no IBAN or account number.
• Select Revoke to stop a key at once. The list shows when each key was last used and how many calls it made.
• A key may make 10 calls a second, with short bursts up to 60. A period asked for can be up to 92 days.
• A punch sent through the API is added as a correction with the key's name as the author. Send each punch once: the same punch sent twice appears twice on the timesheet, and a manager removes one.
• Webhooks are signed with the secret (HMAC-SHA256 in the X-Hr-Signature header). A failed delivery is retried for about a day; a webhook that fails 20 times in a row is switched off until you switch it on again.
• Not yet tried against a live endpoint: webhook delivery is tested only inside our own test setup. Test with your own system before you rely on it.
• Making and revoking keys, and every punch sent, are written to the activity log.
• For developers, the technical reference is linked from the page: Read how to call it.