Shift types worked per period

Employees' contracts can impose limits on the number of different shift types employees work in a specific period, for instance, when there are morning, afternoon, and night shifts, employees might only be permitted to work 2 of the 3 shift types to prevent unnecessary disruption to their schedules.

Prerequisites

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

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
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 shift types worked per period

Period rules to define the maximum number of shift types worked per period are defined in contracts:

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max2ShiftTypesPerWeek",
          "period": "WEEK",
          "satisfiability": "REQUIRED",
          "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
          "shiftTypesWorkedMax": 2
        }
      ]
    }
  ]
}

PeriodRules must include an ID.

period sets the period the rule applies to, for instance, DAY, WEEK, MONTH, SCHEDULE.

Further information about period:

DAY spans a single day and occurs every day in the schedule.

WEEK spans 7 days and occurs every week (including partial weeks) in the schedule. The default start of the week is Monday, but this can be overridden to any day in the week:

{
  "scheduleParameterization": {
    "weekStart": "THURSDAY"
  }
}

MONTH spans the entire month. MONTH has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.

SCHEDULE spans the entire schedule.

You can define custom periods to apply to this rule in the following way:

{
  "scheduleParameterization": {
    "periods": [
      {
        "id": "PAY_PERIOD",
        "dateSpans": [
          {
            "start": "2023-01-01",
            "end": "2023-01-15"
          }
        ]
      }
    ]
  }
}

The start and end dates are inclusive.

Learn about counting days in period rules:

By default, period rules count shifts within the defined period if the shift starts within the defined period. For instance, if you define a rule that an employee can only work 1 shift a day, a night shift that started on the previous day but ends the following morning will not be counted and another shift might be assigned on the same day as the night shift ended.

To change this behavior change the field periodShiftOverlapKind from START_ONLY to START_AND_END.

