Skip to main content
The Fill API request defines employees, shifts, and constraints for workforce scheduling optimization.

​
Request Structure

{
  "employees": [...],      // Required: Available workforce
  "shifts": [...],         // Required: Shifts to fill
  "rules": [...],          // Optional: Labor constraints
  "requirements": [...],   // Optional: Skill requirements
  "fairnessBuckets": [...],// Optional: Workload distribution
  "rests": [...],          // Optional: Rest periods
  "patterns": [...],       // Optional: Shift sequences
  "demands": [...],        // Optional: Coverage requirements
  "assignments": [...],    // Optional: Pre-assigned shifts
  "options": {...},        // Optional: Solver configuration
  "weights": {...},        // Optional: Constraint weights
  "hook": "..."            // Optional: Webhook URL
}

​
Top-Level Fields

​
shifts
array
required
List of shifts to be filled with employees. See Shift.
​
employees
array
required
List of available employees. See Employee.
​
rules
array
Labor rules and constraints. See Rule.
​
requirements
array
Skill requirements across shifts. See Requirement.
​
fairnessBuckets
array
Workload distribution groups. See FairnessBucket.
​
rests
array
Rest period constraints. See Rest.
​
patterns
array
Shift sequence patterns. See Pattern.
​
demands
array
Coverage requirements. See Demand.
​
assignments
array
Pre-assigned employee-shift pairs. See Assignment.
​
options
object
Solver configuration. See Options.
​
weights
object
Custom constraint weights. See Weights.
​
hook
string (URI)
Webhook URL for completion notification.

​
Shift

Shifts represent time slots that need employees assigned. 
{
  "name": "morning-kitchen",
  "from": "2024-04-18T08:00:00",
  "to": "2024-04-18T14:00:00",
  "skills": [{ "name": "kitchen" }],
  "min": 1,
  "max": 2,
  "priority": 1,
  "tags": [{ "name": "EARLY" }],
  "blocklist": ["employee-3"],
  "cost": 50
}
​
name
string
required
Unique identifier for the shift.
​
from
datetime
required
Shift start time (ISO 8601 format).
​
to
datetime
required
Shift end time (ISO 8601 format).
​
skills
array
Required skill references. Employees must have matching skills.
​
min
integer
default:"1"
Minimum employees required for this shift.
​
max
integer
default:"1"
Maximum employees allowed for this shift.
​
priority
integer (1-10)
Shift importance. 1 = highest priority, 10 = lowest.
​
tags
array
Shift tags for grouping in rules and patterns. See ShiftTag.
​
blocklist
array
Employee names that cannot be assigned to this shift.
​
cost
number
Financial cost for assigning this shift. Minimized in partial planning.
​
rests
array
Rest requirements after this shift. See ShiftRest.

​
ShiftTag

{ "name": "NIGHT" }
​
name
string
required
Tag identifier used in rules and patterns.

​
Employee

Employees are the workforce available for shift assignments. 
{
  "name": "Alice",
  "skills": [{ "name": "kitchen", "level": 3 }],
  "availability": ["2024-04-18T08:00:00/2024-04-18T18:00:00"],
  "preference": ["morning-kitchen"],
  "lastRestDate": "2024-04-17"
}
​
name
string
required
Unique identifier for the employee.
​
skills
array
Employee capabilities with optional proficiency levels.
​
availability
array
Available time ranges (ISO 8601 interval format).
​
preference
array
Preferred shift names.
​
lastRestDate
date
Last rest date before the planning period.

​
Rule

Rules define labor constraints using counters or sequences. 
{
  "constraint": "COUNTER",
  "type": "WORKING_DAYS",
  "min": 2,
  "max": 5,
  "period": {
    "from": "2024-04-01",
    "to": "2024-04-07"
  },
  "shifts": ["NIGHT"],
  "then": { ... }
}
​
constraint
string
required
Rule type: COUNTER or SEQUENCE.
​
type
string
required
What to measure: DAYS_WORKED, DAYS_IDLE, WEEKENDS_WORKED, WEEKENDS_IDLE, SHIFT_TYPES_WORKED, SHIFT_TYPES_HOURS_WORKED, HOURS_WORKED.
​
min
integer
Minimum count or sequence length.
​
max
integer
Maximum count or sequence length.
​
period
object
Time scope with from/to or rolling duration.
​
shifts
array
Filter to specific shift tags.
​
then
Rule
Conditional rule triggered when threshold exceeded.

​
Requirement

