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

EndpointMCP toolScopePermission
GET /v1/employeescybooks_list_employeesemployees:readview_employees
GET /v1/employees/{id}cybooks_get_employeeemployees:readview_employees
GET /v1/employees/{id}/contractcybooks_get_employee_contractemployees:sensitiveview_employees and view_employee_contracts
GET /v1/employees/{id}/compensationcybooks_get_employee_compensationemployees:sensitiveview_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

Cybooks 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.

EndpointHidden without view_payrollStill shown
employee.index, employee.shownothing: they never carry payeverything
employee.contractwage; substantive is null when only the wage could tellcontract type, pay type, 13th salary election, dates, hours, position
employee.compensationgross_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), archived or all.
  • 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 with GET /v1/related-parties).
  • filter[updated_since]: an ISO 8601 timestamp.
  • sort: last_name (default), created_at, updated_at or id, 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. substantive is 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_payroll it is null, so the hidden wage cannot be inferred from it.
  • contract_type, pay_type (salary or hourly), wage and
    currency (EUR).
  • thirteenth_salary: elected, pay_month and applicable_from.
  • job_position, start_date, end_date (the last working day, once the
    employee has left), working_pattern, week_working_hours and
    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 has salary_type (annual or hourly),
    gross_annual_amount or hourly_rate, effective_date, end_date,
    change_reason, notes and cancelled_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.0500 is 5%) and their dates.
  • currency (EUR, the payroll currency) and pay_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:

  1. GET /v1/related-parties?filter[role]=director and pick the director's
    id.
  2. 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).
  3. GET /v1/employees/{employee_id}/contract: on_file and substantive
    say whether an employment contract is recorded.
  4. GET /v1/employees/{employee_id}/compensation: current is the salary in
    force. With salary_hidden: true the key's person lacks view_payroll;
    ask someone who has it.

Did this page help you?