{
  "periodRules": [
    {
      "id": "Max8HoursPerDayFullTime",
      "period": "DAY",
      "minutesWorkedMax": 480,
      "satisfiability": "REQUIRED",
      "periodShiftOverlapKind": "START_AND_END"
    }
}

shiftTypesTagCategories specifies which tags the rule applies to.

Shifts can only be tagged with one of the tags specified by shiftTypesTagCategories.

{
  "shifts": [
    {
      "id": "Mon AM",
      "start": "2027-02-01T06:00:00Z",
      "end": "2027-02-01T14:00:00Z",
      "tags": ["Early"]
    }
  ]
}

shiftTypesWorkedMax sets the maximum number of shift types the employee can work in the specified period.

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

2. Required shift types worked per period

When the satisfiability of the rule is REQUIRED, the Shift types worked per period not in required range for employee hard constraint is invoked, which makes sure the number of shift types worked does not exceed the limit specified in shiftTypesWorkedMax.

Shifts will be left unassigned if assigning them would break the Shift types worked per period not in required range for employee constraint.

In the following example, there are 5 shifts, 3 shift types, 1 employee, and a rule with a required satisfiability that states employees can work a maximum of 2 different shift types.

Ann is assigned to 2 different shift types (Early and Afternoon), and 1 shift (of type Night) is left unassigned to avoid breaking the Shift types worked per period not in required range for employee hard constraint.

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 shift types worked per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max2ShiftTypesPerWeek",
            "period": "WEEK",
            "satisfiability": "REQUIRED",
            "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
            "shiftTypesWorkedMax": 2
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T14:00:00Z",
        "tags": ["Early"]
      },
      {
        "id": "Tue PM",
        "start": "2027-02-02T14:00:00Z",
        "end": "2027-02-02T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Wed Night",
        "start": "2027-02-03T22:00:00Z",
        "end": "2027-02-04T06:00:00Z",
        "tags": ["Night"]
      },
      {
        "id": "Thu PM",
        "start": "2027-02-04T14:00:00Z",
        "end": "2027-02-04T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Fri AM",
        "start": "2027-02-05T06:00:00Z",
        "end": "2027-02-05T14:00:00Z",
        "tags": ["Early"]
      }
    ]
  }
}

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",
    "name": "Required shift types worked per period example",
    "submitDateTime": "2025-06-17T06:10:58.866327174Z",
    "startDateTime": "2025-06-17T06:11:10.789858179Z",
    "activeDateTime": "2025-06-17T06:11:10.934340602Z",
    "completeDateTime": "2025-06-17T06:11:42.078637013Z",
    "shutdownDateTime": "2025-06-17T06:11:42.369370316Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Tue PM",
        "employee": "Ann"
      },
      {
        "id": "Wed Night"
      },
      {
        "id": "Thu PM",
        "employee": "Ann"
      },
      {
        "id": "Fri AM",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 1,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to only 2 shifts types and a third shift type left unassigned.

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

KPIs provides the KPIs for the output including:

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

3. Preferred shift types worked per period

When the satisfiability of the rule is PREFERRED, the Shift types worked per period not in preferred range for employee soft constraint is invoked.

With a satisfiability of PREFERRED a shiftTypesWorkedMin value can also be provided to set the preferred minimum number of shifts worked.

{
  "contracts": [
    {
      "id": "fullTimeContract",
      "periodRules": [
        {
          "id": "Max2ShiftTypesPerWeek",
          "period": "WEEK",
          "satisfiability": "PREFERRED",
          "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
          "shiftTypesWorkedMin": 2,
          "shiftTypesWorkedMax": 3
        }
      ]
    }
  ]
}

If there is no alternative, shifts will still be assigned to employees even if assigning shifts takes the number of shift types below the limit set in shiftTypesWorkedMin or exceeds the limit set in shiftTypesWorkedMax and breaks the Shift types worked per period not in preferred range for employee soft constraint. This constraint adds a soft penalty for matches to the constraint, incentivizing Timefold to find an alternative solution.

In the following example, there are 5 shifts, 3 shift types, 1 employee, and a rule with a preferred satisfiability that states employees should only work 2 different shift types in the period.

Ann is assigned to all 3 shift types and a soft penalty is applied to the run score.

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 shift types worked per period example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "periodRules": [
          {
            "id": "Max2ShiftTypesPerWeek",
            "period": "WEEK",
            "satisfiability": "PREFERRED",
            "shiftTypesTagCategories": ["Early", "Afternoon", "Night"],
            "shiftTypesWorkedMax": 2
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon AM",
        "start": "2027-02-01T06:00:00Z",
        "end": "2027-02-01T14:00:00Z",
        "tags": ["Early"]
      },
      {
        "id": "Tue PM",
        "start": "2027-02-02T14:00:00Z",
        "end": "2027-02-02T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Wed Night",
        "start": "2027-02-03T22:00:00Z",
        "end": "2027-02-04T06:00:00Z",
        "tags": ["Night"]
      },
      {
        "id": "Thu PM",
        "start": "2027-02-04T14:00:00Z",
        "end": "2027-02-04T22:00:00Z",
        "tags": ["Afternoon"]
      },
      {
        "id": "Fri AM",
        "start": "2027-02-05T06:00:00Z",
        "end": "2027-02-05T14:00:00Z",
        "tags": ["Early"]
      }
    ]
  }
}

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",
    "name": "Preferred shift types worked per period example",
    "submitDateTime": "2025-06-17T06:28:39.022547701Z",
    "startDateTime": "2025-06-17T06:28:56.959955839Z",
    "activeDateTime": "2025-06-17T06:28:57.296433959Z",
    "completeDateTime": "2025-06-17T06:29:28.566253338Z",
    "shutdownDateTime": "2025-06-17T06:29:28.804020984Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-960soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon AM",
        "employee": "Ann"
      },
      {
        "id": "Tue PM",
        "employee": "Ann"
      },
      {
        "id": "Wed Night",
        "employee": "Ann"
      },
      {
        "id": "Thu PM",
        "employee": "Ann"
      },
      {
        "id": "Fri AM",
        "employee": "Ann"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  }
}

modelOutput contains the schedule with Ann assigned to shifts with 3 different shift types.

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

KPIs provides the KPIs for the output including:

{
  "assignedShifts": 5,
  "activatedEmployees": 1,
  "assignedMandatoryShifts": 5
}

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
See other options related to Shift type diversity.

Shift types worked per period

Prerequisites

1. Define shift types worked per period

2. Required shift types worked per period

3. Preferred shift types worked per period

Next