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 employee group the shift belongs to and determines who is eligible for it. Assigning an employee and a position is optional; a position must be one of that employee group's positions, which list_positions returns. 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. shiftTypeId books the shift as a specific type (Overtime 1.5, Training, Annual leave); omit it to leave the shift on the portal's default type, which Planday calls Normal. 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, each with a suggestionId that policy creation can be seeded from. 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 positions (roles a shift can be staffed as, e.g. Head Chef, Bartender) set up in the given departments. Each position belongs to one department and one employee group, and may be filed under a category, which the schedule shows as a section. Use it to find the positionId for create_draft_shift: a shift's position must be one of the positions of the shift's employee group, so filter by employeeGroupIds once the group is known. It also supplies employeeGroupId values for create_draft_shift. Omit departmentIds to list every department you have schedule access to. Each position carries its department, employee group and category names alongside the ids; describe positions to the user by name, never by id. A null categoryName means the position has no category. A null department or employee group name means the name could not be looked up. validFrom/validTo, when set, bound the dates the position can be used on. Deleted positions are not returned. A name too long to return in full is shortened and ends with '…'.

list_positions

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, employee-group and shift-type 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 there 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. shiftTypeName is different: every shift has a shift type, and a null shiftTypeId is the portal's default one, which Planday calls Normal. Describe those shifts as Normal, never as having no shift type. A name or comment too long to return in full is shortened and ends with '…', so treat a value ending that way as partial.

list_shifts