Demand-based scheduling

By default in employee shift scheduling, shifts are assigned with shift slot scheduling.

In shift slot scheduling, the number of shifts that are required to cover the workload is known, and only that number of shifts are created. Timefold uses the constraints of the scheduling problem: availability, cost management, employee preferences, shift patterns, and contractual obligations, etc, to determine which employees are assigned to which shifts.

Shifts can also be assigned with hourly demand scheduling.

In hourly demand scheduling, the hourly demand (how many employees are needed) is known. There is a pool of shifts that can be chosen from to meet the demand.

The pool of shifts may have different start times and durations.

Timefold uses the constraints of the scheduling problem: availability, cost management, employee preferences, shift patterns, and contractual obligations, etc, to determine which shifts to schedule to meet the demand curve and which employees to assign to those shifts.

Shifts that are not required to meet the demand can be left unassigned or distributed evenly across the demand curve.

The demand curve in hourly demand scheduling can be defined with the maximum or minimum number of required employees at specific times, leading to assigning fewer employees during quiet periods when the full complement of employees are not required, and alternatively, assigning more employees during busy periods.

If there is an hourly demand for a maximum of 1 employee between 08:00 and 09:00, and an hourly demand for a maximum of 3 employees between 09:00 and 10:00 and there are sufficient shifts that start at 08:00 and 09:00 with a duration longer than 2 hours, 1 employee will be assigned a shift that starts at 08:00 and 2 more employees will be assigned shifts that start at 09:00.

The 1 employee who starts at 08:00 meets the demand for a maximum of 1 employee between 08:00 and 09:00.

The 1 employee who starts at 08:00 and the 2 employees who starts at 09:00 meets the demand for a maximum of 3 employees between 09:00 and 10:00.

The minimumMaximumShiftsPerHourlyDemand global rules define the hourly demand for shifts.

Prerequisites

Learn how to configure an API Key to run the examples in this guide:

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

In the examples, replace <API_KEY> with the API Key you just copied.

1. Define hourly shift demand

minimumMaximumShiftsPerHourlyDemand is defined in globalRules:

{
  "globalRules": {
    "minimumMaximumShiftsPerHourlyDemand": [
      {
        "id": "HourlyDemand",
        "demandDetails": [
          {
            "startDateTime": "2027-02-01T07:00:00Z",
            "endDateTime": "2027-02-01T08:00:00Z",
            "maxDemand": 1
          },
          {
            "startDateTime": "2027-02-01T08:00:00Z",
            "endDateTime": "2027-02-01T09:00:00Z",
            "maxDemand": 2
          },
          {
            "startDateTime": "2027-02-01T16:00:00Z",
            "endDateTime": "2027-02-01T17:00:00Z",
            "maxDemand": 2
          },
          {
            "startDateTime": "2027-02-01T17:00:00Z",
            "endDateTime": "2027-02-01T18:00:00Z",
            "maxDemand": 1
          }
        ],
        "satisfiability": "REQUIRED"
      }
    ]
  }
}

The hourly demand in this example, states the following:

  • Between 07:00 and 08:00 there must be a maximum of 1 employee.

  • Between 08:00 and 09:00 there must be a maximum of 2 employees.

  • Between 16:00 and 17:00 there must be a maximum of 2 employees.

  • Between 17:00 and 18:00 there must be a maximum of 1 employee.

minimumMaximumShiftsPerHourlyDemand must include an id.

demandDetails must include startDateTime and endDateTime and the maxDemand for the specified time for each time period when the hourly demand is defined. startDateTime and endDateTime must be a valid ISO 8601 date-time.

minimumMaximumShiftsPerHourlyDemand can include or exclude shifts based on shift tags:

{
  "minimumMaximumShiftsPerHourlyDemand": [
    {
      "id": "HourlyDemand",
      "includeShiftTags": [
        "Part-time"
      ],
      "demandDetails": [
        {
          "startDateTime": "2027-02-01T09:00:00Z",
          "endDateTime": "2027-02-01T10:00:00Z",
          "maxDemand": 1
        }
      ],
      "satisfiability": "REQUIRED"
    }
  ]
}
Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

The satisfiability of the rule can be REQUIRED or PREFERRED. If omitted, REQUIRED is the default.

2. Required hourly shift demand

When the satisfiability of the rule is REQUIRED, the Shifts worked not in required hourly demand range hard constraint is invoked, making sure the number of shifts assigned does not exceed the limit set in maxDemand.

Shifts will be left unassigned if assigning the shifts breaks the constraint.

In the following example, the following hourly demand has been specified:

  • Between 07:00 and 08:00 there must be a maximum of 1 employee.

  • Between 08:00 and 09:00 there must be a maximum of 2 employees.

  • Between 16:00 and 17:00 there must be a maximum of 2 employees.

  • Between 17:00 and 18:00 there must be a maximum of 1 employee.

