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

array

required

List of shifts to be filled with employees. See Shift.

array

required

List of available employees. See Employee.

array

Labor rules and constraints. See Rule.

array

Skill requirements across shifts. See Requirement.

array

Workload distribution groups. See FairnessBucket.

array

Rest period constraints. See Rest.

array

Shift sequence patterns. See Pattern.

array

Coverage requirements. See Demand.

array

Pre-assigned employee-shift pairs. See Assignment.

object

Solver configuration. See Options.

object

Custom constraint weights. See Weights.

string (URI)

Webhook URL for completion notification.

string

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

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

string

required

Unique identifier for the shift.

datetime

required

Shift start time (ISO 8601 format).

datetime

required

Shift end time (ISO 8601 format).

array

Required skill references. Employees must have matching skills.

integer

required

Minimum employees required for this shift.

integer

required

Maximum employees allowed for this shift.

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.

array

Shift tags for grouping in rules and patterns. See ShiftTag.

array

Employee names that cannot be assigned to this shift.

number

Financial cost for assigning this shift. Minimized in partial planning.

object

Geographic location of the shift ({lat, lon}). Used with an employee’s home location to optimize/penalize travel time.

array

Rest requirements after this shift. See Rest.

ShiftTag

{ "name": "NIGHT" }

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": [...]
}

string

required

Unique identifier for the employee.

array

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

array

Available time ranges (ISO 8601 interval format).

array

Preferred shift names.

array

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

object

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

number

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

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": { ... }
}

string

required

Rule type: COUNTER or SEQUENCE.

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.

integer

Minimum count or sequence length.

integer

Maximum count or sequence length.

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

object

Time scope with from/to or rolling duration.

array

Filter to specific shift tags.

Rule

Conditional rule triggered when threshold exceeded.

Requirement

Skill requirements across multiple shifts.

{
  "shifts": ["shift-1", "shift-2"],
  "skill": "supervisor",
  "value": 1
}

array

required

Shift names this requirement applies to.

string

required

Required skill name.

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

array

required

Employees in this fairness group.

array

required

Shifts to distribute fairly.

object

Evaluation period with from and to dates.

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
}

string

required

SINGLE_DAY or MULTI_DAY.

string

required

PREFERRED, UNPREFERRED, or PROHIBITED.

array

Sequence elements with type (ON/OFF) and tags (tag list).

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
}

string

required

Unique demand identifier.

datetime

required

Demand period start.

datetime

required

Demand period end.

array

required

Required skills for this demand period.

integer

Minimum employees required.

integer

Maximum employees allowed.

Assignment

Pre-defined employee-shift pairings.

{
  "shift": "morning-1",
  "employee": "Alice",
  "locked": true
}

string

required

Shift name to assign.

string

required

Employee name to assign.

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": { ... }
}

boolean

default:"true"

Enforce availability as hard constraint.

boolean

default:"true"

Enforce skill matching as hard constraint.

boolean

default:"true"

Enforce blocklist as hard constraint.

boolean

default:"false"

Allow unfilled shifts in solution.

boolean

Penalize employees with no assignments.

object

Explanation settings. See ExplanationOptions.

object

Weekend definition. See IdleWeekendDefinition.

boolean

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

boolean

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

ExplanationOptions

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

boolean

default:"false"

Enable alternative generation.

boolean

default:"false"

Exclude infeasible alternatives from response.

boolean

default:"false"

Compute alternatives only for unassigned shifts.

IdleWeekendDefinition

{
  "fromDayOfWeek": "FRIDAY",
  "fromTime": "19:00:00",
  "toDayOfWeek": "SUNDAY",
  "toTime": "23:00:00",
  "restTime": "PT36H"
}

string

required

Weekend start day.

string

required

Weekend start time (HH:mm:ss).

string

required

Weekend end day.

string

required

Weekend end time (HH:mm:ss).

string (ISO 8601 duration)

Minimum consecutive rest for idle weekend.

Rest

Rest period constraints.

{
  "tags": ["NIGHT"],
  "sequence": "AFTER",
  "min": "PT11H",
  "minConsecutive": "PT8H"
}

array

Shift tags that trigger this rest.

array

Shift tags excluded from rest calculation.

string

AFTER, BEFORE, or CUMULATIVE relative to the triggering shift.

object

Fixed period for periodic rest rules.

string

Rolling period: WEEKLY, DAILY.

string (ISO 8601 duration)

Minimum total rest.

string (ISO 8601 duration)

Maximum total rest.

string (ISO 8601 duration)

Minimum uninterrupted rest.

integer

Maximum rest occurrences.

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