Response Schema

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": [...],
  "unservedReasons": { "shift-2": ["Employee Skill Match"] },
  "violations": [...],
  "suggestions": [...]
}

Top-Level Fields

string (UUID)

required

Unique identifier for the solve job.

status

string

required

Job status: QUEUED, SOLVING, SOLVED, or ERROR.

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.

unservedReasons

object

Map of unassigned shift name to the list of hard constraints (e.g. Employee Skill Match) that blocked assignment for that shift.

violations

array

Not currently populated by Fill. See ViolatedConstraint.

suggestions

array

Not yet implemented for Fill. 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 Score	Feasible	Meaning
`0`	`true`	All hard constraints satisfied
`-1` or lower	`false`	One 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.

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

violations is a field inherited from the shared response model, but Fill does not currently populate it — it is always absent on Fill responses. Use unassigned and unservedReasons on this response for per-shift blocking information, or call /v2/fill/jobs/{id}/explanation for detailed conflict data (conflicts, unresolved).

{
  "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

The Fill /suggest endpoint is not yet implemented, and FillMapping never sets suggestions on a real solve response. This section is documented for forward compatibility only.

Alternative assignment options intended to be returned by the suggest API, using the same shape as Assignment.

{
  "shift": "morning-kitchen",
  "from": "2024-04-18T08:00:00",
  "to": "2024-04-18T14:00:00",
  "skills": ["kitchen"],
  "employee": "Carol",
  "travelTimeInSeconds": 900
}

shift

string

required

Shift identifier from the request.

from

datetime

required

Shift start time.

datetime

required

Shift end time.

skills

array

required

Skills required for this shift.

employee

string

required

Suggested employee.

travelTimeInSeconds

integer

Travel time from employee location to shift location (if locations provided).

Weights Reference

Available constraint weights for customization in requests.

Constraint	Property	Default	Description
Maximum Working Days	`maxWorkingDays`	HARD	Max days in planning period
Maximum Hours	`maxHours`	HARD	Max hours in planning period
Minimum Hours	`minHours`	HARD	Min hours in planning period
Earliest Shift Start	`shiftStart`	HARD	Earliest allowed start time
Latest Shift Start	`latestShiftStart`	HARD	Latest allowed start time
Latest Shift End	`shiftEnd`	HARD	Latest allowed end time
Maximum Shift Length	`maxShift`	HARD	Max shift duration
Minimum Shift Length	`minShift`	HARD	Min shift duration
DayOfWeek Working	`dayOfWeek`	HARD	Day-based availability
Maximum Shifts Same Day	`sameDay`	HARD	Max shifts per day
Minimum Rest Same Day	`sameDayMinRest`	HARD	Min rest between same-day shifts
Employee Availability	`availability`	HARD	Time-based availability
Locked Assignment	`locked`	HARD	Fixed assignments
Max Consecutive Days	`maxConsecutive`	HARD	Max consecutive working days
Minimum Rest	`minRest`	HARD	Min rest between shifts
No Concurrent	`concurrent`	HARD	Prevent overlapping assignments
Skill Requirements	`requirements`	HARD	Shared skill requirements
Employee Skill Match	`skills`	HARD	Skill matching
Shift Blocklist	`blacklist`	HARD	Blocked employee-shift pairs
Employee Working Days	`working`	HARD	Respect working day limits
Travel Time	`distance`	SOFT	Minimize travel
Priority	`priority`	SOFT	Shift priorities
Shift Preference	`pref`	MEDIUM	Employee preferences
Financial Costs	`costs`	SOFT	Shift costs
Wage Costs	`wages`	SOFT	Employee wage costs
Unassigned Employee	`unassigned`	MEDIUM	Minimize unassigned employees
Soft Skill Match	`softSkills`	SOFT	Soft skill matching
Critical Skill Match	`criticalSkills`	HARD	Employee lacks a critical required skill
Efficiency	`efficiency`	SOFT	Employee efficiency
Skill Level Match	`softSkillsLevel`	SOFT	Skill proficiency matching
Minimum Hours (Unassigned)	`minHoursUnassigned`	HARD	Min hours for unassigned-eligible employees
Travel Time (Availability Locations)	`distanceAL`	SOFT	Travel time from availability locations
Fairness	`fairness`	SOFT	Fair distribution of work
Counter Days Worked	`counterDaysWorked`	HARD	Days-worked counter rule
Counter Days Idle	`counterDaysIdle`	HARD	Days-idle counter rule
Counter Hours Worked	`counterHoursWorked`	HARD	Hours-worked counter rule
Counter Shift Types Worked	`counterShiftTypesWorked`	HARD	Shift-types-worked counter rule
Counter Shift Types Hours	`counterShiftTypesHours`	HARD	Shift-types-hours counter rule
Counter Weekends Worked	`counterWeekendsWorked`	HARD	Weekends-worked counter rule
Counter Weekends Idle	`counterWeekendsIdle`	HARD	Weekends-idle counter rule
Counter Max Consecutive Days	`counterMaxConsecutiveDays`	HARD	Max-consecutive-days counter rule
Sequence Days Worked	`sequenceDaysWorked`	HARD	Days-worked sequence rule
Sequence Days Idle	`sequenceDaysIdle`	HARD	Days-idle sequence rule
Sequence Hours Worked	`sequenceHoursWorked`	HARD	Hours-worked sequence rule
Sequence Shift Types Worked	`sequenceShiftTypesWorked`	HARD	Shift-types-worked sequence rule
Sequence Shift Types Hours	`sequenceShiftTypesHours`	HARD	Shift-types-hours sequence rule
Sequence Weekends Worked	`sequenceWeekendsWorked`	HARD	Weekends-worked sequence rule
Sequence Weekends Idle	`sequenceWeekendsIdle`	HARD	Weekends-idle sequence rule
Sequence Max Consecutive Days	`sequenceMaxConsecutiveDays`	HARD	Max-consecutive-days sequence rule
Rest Minimum Duration	`restMinDuration`	HARD	Rest period shorter than minimum duration
Rest Minimum Consecutive	`restMinConsecutive`	HARD	Insufficient consecutive rest
Rest Before Shift	`restBeforeShift`	HARD	Insufficient rest before the shift
Rest After Shift	`restAfterShift`	HARD	Insufficient rest after the shift
Rest Maximum Duration	`restMaxDuration`	HARD	Rest period longer than maximum duration
Rest Total Duration	`restTotalDuration`	HARD	Total rest outside allowed bounds
Pattern Prohibited	`patternProhibited`	HARD	A prohibited shift pattern occurred
Pattern Preferred	`patternPreferred`	SOFT	A preferred shift pattern was not followed
Pattern Unpreferred	`patternUnpreferred`	SOFT	An unpreferred shift pattern occurred

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.

Platform

VRP API

Fill API

Response Structure

Top-Level Fields

Score

Score Interpretation

Assignment

Example Assignment List

ViolatedConstraint

Suggestion

Weights Reference

Custom Weight Format

​Response Structure

​Top-Level Fields

​Score

​Score Interpretation

​Assignment

​Example Assignment List

​ViolatedConstraint

​Suggestion

​Weights Reference

​Custom Weight Format

Response Structure

Top-Level Fields

Score

Score Interpretation

Assignment

Example Assignment List

ViolatedConstraint

Suggestion

Weights Reference

Custom Weight Format