Planday

Approves or rejects a swap (or handover) between two existing shifts. Set accept=true to approve the swap, or accept=false to reject it. Identify the shifts by ID only — the department is resolved automatically. A swap that would double-book an employee or breach a labour rule is refused with the reason.

approve_shift_swap

Assigns (or reassigns) an existing shift to an employee. Approved absence is not checked: a shift can be assigned to an employee who is on leave that day and it will succeed.

assign_shift

Creates an unpublished draft shift in a department. Returns the new shift ID plus the employee, department, position and employee-group names it was created with, and a ready-made description of the shift — report the created shift to the user with those names, not with ids. A name comes back null when the shift has no such entity (an open shift has no employee, and a shift need not have a position) or when it could not be looked up; say so rather than showing the id instead. employeeGroupId is required — it is the section the shift belongs to and determines who is eligible for it. Assigning an employee and a position is optional. Omit employeeId to create an OPEN (unassigned) shift that anyone in the employee group is eligible to take — that is how open shifts are created; assign one later with assign_shift. The shift is a draft until published with publish_draft_shifts. Overlapping shifts and working-time rule breaches are refused, but approved absence is not checked: a shift can be created on a day the employee is on leave and it will succeed.

create_draft_shift

Returns the full detail of a single working time rule identified by ruleId (obtained from list_working_time_rules): the threshold it enforces, the period it is measured over, the days it covers, and the employee groups, types and shift types it applies to.

get_working_time_rule

Reads absence accounts. The arguments select one of four scopes: with neither accountId nor employeeId, returns a paged list of active accounts in 'accounts'; with accountId, returns that one account's full definition in 'details' (accrued accounts only, as only accrued accounts have a definition to read); with accountId and includeBalances, returns that account's balances in 'balances' instead of its definition, which works for an account of any absence type; with employeeId and includeBalances, returns every account balance for that employee. includeBalances requires accountId or employeeId — balances cannot be read portal-wide.

list_absence_accounts

Reads absence policies (also called account types). The arguments select the scope: with no policyId, returns a paged list of policies of every absence type (Vacation, Absence, Flextime, Accrued, ExtraLeave) in 'policies'; with policyId, returns that one policy's full definition in 'details'. Set includeSuggestions to also return the published policy templates for the portal's country, which can seed create_absence_policy via its suggestionId argument. Detail, create and update cover accrued policies only.

list_absence_policies

Returns a list of active departments for a portal. Departments are referenced by ID in other entities such as absence policies.

list_departments

Returns active employees for a portal, up to the first 200 (larger portals are truncated). Each employee includes the ids of the departments and employee groups they belong to. Pass departmentIds to return only the employees in those departments (the roster for a department, resolved before the 200 cap). Employees are referenced by ID in other entities such as absence accounts.

list_employees

Returns the shifts scheduled in a date range for the given departments and/or employees, up to the first 150 (narrow the date range or filters if results may be truncated). You must supply at least one departmentId or employeeId. Unpublished draft shifts are included by default and identified by the isDraft flag. Open (unassigned) shifts have a null employeeId; to see them query by departmentIds only — supplying employeeIds restricts results to those employees' assigned shifts and excludes open shifts, which belong to no employee. For a portal-wide query with no department named, call list_departments first and pass every department id; never guess ids. Each shift carries the employee, department, position and employee-group names alongside their ids — describe shifts to the user by those names, not by id. Not every shift has all of them: a shift often has no position, and an open shift has no employee. A null name means the shift has no such entity, or that its name could not be looked up — in either case say so ("no position set", "unassigned") rather than showing the id in its place.

list_shifts

Returns the portal's working time rules — the labour rules (e.g. max timesheet length, minimum rest between shifts) that govern scheduling. Each entry gives the rule's type and the employee groups and types it applies to. Use get_working_time_rule for a rule's full thresholds.

list_working_time_rules