Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
    • Pick-up and Delivery Routing
  • Platform
Try models
  • Employee Shift Scheduling
  • User guide
  • Input datasets
  • Model input
  • latest
    • latest
    • 1.20.x

Employee Shift Scheduling

    • Introduction
    • Getting started: Hello world
    • User guide
      • Terms
      • Use case guide
      • Planning AI concepts
      • Integration
      • Constraints
      • Understanding the API
      • Demo datasets
      • Input datasets
        • Model configuration
        • Model input
        • Planning window
      • Planning window
      • Time zones and Daylight Saving Time (DST)
      • Tags and tag types
      • Input validation
      • Metrics and optimization goals
      • Score analysis
      • Visualizations
    • Employee resource constraints
      • Employee contracts
      • Employee availability
      • Employee priority
      • Pairing employees
      • Shift travel and locations
      • Employee activation
      • Work limits
        • Minutes worked per period
        • Minutes worked in a rolling window
        • Minutes logged per period
        • Days worked per period
        • Days worked in a rolling window
        • Consecutive days worked
        • Shifts worked per period
        • Shifts worked in a rolling window
        • Weekend minutes worked per period
        • Weekends worked per period
        • Weekends worked in a rolling window
        • Consecutive weekends worked
      • Time off
        • Days off per period
        • Consecutive days off per period
        • Consecutive days off in a rolling window
        • Consecutive minutes off in a rolling window
        • Shifts to avoid close to day off requests
        • Consecutive weekends off per period
      • Shift rotations and patterns
        • Shift rotations
        • Single day shift sequence patterns
        • Minimize gaps between shifts
        • Multi-day shift sequence patterns
        • Daily shift pairings
        • Overlapping shifts
        • Shift start times differences
        • Minutes between shifts
      • Shift type diversity
        • Shift tag types
        • Shift types worked per period
        • Unique tags per period
      • Fairness
        • Balance time worked
        • Balance shift count
    • Shift service constraints
      • Alternative shifts
      • Cost management
      • Demand-based scheduling
      • Mandatory and optional shifts
      • Shift assignments
      • Skills and risk factors
    • Manual intervention
    • Recommendations
    • Real-time planning
    • Real-time planning (preview)
    • Scenarios
      • Configuring labor law compliance
      • Configuring employee well-being
    • Changelog
    • Upgrade to the latest version
    • Feature requests

Model input

The modelInput is where you add your data about available employees and the shifts to be scheduled and optimized.

The JSON shows an example modelInput. Note, most of the values are missing.

{
  "modelInput": {
    "tagTypes": [
      {
        "id": "tagTypeName"
      }
    ],
    "tags": [
      {
        "id": "tagName"
      }
    ],
    "contracts": [
      {
        "id": "string"
      }
    ],
    "employees": [
      {
        "id": "Ann"
      }
    ],
    "shifts": [
      {
        "id": "string"
      }
    ],
    "shiftGroups": [
      {
        "id": "string"
      }
    ],
    "employeeCostGroups": [
      {
        "id": "string"
      }
    ],
    "scheduleParameterization": {
      "weekStart": "MONDAY"
    },
    "globalRules": {
    },
    "planningWindow": {
      "start": "2024-02-05T00:00+01:00",
      "end": "2024-02-12T:00:00+01:00"
    }
  }
}
  • tagTypes and tags provide additional information about employees and shifts. See Tags and tag types, Shift travel and locations, Shift tag types, and Unique tags per period for specific examples.

  • contracts includes information about employees contracts and rules related to the hours employees work. See Employee contracts and Work limits for more details.

  • employees include information about employees, their availability, and skills. See Employee resource constraints for more details.

  • shifts includes information about the shifts to be assigned to employees. See Shift service constraints for more details.

  • shiftGroups includes information about alternative shifts in a group where only one or more of the shifts need to be assigned. see Alternative shifts for more details.

  • employeeCostGroups defines employee activation costs to help manage costs. see Employee activation for more details.

  • scheduleParameterization lets you define the first day of the week. See Work limits and Time off for more details.

  • globalRules define rules that apply to the entire schedule.

  • planningWindow is the period of time the schedule is being planned for. See Planning window for more details.

Next

  • See the full API spec or try the online API.

  • Learn more about employee shift scheduling from our YouTube playlist.

  • Learn about the Model configuration

  • Learn about configuration parameters and profiles.

  • © 2026 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default