Employee priority

Employees have different levels of seniority and responsibility and can be assigned different priority levels.

Rules related to employees' preferences and working hours are more likely to be honored for employees with higher priorities.

Employee contracts can also have priorities. Contract priorities are applied to the all the employees with those contracts. See Employee contracts for more details.

1. Defining employee priority

Priority is defined per employee:

{
  "employees": [
    {
      "id": "Ann",
      "priority": "LOW"
    },
    {
      "id": "Beth",
      "priority": "NORMAL"
    },
    {
      "id": "Carl",
      "priority": "HIGH"
    },
    {
      "id": "Dan",
      "priority": "CRITICAL"
    }
  ]
}

The priority can be CRITICAL, HIGH, NORMAL, or LOW.

CRITICAL is the highest priority and LOW is the lowest priority.

An employee with a CRITICAL priority is more likely to have their preferences met than an employee with a lower priority.

2. Employee priority example

In the following example, there are three employees and two shifts. Ann’s priority is LOW, Beth’s priority is NORMAL, and Carl’s priority is HIGH.

All three employees have preferredTimeSpans for when they prefer to work that match the two available shifts.

Because Beth and Carl have higher priorities than Ann, they are assigned the shifts.

employee priority

  • 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": "Employee priority example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "priority": "LOW",
        "preferredTimeSpans": [
          {
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "priority": "NORMAL",
        "preferredTimeSpans": [
          {
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "priority": "HIGH",
        "preferredTimeSpans": [
          {
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "MON 1",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z"
      },
      {
        "id": "MON 2",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16: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>
{
  "metadata": {
    "id": "f5a3b23c-f040-4228-88c9-d87b23299584",
    "originId": "f5a3b23c-f040-4228-88c9-d87b23299584",
    "name": "Employee priority example",
    "submitDateTime": "2026-02-09T05:52:15.439778882Z",
    "startDateTime": "2026-02-09T05:54:00.000699439Z",
    "activeDateTime": "2026-02-09T05:54:00.092894632Z",
    "solverStatus": "SOLVING_ACTIVE",
    "score": "0hard/0medium/2400soft",
    "tags": [
      "system.type:from-request",
      "system.profile:Standard profile"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "MON 1",
        "employee": "Carl"
      },
      {
        "id": "MON 2",
        "employee": "Beth"
      }
    ],
    "employees": [
      {
        "id": "Ann",
        "metrics": {
          "assignedShifts": 0,
          "durationWorked": "PT0S",
          "durationOfTimePreferencesMet": "PT0S"
        }
      },
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 1,
          "durationWorked": "PT8H",
          "durationOfTimePreferencesMet": "PT8H"
        }
      },
      {
        "id": "Carl",
        "metrics": {
          "assignedShifts": 1,
          "durationWorked": "PT8H",
          "durationOfTimePreferencesMet": "PT8H"
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 3,
    "shifts": 2,
    "pinnedShifts": 0,
    "mandatoryShifts": 2,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 2,
    "unassignedShifts": 0,
    "disruptionPercentage": 0,
    "averageDurationOfEmployeesPreferencesMet": "PT5H20M",
    "minimumDurationOfPreferencesMetAcrossEmployees": "PT8H",
    "activatedEmployees": 2,
    "assignedMandatoryShifts": 2
  },
  "run": {
    "id": "f5a3b23c-f040-4228-88c9-d87b23299584",
    "originId": "f5a3b23c-f040-4228-88c9-d87b23299584",
    "name": "Employee priority example",
    "submitDateTime": "2026-02-09T05:52:15.439778882Z",
    "startDateTime": "2026-02-09T05:54:00.000699439Z",
    "activeDateTime": "2026-02-09T05:54:00.092894632Z",
    "solverStatus": "SOLVING_ACTIVE",
    "score": "0hard/0medium/2400soft",
    "tags": [
      "system.type:from-request",
      "system.profile:Standard profile"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

3. Constraints influenced by employee priority

The following constraints multiply their score impact by the employee’s priority. Violations of these constraints are penalized or rewarded more for higher-priority employees, making the solver more likely to satisfy them.

3.1. Employee availability

3.2. Pairing employees

3.3. Replanning

3.4. Shift assignments

3.5. Shift rotations and patterns

3.6. Shift travel and locations

3.7. Shift type diversity

3.8. Skills and risk factors

3.9. Time off

3.10. Work limits

Next