Skip to main content
The Fill API returns optimized shift assignments with scoring information and optional explanations.

​
Response Structure

{
  "id": "job-uuid-123",
  "status": "SOLVED",
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -5,
    "feasible": true
  },
  "assignments": [...],
  "unassigned": [...],
  "violations": [...],
  "suggestions": [...]
}

​
Top-Level Fields

​
id
string (UUID)
required
Unique identifier for the solve job.
​
status
string
required
Job status: QUEUED, SOLVING, or SOLVED.
​
score
object
required
Solution quality indicator. See Score.
​
assignments
array
required
List of employee-shift pairings. See Assignment.
​
unassigned
array
List of shift names that could not be filled.
​
violations
array
List of constraint violations. See ViolatedConstraint.
​
suggestions
array
Alternative assignments from suggest API. See Suggestion.

​
Score

The score indicates solution quality using a three-tier system. 
{
  "hardScore": 0,
  "mediumScore": 0,
  "softScore": -15,
  "feasible": true
}
​
hardScore
integer
required
Hard constraint violations. Must be 0 for a feasible solution.
​
mediumScore
integer
required
Medium constraint violations. Less critical than hard constraints.
​
softScore
integer
required
Soft constraint penalties. Used to optimize solution quality.
​
feasible
boolean
required
true if hardScore is 0. Indicates all hard constraints are satisfied.

​
Score Interpretation

Hard ScoreFeasibleMeaning
0trueAll hard constraints satisfied
-1 or lowerfalseOne or more hard constraint violations
A negative soft score is normal and expected. The solver minimizes soft score violations while keeping hard constraints satisfied.

​
Assignment

Each assignment represents an employee assigned to a shift. 
{
  "shift": "morning-kitchen",
  "from": "2024-04-18T08:00:00",
  "to": "2024-04-18T14:00:00",
  "skills": ["kitchen"],
  "employee": "Alice",
  "travelTimeInSeconds": 1200
}
​
shift
string
required
Shift identifier from the request.
​
from
datetime
required
Shift start time.
​
to
datetime
required
Shift end time.
​
skills
array
required
Skills required for this shift.
​
employee
string
required
Assigned employee name.
​
travelTimeInSeconds
integer
Travel time from employee location to shift location (if locations provided).

​
Example Assignment List

{
  "assignments": [
    {
      "shift": "morning-kitchen",
      "from": "2024-04-18T08:00:00",
      "to": "2024-04-18T14:00:00",
      "skills": ["kitchen"],
      "employee": "Alice"
    },
    {
      "shift": "evening-bar",
      "from": "2024-04-18T18:00:00",
      "to": "2024-04-18T23:00:00",
      "skills": ["bar"],
      "employee": "Bob"
    }
  ]
}

​
ViolatedConstraint

Details about constraints that were violated in the solution. 
{
  "name": "Employee Skill Match",
  "value": 2,
  "level": "SOFT"
}
​
name
string
required
Constraint identifier.
​
value
number
required
Violation magnitude. Higher values indicate larger deviations.
​
level
string
required
Constraint level: HARD, MEDIUM, or SOFT.

​
Suggestion

Alternative assignment options returned by the suggest API. 
{
  "shift": "morning-kitchen",
  "employee": "Carol",
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -3,
    "feasible": true
  },
  "violations": [...]
}
​
shift
string
required
Shift being evaluated.
​
employee
string
required
Suggested employee.
​
score
object
required
Impact on solution score if this assignment is made.
​
violations
array
Constraints violated by this suggestion.

​
Weights Reference

Available constraint weights for customization in requests.
ConstraintPropertyDefaultDescription
Maximum Working DaysmaxWorkingDaysHARDMax days in planning period
Maximum HoursmaxHoursHARDMax hours in planning period
Minimum HoursminHoursHARDMin hours in planning period
Earliest Shift StartshiftStartHARDEarliest allowed start time
Latest Shift StartlatestShiftStartHARDLatest allowed start time
Latest Shift EndshiftEndHARDLatest allowed end time
Maximum Shift LengthmaxShiftHARDMax shift duration
Minimum Shift LengthminShiftHARDMin shift duration
DayOfWeek WorkingdayOfWeekHARDDay-based availability
Maximum Shifts Same DaysameDayHARDMax shifts per day
Minimum Rest Same DaysameDayMinRestHARDMin rest between same-day shifts
Employee AvailabilityavailabilityHARDTime-based availability
Locked AssignmentlockedHARDFixed assignments
Max Consecutive DaysmaxConsecutiveHARDMax consecutive working days
Minimum RestminRestHARDMin rest between shifts
No ConcurrentconcurrentHARDPrevent overlapping assignments
Skill RequirementsrequirementsHARDShared skill requirements
Employee Skill MatchskillsHARDSkill matching
Shift BlocklistblacklistHARDBlocked employee-shift pairs
Employee Working DaysworkingHARDRespect working day limits
Travel TimedistanceSOFTMinimize travel
PriorityprioritySOFTShift priorities
Shift PreferenceprefMEDIUMEmployee preferences
Financial CostscostsSOFTShift costs
Wage CostswagesSOFTEmployee wage costs
Unassigned EmployeeunassignedMEDIUMMinimize unassigned employees
Soft Skill MatchsoftSkillsSOFTSoft skill matching
Critical Skill MatchcriticalSkillsSOFTCritical shift preference
EfficiencyefficiencySOFTEmployee efficiency
Skill Level MatchsoftSkillsLevelSOFTSkill proficiency matching

​
Custom Weight Format

Override defaults using the format <weight><priority>: 
{
  "weights": {
    "locked": "100hard",
    "unassigned": "5soft",
    "skills": "50hard"
  }
}
Use weights to balance competing objectives. Increase weights for constraints that matter most to your business.