Recommendations

Managing complex schedules for a large number of employees is a difficult task, and when an employee is suddenly unavailable to cover a shift they’ve been scheduled for, it can be difficult to know who to schedule in their place.

Timefold’s recommendations API can provide recommendations ordered by the best fit to cover a shift at the last minute.

This guide explains recommendations with the following examples.

Recommendations for a shift
Recommendations and employee skills
Recommendations with employee preferences

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for this model:

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 current model.

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

1. Recommendations for a shift

In the following example, Ann and Beth have been assigned shifts, but Ann has called in sick for her shift.

Timefold’s recommendations API can provide recommendations for the best employee to assign to Ann’s shift.

1.1. The recommendations input dataset

A recommendation input dataset includes the following:

1.1.1. Max number of recommendations

The maximum number of employees to recommend for a shift:

{
  "maxNumberOfRecommendations": 2
}

1.1.2. Fit shift ID

The ID of the shift the recommended employee will be assigned.

{
  "fitShiftId": "2027-02-01"
}

1.1.3. Model input

The model input must include the employees and the shifts.

{
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-02T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-a",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "2027-02-01-b",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "employee": "Beth"
      }
    ]
  }
}

Ann is unavailable for her shift, so an unavailability time span has been added for Ann:

{
  "id": "Ann",
  "unavailableTimeSpans": [
    {
      "start": "2027-02-01T00:00:00Z",
      "end": "2027-02-02T00:00:00Z"
    }
  ],
  "availableTimeSpans": [
    {
      "start": "2027-02-02T00:00:00Z",
      "end": "2027-02-08T00:00:00Z"
    }
  ]
}

Learn more about Employee availability.

Any shifts that are already assigned must include the employee ID of the employee they are assigned to. Shifts that have been dropped by an employee do not include an employee ID. In this case, shift 2027-02-01-a was assigned to Ann, but Ann has called in sick, so no employee ID is included.

{
  "shifts": [
    {
      "id": "2027-02-01-a",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z"
    },
    {
      "id": "2027-02-01-b",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "employee": "Beth"
    }
  ]
}

1.2. Submit the input dataset

Submit the recommendations input dataset to the API endpoint: /v1/schedules/recommendations/recommend-employees.

The HTTP response provides the recommendations.

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/recommendations/recommend-employees [email protected]

{
  "maxNumberOfRecommendations": 2,
  "fitShiftId": "2027-02-01-a",
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-02T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-a",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z"
      },
      {
        "id": "2027-02-01-b",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "employee": "Beth"
      }
    ]
  }
}

{
  "recommendations": [
    {
      "employeeId": "Carl",
      "scoreDiff": "0hard/1medium/0soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    },
    {
      "employeeId": "Dan",
      "scoreDiff": "0hard/1medium/0soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    }
  ]
}

modelOutput contains two recommendations to cover shift 2027-02-01-a.

1.3. The recommendations

There are two recommendations for this input dataset: Dan and Carl.

Each recommendation includes the following:

The employee: The employee being recommended.
The scoreDiffs: The overall score difference implementing the recommendation will have.
The constraintDiffs: The score difference to individual constraints.

In this case, the recommendation includes:

{
  "score": "0hard/1medium/0soft",
  "constraintName": "Unassigned mandatory shift"
}

Which indicates the medium score has improved by 1, because the shift is no longer unassigned.

2. Recommendations and employee skills

In the previous example, any one of the available employees could have been assigned to the shift Ann dropped.

However, employees generally have different skills and availability which could help determine which employee is considered the best fit.

In the following example, Ann is a shift supervisor and the shift that needs to be filled must be filled by another shift supervisor.

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/recommendations/recommend-employees [email protected]

{
  "maxNumberOfRecommendations": 2,
  "fitShiftId": "2027-02-01-a",
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-02T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-a",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "requiredSkills": [
          "supervisor"
        ]
      },
      {
        "id": "2027-02-01-b",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "employee": "Beth"
      }
    ]
  }
}

