Skip to main content
This guide covers breaking changes and new features when migrating to Fill API v2.

​
Breaking Changes

​
Request Level

The contracts list has been deprecated. Use rules instead for defining labor constraints.
DeprecatedReplacementNotes
contractsrulesDefine constraints using the new Rule system

​
Employee Changes

DeprecatedReplacementNotes
periodRulesrulesUse global rules with employee filtering
contractrulesReference rules instead of contracts

​
Shift Changes

DeprecatedReplacementNotes
valuemin and maxSpecify exact staffing range
criticalmin and maxUse min for required staffing
employeesassignmentsPre-assign with Assignment objects
lockedassignmentsSet locked: true in Assignment
blacklistblocklistRenamed for inclusive terminology
New field tags added to shifts for grouping in rules (e.g., EARLY, NIGHT).

​
New Features

​
Rules

Rules replace period rules and contracts with a more flexible system for counters and sequences. 
{
  "period": {
    "from": "2024-03-06T08:00:00",
    "to": "2024-03-10T17:00:00"
  },
  "maxWorkingDays": 4
}
Use tags in rules to apply constraints to specific shift types only.
See Rules documentation for complete examples.

​
Patterns

Define preferred or prohibited sequences of shifts across single or multiple days.
Pattern Example
{
  "type": "MULTI_DAY",
  "satisfy": "PROHIBITED",
  "elements": [
    { "type": "ON", "tags": ["LATE"] },
    { "type": "ON", "tags": ["EARLY"] }
  ]
}
See Patterns documentation for complete examples.

​
Demands

Specify staffing requirements independent of shift structure, allowing flexible coverage optimization.
Demand Example
{
  "demands": [
    {
      "name": "Peak hours",
      "from": "2022-01-01T14:00:00",
      "to": "2022-01-01T18:00:00",
      "min": 3,
      "max": 5
    }
  ]
}
See Demands documentation for complete examples.

​
Assignments

Granularly specify pre-defined shift assignments with optional locking.
Assignment Example
{
  "assignments": [
    {
      "shift": "morning-1",
      "employee": "Alice",
      "locked": true
    }
  ]
}
See Lock Plan documentation for complete examples.

​
Migration Checklist

1

Update shift definitions

Replace value with min and max properties:
// Before
{ "value": 2 }

// After
{ "min": 2, "max": 2 }
2

Convert contracts to rules

Migrate contract-based constraints to the new Rule format with constraint and type fields.
3

Update employee references

Remove contract and periodRules from employees. Define rules at the request level instead.
4

Rename blacklist to blocklist

Update any blacklist fields on shifts to blocklist.
5

Convert locked shifts to assignments

Replace employees and locked on shifts with the assignments array.