There are 5 available employees, and 12 possible shifts.

The satisfiability of the rule is required.

4 employees are assigned shifts. 1 employee is not assigned a shift to avoid breaking the Shifts worked not in required hourly demand range hard constraint by exceeding the demand curve.

8 shifts are left unassigned.

required hourly shift demand

  • Input

  • Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]
{
  "config": {
    "run": {
      "name": "Required hourly shift demand example"
    }
  },
  "modelInput": {
    "globalRules": {
      "minimumMaximumShiftsPerHourlyDemand": [
        {
          "id": "HourlyDemand",
          "demandDetails": [
            {
              "startDateTime": "2027-02-01T07:00:00Z",
              "endDateTime": "2027-02-01T08:00:00Z",
              "maxDemand": 1
            },
            {
              "startDateTime": "2027-02-01T08:00:00Z",
              "endDateTime": "2027-02-01T09:00:00Z",
              "maxDemand": 2
            },
            {
              "startDateTime": "2027-02-01T16:00:00Z",
              "endDateTime": "2027-02-01T17:00:00Z",
              "maxDemand": 2
            },
            {
              "startDateTime": "2027-02-01T17:00:00Z",
              "endDateTime": "2027-02-01T18:00:00Z",
              "maxDemand": 1
            }
          ],
          "satisfiability": "REQUIRED"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann"
      },
      {
        "id": "Beth"
      },
      {
        "id": "Carl"
      },
      {
        "id": "Dan"
      },
      {
        "id": "Elsa"
      }
    ],
    "shifts": [
      {
        "id": "7-15 A",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "7-15 B",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "7-15 C",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "8-16 A",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "8-16 B",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "8-16 C",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "9-17 A",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "9-17 B",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "9-17 C",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "10-18 A",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      },
      {
        "id": "10-18 B",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      },
      {
        "id": "10-18 C",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      }
    ]
  }
}
To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>
{
  "run": {
    "id": "ID",
    "parentId": null,
    "originId": "ID",
    "name": "Required hourly shift demand example",
    "submitDateTime": "2025-06-26T04:33:10.966491445Z",
    "startDateTime": "2025-06-26T04:33:23.425140272Z",
    "activeDateTime": "2025-06-26T04:33:23.617726513Z",
    "completeDateTime": "2025-06-26T04:33:54.668159337Z",
    "shutdownDateTime": "2025-06-26T04:33:54.855922554Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-8medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "7-15 A",
        "employee": "Ann"
      },
      {
        "id": "7-15 B"
      },
      {
        "id": "7-15 C"
      },
      {
        "id": "8-16 A",
        "employee": "Beth"
      },
      {
        "id": "8-16 B"
      },
      {
        "id": "8-16 C"
      },
      {
        "id": "9-17 A",
        "employee": "Carl"
      },
      {
        "id": "9-17 B",
        "employee": "Dan"
      },
      {
        "id": "9-17 C"
      },
      {
        "id": "10-18 A"
      },
      {
        "id": "10-18 B"
      },
      {
        "id": "10-18 C"
      }
    ]
  },
  "inputMetrics": {
    "employees": 5,
    "shifts": 12,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 8,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 4,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with the hourly demand satisfied.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 4,
  "unassignedShifts": 8,
  "activatedEmployees": 4,
  "assignedMandatoryShifts": 4
}

3. Preferred hourly shift demand

When the satisfiability of the rule is PREFERRED, the Shifts worked not in preferred hourly demand range soft constraint is invoked.

With preferred satisfiability, you can define minDemand for the minimum hourly demand in combination with maxDemand or separately.

{
  "globalRules": {
    "minimumMaximumShiftsPerHourlyDemand": [
      {
        "id": "HourlyDemand",
        "demandDetails": [
          {
            "startDateTime": "2027-02-01T07:00:00Z",
            "endDateTime": "2027-02-01T08:00:00Z",
            "minDemand": 1
          },
          {
            "startDateTime": "2027-02-01T08:00:00Z",
            "endDateTime": "2027-02-01T09:00:00Z",
            "minDemand": 2
          },
          {
            "startDateTime": "2027-02-01T16:00:00Z",
            "endDateTime": "2027-02-01T17:00:00Z",
            "minDemand": 2
          },
          {
            "startDateTime": "2027-02-01T17:00:00Z",
            "endDateTime": "2027-02-01T18:00:00Z",
            "minDemand": 1
          }
        ],
        "satisfiability": "PREFERRED"
      }
    ]
  }
}

Employees might be assigned shifts that are do not meet the demand, but the Shifts worked not in preferred hourly demand range soft constraint adds a soft penalty to the run score for any matches to the constraint, incentivizing Timefold to find an alternative solution.