{
  "recommendations": [
    {
      "employeeId": "Dan",
      "scoreDiff": "0hard/1medium/0soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    },
    {
      "employeeId": "Elsa",
      "scoreDiff": "0hard/1medium/0soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    }
  ]
}

modelOutput contains two recommendations to cover shift 2027-02-01-a.

This time the recommendations are for Dan and Elsa who both have the "supervisor" skill.

3. Recommendations with employee preferences

Employees can define a range of preferences including unpreferred work times and who they prefer to work with.

In the following example, Dan prefers not to work on Mondays.

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/recommendations/recommend-employees [email protected]

{
  "maxNumberOfRecommendations": 2,
  "fitShiftId": "2027-02-01-a",
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "unavailableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-02T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Dan",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ],
        "unpreferredTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-02T00:00:00Z"
          }
        ]
      },
      {
        "id": "Elsa",
        "skills": [
          {
            "id": "supervisor"
          }
        ],
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      },
      {
        "id": "Flo",
        "availableTimeSpans": [
          {
            "start": "2027-02-01T00:00:00Z",
            "end": "2027-02-08T00:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "2027-02-01-a",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "requiredSkills": [
          "supervisor"
        ]
      },
      {
        "id": "2027-02-01-b",
        "start": "2027-02-01T09:00:00Z",
        "end": "2027-02-01T17:00:00Z",
        "employee": "Beth"
      }
    ]
  }
}

{
  "recommendations": [
    {
      "employeeId": "Elsa",
      "scoreDiff": "0hard/1medium/0soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    },
    {
      "employeeId": "Dan",
      "scoreDiff": "0hard/1medium/-960soft",
      "constraintDiffs": [
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shift count"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance shifts worked for minimum hourly demand"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Balance time worked"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Consecutive days worked not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Costs per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Days worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee assignment disrupted on replanning"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have preferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not have required daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work during available time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee does not work required single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited risk factor associated with shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has prohibited shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred daily shift pairing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee has unpreferred shift near day off request"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is not paired with required employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with preferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with prohibited employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee is paired with unpreferred employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during preferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works during unavailable time"
        },
        {
          "score": "0hard/0medium/-960soft",
          "constraintName": "Employee works during unpreferred time"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works preferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works prohibited single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with non-matching required shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works shift with preferred shift tags"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred multi day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Employee works unpreferred single day shift sequence pattern"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Locations worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Maximum employee to shift travel distance exceeded"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize gaps between shifts for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimize travel distance"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minimum time between shifts including travel not met"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes between shifts not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Minutes worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Overlapping shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Preferred skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Prohibited employee assigned"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Required skill missing"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shift types worked per period not in required range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in preferred hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked not in required hourly demand range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in preferred range for employee"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Shifts worked per period not in required range for employee"
        },
        {
          "score": "0hard/1medium/0soft",
          "constraintName": "Unassigned mandatory shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unassigned optional shift"
        },
        {
          "score": "0hard/0medium/0soft",
          "constraintName": "Unpreferred employee assigned"
        }
      ]
    }
  ]
}

modelOutput contains two recommendations to cover shift 2027-02-01-a.

In this scenario, Dan is still recommended because only he and Elsa have the required skill of supervisor, but this time, Elsa is recommended first as she is the best fit, and Dan is recommended second.

In the second recommendation, we see:

{
  "score": "0hard/0medium/-960soft",
  "constraintName": "Employee works during unpreferred time"
}

This shows a soft score penalty because the recommendation would involve Dan working during an unpreferred time.

See the Employee Shift Scheduling User Guide
Understand the constraints of the Employee Shift Scheduling model.
See the full API spec or try the online API.
Manage schedules with Time zones and Daylight Saving Time (DST) changes.

Recommendations

Prerequisites

1. Recommendations for a shift

1.1. The recommendations input dataset

1.1.1. Max number of recommendations

1.1.2. Fit shift ID

1.1.3. Model input

1.2. Submit the input dataset

1.3. The recommendations

2. Recommendations and employee skills

3. Recommendations with employee preferences

Next