Employees
Employees
Read the company's employees, their employment terms and their pay through
the API. These endpoints are read only: hiring, salary changes and contracts
are made on the Employees and Payroll pages in Cybooks.
The same operations power the Cybooks MCP server. Each REST endpoint below
names its MCP tool; the employee tools are reached through
cybooks_search_capabilities "employee" and run with
cybooks_read_capability.
Endpoints
| Endpoint | MCP tool | Scope | Permission |
|---|---|---|---|
GET /v1/employees | cybooks_list_employees | employees:read | view_employees |
GET /v1/employees/{id} | cybooks_get_employee | employees:read | view_employees |
GET /v1/employees/{id}/contract | cybooks_get_employee_contract | employees:sensitive | view_employees and view_employee_contracts |
GET /v1/employees/{id}/compensation | cybooks_get_employee_compensation | employees:sensitive | view_employees |
The scope column applies to API keys (REST). An MCP connection is checked
against the connected person's permissions, not key scopes. A person without
the permission gets 403 Forbidden; an id the company does
not have gets 404. Payroll is on every plan, so the plan check is the
bookkeeping feature every plan carries.
Salary figures need view_payroll
view_payrollCybooks shows pay only to people who may see payroll. The API does the same:
for a key or MCP connection whose person lacks view_payroll, every salary
figure is null and the response carries salary_hidden: true.
| Endpoint | Hidden without view_payroll | Still shown |
|---|---|---|
employee.index, employee.show | nothing: they never carry pay | everything |
employee.contract | wage; substantive is null when only the wage could tell | contract type, pay type, 13th salary election, dates, hours, position |
employee.compensation | gross_annual_amount, hourly_rate and notes on every row; benefits (null) | dates, salary types, states, change reasons, currency, pay frequency |
The employee record never carries identity numbers (TIC, social insurance),
the bank account, the home address, phone numbers or the date of birth.
The employee
GET /v1/employees lists the employees with cursor pagination.
filter[status]:active(the default: not archived),archivedorall.filter[q]: matches first name, last name, full name, email or the payroll
number.filter[related_party_id]: the employee record of a director, shareholder
or other related party (list them withGET /v1/related-parties).filter[updated_since]: an ISO 8601 timestamp.sort:last_name(default),created_at,updated_atorid, with-
for descending.
Each employee has id, number (the payroll number), first_name,
last_name, full_name, email, job_position, employee_type,
start_date, related_party_id, director (the linked related party's
director role, else the payroll director flag), status, archived_at,
created_at and updated_at.
The contract
GET /v1/employees/{id}/contract returns the employment terms:
on_file: false when no contract is recorded.substantiveis true only
when the contract carries real terms (a contract type or a positive wage),
not just the 13th salary election. Without a contract type and without
view_payrollit is null, so the hidden wage cannot be inferred from it.contract_type,pay_type(salaryorhourly),wageand
currency(EUR).thirteenth_salary:elected,pay_monthandapplicable_from.job_position,start_date,end_date(the last working day, once the
employee has left),working_pattern,week_working_hoursand
working_times(hours per weekday, as[{"day": "monday", "hours": 8}]).related_party_id.
Compensation
GET /v1/employees/{id}/compensation returns the pay:
current: the salary in force today. It is a dated salary row
(source: compensation), or, for an employee with no dated row yet, the
salary on the payroll record (source: employee_record, effective from the
start date) while no dated row has started. Null when neither applies.history: every dated salary row, newest first, including scheduled
changes (state: scheduled), past ones (superseded) and cancelled ones
(cancelled). Each row hassalary_type(annualorhourly),
gross_annual_amountorhourly_rate,effective_date,end_date,
change_reason,notesandcancelled_at.benefits: the benefit enrolments (provident fund, medical insurance and
so on) with the scheme, the employee and employer contribution rates (a
fraction of pay:0.0500is 5%) and their dates.currency(EUR, the payroll currency) andpay_frequency(how often the
company runs payroll,monthly; null before payroll is set up).
Worked example: a director's salary before a reimbursement
An agent preparing a home-office reimbursement for a director needs the
director's employee record, contract and salary:
GET /v1/related-parties?filter[role]=directorand pick the director's
id.GET /v1/employees?filter[related_party_id]={id}returns the employee
record linked to that related party (none means the director is not on
payroll).GET /v1/employees/{employee_id}/contract:on_fileandsubstantive
say whether an employment contract is recorded.GET /v1/employees/{employee_id}/compensation:currentis the salary in
force. Withsalary_hidden: truethe key's person lacksview_payroll;
ask someone who has it.
Updated 23 days ago