In the following example, the following hourly demand has been specified:

  • Between 07:00 and 08:00 there must be a minimum of 1 employee.

  • Between 08:00 and 09:00 there must be a minimum of 2 employees.

  • Between 16:00 and 17:00 there must be a minimum of 2 employees.

  • Between 17:00 and 18:00 there must be a minimum of 1 employee.

There are 5 available employees, and 12 possible shifts.

The satisfiability of the rule is preferred.

All 5 employees are assigned shifts.

7 shifts are left unassigned.

preferred hourly shift demand

  • Input

  • Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]
{
  "config": {
    "run": {
      "name": "Preferred hourly shift demand example"
    }
  },
  "modelInput": {
    "globalRules": {
      "minimumMaximumShiftsPerHourlyDemand": [
        {
          "id": "HourlyDemand",
          "demandDetails": [
            {
              "startDateTime": "2027-02-01T07:00:00Z",
              "endDateTime": "2027-02-01T08:00:00Z",
              "minDemand": 1
            },
            {
              "startDateTime": "2027-02-01T08:00:00Z",
              "endDateTime": "2027-02-01T09:00:00Z",
              "minDemand": 2
            },
            {
              "startDateTime": "2027-02-01T16:00:00Z",
              "endDateTime": "2027-02-01T17:00:00Z",
              "minDemand": 2
            },
            {
              "startDateTime": "2027-02-01T17:00:00Z",
              "endDateTime": "2027-02-01T18:00:00Z",
              "minDemand": 1
            }
          ],
          "satisfiability": "PREFERRED"
        }
      ]
    },
    "employees": [
      {
        "id": "Ann"
      },
      {
        "id": "Beth"
      },
      {
        "id": "Carl"
      },
      {
        "id": "Dan"
      },
      {
        "id": "Elsa"
      }
    ],
    "shifts": [
      {
        "id": "7-15 A",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "7-15 B",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "7-15 C",
        "start": "2027-02-01T07:00:00Z",
        "end": "2027-02-01T15:00:00Z"
      },
      {
        "id": "8-16 A",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "8-16 B",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "8-16 C",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "9-17 A",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "9-17 B",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "9-17 C",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "10-18 A",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      },
      {
        "id": "10-18 B",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      },
      {
        "id": "10-18 C",
        "start": "2027-02-01T10:00:00Z",
        "end": "2027-02-01T18:00:00Z"
      }
    ]
  }
}
To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>
{
  "run": {
    "id": "ID",
    "parentId": null,
    "originId": "ID",
    "name": "Preferred hourly shift demand example",
    "submitDateTime": "2025-06-26T04:50:31.839620831Z",
    "startDateTime": "2025-06-26T04:50:42.409633761Z",
    "activeDateTime": "2025-06-26T04:50:42.526984212Z",
    "completeDateTime": "2025-06-26T04:51:13.458225717Z",
    "shutdownDateTime": "2025-06-26T04:51:13.628499812Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-7medium/-480soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "7-15 A",
        "employee": "Beth"
      },
      {
        "id": "7-15 B"
      },
      {
        "id": "7-15 C"
      },
      {
        "id": "8-16 A",
        "employee": "Dan"
      },
      {
        "id": "8-16 B",
        "employee": "Elsa"
      },
      {
        "id": "8-16 C"
      },
      {
        "id": "9-17 A"
      },
      {
        "id": "9-17 B"
      },
      {
        "id": "9-17 C",
        "employee": "Ann"
      },
      {
        "id": "10-18 A"
      },
      {
        "id": "10-18 B",
        "employee": "Carl"
      },
      {
        "id": "10-18 C"
      }
    ]
  },
  "inputMetrics": {
    "employees": 5,
    "shifts": 12,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 7,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 5,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with the demand curve satisfied.

inputMetrics provides a breakdown of the inputs in the input dataset.

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 4,
  "unassignedShifts": 8,
  "activatedEmployees": 4,
  "assignedMandatoryShifts": 4
}

4. Balance shifts worked for the minimum hourly demand

When there are more shifts and available employees to assign to those shifts than are required by the hourly demand and you are using preferred satisfiability for minimumMaximumShiftsPerHourlyDemand with minDemand, the Balance shifts worked for minimum hourly demand soft constraint will attempt to distribute the shifts across the day rather than assigning them all at the same time.

If the demand is met exactly no soft score penalty is applied. Additional shifts above the minDemand attract a penalty, and the more unevenly the shifts are distributed, the higher the penalty, incentivizing Timefold to spread the additional shifts as evenly as possible across the demand curve.

If there are shifts that cover time periods with no hourly demand defined, these shifts are more likely to be assigned as they are not assigned a soft score penalty by the Balance shifts worked for minimum hourly demand soft constraint.

Next