FILL request

Filling in pre-defined shifts with employees according to contractual agreements that enforce fair and cost efficient
rosters. The input requires you to make up:

  • contract definitions
  • open shifts
  • available employees

Additionally you can customise the solver behaviour by also changing the weights and priority of the constraints

This FILL request schema is used for solving a Shift Filling Problem. It consists of shifts, employees, options
and weights.

shifts[Shift]trueList of Shifts
employees[Employee]trueList of Employees
optionsOptionsfalseOptions for solver configuration
weightsWeightsfalseWeighting the constraints
hookstring(uri)falseWebhook for getting notified after request is solved.


A contract definition consists of a multitude of labour restricting constraints such as the maximum number of
consecutive working days, the maximum number of shifts per day, number of resting days, etc...

namestringUnique name identifier for a contract.
maxstring (duration iso8601)Maximum duration of all assigned shifts per employee.
minstring (duration iso8601)Minimum total duration of all assigned shifts per employee.
maxConsecutiveWorkDaysintegerMaximum number of days that one employee is allowed to work in a row.
maxShiftsDayintegerMaximum number of shifts during one day.
minRestBetweenShiftsSameDaystring (duration iso8601)Minimum duration between two shifts on the same day.
maxWorkingDaysintegerMaximum number of days working in the planning period.
latestShiftStartstring (time iso8601)Latest time an employee can start his shift.
earliestShiftStartstring (time iso8601)Earliest time an employee can start his shift.
  "name": "FULL",
  "max": "PT38H",
  "min": "PT5H",
  "maxConsecutiveWorkDays": 5,
  "maxShiftsDay": 2,
  "minRestBetweenShiftsSameDay": 30,
  "maxWorkingDays": 6,
  "latestShiftStart": "10:00:00",
  "earliestShiftStart": "02:00:00"


The shifts represent the demand. These shifts need to be filled in with employees.
A shift in its simplest form can be defined by a shift start time (from) and an end time (to).
Shifts are uniquely identified by a name and require a specific skill.
You can define the number of employees that need to be assigned to this shift with value.

namestringUnique id of the shift
fromstring (datetime)Starting time of the shift
tostring (datetime)End time of the shift
skillsarray of stringsSkill name references
costnumberFinancial cost related to this shift. Will be minimised when partialPlanning.
valuenumberActual number of employees that should be assigned to this shift
prioritynumberForces a priority constraint on this shift with 1 being highest priority and 10 being the lowest.
employeesarray of stringsList of planned employees. Or can be used to pre-plan.


Define the resources or employees with whom you want to fill up the shifts.

namestringUnique identifier for this employee
contractstringReference to contract for this employee.
skillsarray of stringList of skill references.
lastRestDatestring (date)The last date on which the employee had a rest before the planning period.
availabilityarray of stringAvailable date-time range of employee.
preferencearray of stringPreference towards certain shifts. (shift name)
periodRulesarray of PeriodRuleList of Period Rule

Period Rule

A shift rule for an employee that applies to a period of time.

periodPlanningPeriodPlanning period for this period rule.
maxWorkingDaysintegerMaximum number of total days working in planning period.
minWorkingDaysintegerMinimum number of total days working in planning period.
minWorkingDurationstringMinimum duration to work in the planning period.
maxWorkingDurationstringMaximum duration to work in the planning period.
minRestDurationBetweenShiftsSameDaystringMinimum duration between two shifts on the same day in this planning period.
minRestDurationstringMinimum duration between any two shifts in this planning period.


For a select group of employees and shifts you can require fair distribution of shifts per planning period. The
planning period can be the entire planning period or a subset of it.

  "fairnessBuckets": [
      "employees": [
      "shifts": [
      "period": {
        "from": "2020-01-01",
        "to": "2020-01-15"