HCM Cafe Public API
The Public API lets your systems read and update one HCM Cafe tenant's data: employees, organisation reference data, holidays, leave balances and attendance punches. It is a server-to-server REST API over HTTPS that sends and receives JSON.
| Base URL | https://api.hcmcafe.com |
| Token URL | https://api.hcmcafe.com/oauth/token |
| Version | v1, in every path, for example /v1/employees |
| Reference | API reference, with every route, field and error |
How access works
Each client belongs to exactly one tenant. The tenant comes from your client record, so no request carries a tenant or account ID, and records of other tenants never appear.
- Ask for access. Contact HCM Cafe with the tenant you are integrating for and what your integration needs to do. The tenant's administrator approves the scopes.
- Create a key pair. You keep the private key. It never leaves your systems.
- Send the public key, and the IP ranges your servers call from if you want token requests limited to them.
- Receive your client ID and scopes. HCM Cafe registers the client and tells you which scopes it holds.
- Call the API. Sign a short assertion with your private key, exchange it for an access token, and send the token with each call.
Get started walks through steps 2 to 5 with working code.
Scopes
A token can only call the routes its scopes allow. Ask only for what your integration needs.
| Scope | Allows |
|---|---|
employees.basic:read | List employees and get one employee: IDs, names, codes and organisation links |
employees.contact:read | Adds officialEmail to employee reads. Use together with employees.basic:read |
employees:write | Create and update employees, and list the values they accept (/v1/employee-masters) |
organisation:read | Departments, divisions, sub-departments, locations and designations |
holidays:read | Holiday calendars and their holidays |
leave.balance:read | Leave types, leave years and an employee's leave balances |
attendance.punch:write | Submit attendance punches, and list the time zones they accept |
Guides
- Get started: from a new key pair to your first call.
- Authentication: the client assertion, tokens, key rotation and IP limits.
- Conventions: paging, rate limits, retries, errors and versioning.
- Troubleshooting: what each error means and how to fix it.