Skill requirements across multiple shifts. 
{
  "shifts": ["shift-1", "shift-2"],
  "skill": "supervisor",
  "value": 1
}
​
shifts
array
required
Shift names this requirement applies to.
​
skill
string
required
Required skill name.
​
value
integer
required
Number of employees with this skill required.

​
FairnessBucket

Groups for equitable workload distribution. 
{
  "employees": ["Alice", "Bob"],
  "shifts": ["shift-1", "shift-2"],
  "period": { "from": "2024-01-01", "to": "2024-01-07" },
  "target": "PT40H"
}
​
employees
array
required
Employees in this fairness group.
​
shifts
array
required
Shifts to distribute fairly.
​
period
object
Evaluation period with from and to dates.
​
target
string (ISO 8601 duration)
required
Target workload per employee.

​
Pattern

Shift sequence preferences or restrictions. 
{
  "type": "MULTI_DAY",
  "satisfy": "PROHIBITED",
  "elements": [
    { "type": "ON", "tags": ["LATE"] },
    { "type": "ON", "tags": ["EARLY"] }
  ],
  "weight": 5
}
​
type
string
required
SINGLE_DAY or MULTI_DAY.
​
satisfy
string
required
PREFERRED, UNPREFERRED, or PROHIBITED.
​
elements
array
Sequence elements with type (ON/OFF) and tags (tag list).
​
weight
integer
Priority weight for preferred patterns.

​
Demand

Coverage requirements independent of shifts. 
{
  "name": "peak-hours",
  "from": "2024-01-01T14:00:00",
  "to": "2024-01-01T18:00:00",
  "skills": [{ "name": "general" }],
  "min": 3,
  "max": 5
}
​
name
string
required
Unique demand identifier.
​
from
datetime
required
Demand period start.
​
to
datetime
required
Demand period end.
​
skills
array
required
Required skills for this demand period.
​
min
integer
Minimum employees required.
​
max
integer
Maximum employees allowed.

​
Assignment

Pre-defined employee-shift pairings. 
{
  "shift": "morning-1",
  "employee": "Alice",
  "locked": true
}
​
shift
string
required
Shift name to assign.
​
employee
string
required
Employee name to assign.
​
locked
boolean
default:"false"
If true, the solver cannot change this assignment.

​
Options

Solver configuration settings. 
{
  "hardAvailability": true,
  "hardSkill": true,
  "partialPlanning": false,
  "explanation": { "enabled": true },
  "idleWeekend": { ... }
}
​
hardAvailability
boolean
default:"true"
Enforce availability as hard constraint.
​
hardSkill
boolean
default:"true"
Enforce skill matching as hard constraint.
​
hardBlacklist
boolean
default:"true"
Enforce blocklist as hard constraint.
​
partialPlanning
boolean
default:"false"
Allow unfilled shifts in solution.
​
penaliseZeroHours
boolean
Penalize employees with no assignments.
​
explanation
object
Explanation settings. See ExplanationOptions.
​
idleWeekend
object
Weekend definition. See IdleWeekendDefinition.

​
ExplanationOptions

{ "enabled": true, "filterHardConstraints": false }
​
enabled
boolean
default:"false"
Enable alternative generation.
​
filterHardConstraints
boolean
default:"false"
Exclude infeasible alternatives from response.

​
IdleWeekendDefinition

{
  "fromDayOfWeek": "FRIDAY",
  "fromTime": "19:00:00",
  "toDayOfWeek": "SUNDAY",
  "toTime": "23:00:00",
  "restTime": "PT36H"
}
​
fromDayOfWeek
string
required
Weekend start day.
​
fromTime
string
required
Weekend start time (HH:mm:ss).
​
toDayOfWeek
string
required
Weekend end day.
​
toTime
string
required
Weekend end time (HH:mm:ss).
​
restTime
string (ISO 8601 duration)
Minimum consecutive rest for idle weekend.

​
Rest

Rest period constraints. 
{
  "tags": ["NIGHT"],
  "sequence": "AFTER",
  "min": "PT11H",
  "minConsecutive": "PT8H"
}
​
tags
array
Shift tags that trigger this rest.
​
excludes
array
Shift tags excluded from rest calculation.
​
sequence
string
AFTER or BEFORE the triggering shift.
​
period
object
Fixed period for periodic rest rules.
​
periodType
string
Rolling period: WEEKLY, DAILY.
​
min
string (ISO 8601 duration)
Minimum total rest.
​
minConsecutive
string (ISO 8601 duration)
Minimum uninterrupted rest.
​
frequency
integer
Maximum rest occurrences.