Request Schema

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
  "label": "...",          // Optional: identify the request (e.g. end customer id)
  "metadata": {...}        // Optional: tracking metadata
}

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.

label

string

Label to identify the request (e.g. end customer id). Max 255 characters.

metadata

object

Optional metadata for tracking purposes (e.g. customerId, appId, userId). Max 10 entries.

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,
  "location": { "lat": 51.05, "lon": 3.72 }
}

name

string

required

Unique identifier for the shift.

from

datetime

required

Shift start time (ISO 8601 format).

datetime

required

Shift end time (ISO 8601 format).

skills

array

Required skill references. Employees must have matching skills.

min

integer

required

Minimum employees required for this shift.

max

integer

required

Maximum employees allowed for this shift.

priority

integer

Shift importance; the solver’s penalty for leaving the shift unassigned scales with this value, so a higher value means higher priority (more likely to be filled). Must be ≥ 0. No fixed upper bound.

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", "weight": 3 }],
  "availability": ["2024-04-18T08:00:00/2024-04-18T18:00:00"],
  "preference": ["morning-kitchen"],
  "contracts": [...],
  "home": { "lat": 51.05, "lon": 3.72 },
  "hourlyPay": 22.5,
  "periodRules": [...]
}

name

string

required

Unique identifier for the employee.

skills

array

Employee capabilities. Each skill has a name, optional weight (proficiency), and optional expiry date.

availability

array

Available time ranges (ISO 8601 interval format).

preference

array

Preferred shift names.

contracts

array

List of employee contracts (working-time limits, shift-length limits, etc.).

home

object

Home location of the employee; the solver optimizes total travel time.

hourlyPay

number

Hourly pay of the employee; the solver optimizes planning cost.

periodRules

array

Rules scoped to a specific period, overriding contract defaults for that 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, MAX_CONSECUTIVE_DAYS.

min

integer

Minimum count or sequence length.

max

integer

Maximum count or sequence length.

At least one of min or max must be provided; a Rule cannot omit both.

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.

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.

useAvailabilityLocations

boolean

Whether to use the location on employee availability windows when computing travel time.

alwaysScoreSharedSkills

boolean

Whether to always score shared skill requirements, even when not otherwise triggered.

ExplanationOptions

{ "enabled": true, "filterHardConstraints": false, "onlyUnassigned": false }

enabled

boolean

default:"false"

Enable alternative generation.

filterHardConstraints

boolean

default:"false"

Exclude infeasible alternatives from response.

onlyUnassigned

boolean

default:"false"

Compute alternatives only for unassigned shifts.

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

Platform

VRP API

Fill API

Request Structure

Top-Level Fields

Shift

ShiftTag

Employee

Rule

Requirement

FairnessBucket

Pattern

Demand

Assignment

Options

ExplanationOptions

IdleWeekendDefinition

Rest

​Request Structure

​Top-Level Fields

​Shift

​ShiftTag

​Employee

​Rule

​Requirement

​FairnessBucket

​Pattern

​Demand

​Assignment

​Options

​ExplanationOptions

​IdleWeekendDefinition

​Rest

Request Structure

Top-Level Fields

Shift

ShiftTag

Employee

Rule

Requirement

FairnessBucket

Pattern

Demand

Assignment

Options

ExplanationOptions

IdleWeekendDefinition

Rest