Reading data
The endpoints, the scope each needs, and what the API never returns.
Switched on per organisationThis is built and working, and is switched on for each organisation on request. Ask your account manager, or reply to any email from us naming it.
| Endpoint | Scope | What it returns |
|---|---|---|
GET /v1/employees | employees:read | People: names, job title, department, status, start and leaving dates, holiday calendar. Filters: status, updated_since |
GET /v1/employees/{id} | employees:read | One person |
GET /v1/leave-types | leave:read | Your annual leave types |
GET /v1/leave-requests?from=&to= | leave:read | Annual leave bookings that overlap the range (at most 400 days). Filters: status, employee_id, updated_since |
GET /v1/leave-requests/{id} | leave:read | One annual leave booking |
GET /v1/leave-balances?year= | leave:read | Allowance, carried over, adjustment, used, pending and remaining per person |
GET /v1/holidays?from=&to= | holidays:read | Bank holidays for your people's calendars, and your company closure days |
Every field of every response is in the API reference.
Never available
The API never returns pay and reward, date of birth, sex, gender, nationality, marital status, National Insurance number, addresses, email addresses and other contact details, line manager, team, location, risk scores, free-text notes and reasons, or any leave other than annual leave. That rules out sickness, medical, parental and bereavement leave.
Good to know
- An id from another organisation returns 404, the same as one that does not exist. There is no way to name another organisation.
- Unknown or repeated query parameters return 400.
- New fields may be added to version 1, so ignore fields you do not recognise. Breaking changes only arrive in a new version.