PlanSolve is still in pre-alpha – Features may change or break. Feedback welcome!
Back to Shift Solver Docs
Try Shift Solver

Quick Start Guide

Get up and running with the Shift Assignment Solver in minutes. Learn how to create your first optimization request and integrate it into your application.

Getting Started in 4 Steps

Step 1

Define Your Contracts

Set up contract types with working hour limits and constraints

  • Maximum and minimum working hours per week
  • Consecutive work day limits
  • Rest period requirements between shifts
  • Shift start time windows
Step 2

Create Your Shifts

Define the shifts that need to be staffed

  • Start and end times for each shift
  • Required skills for the shift
  • Number of employees needed (value)
  • Cost and priority levels
Step 3

Add Your Employees

Define available employees with their capabilities

  • Employee skills and qualifications
  • Contract type assignment
  • Availability dates
  • Shift preferences
Step 4

Configure Optimization

Set solver options and constraint weights

  • Time limits for optimization
  • Maximum iterations
  • Constraint importance weights
  • Fairness rules

Basic Example

Hospital Shift Assignment

{
  "name": "Hospital Shift Assignment",
  "description": "Weekly shift assignment for hospital staff",
  "contracts": [
    {
      "name": "FULL_TIME",
      "max": "PT40H",
      "min": "PT32H",
      "maxConsecutiveWorkDays": 5,
      "maxShiftsDay": 1,
      "minRestBetweenShiftsSameDay": "PT11H",
      "maxWorkingDays": 5,
      "latestShiftStart": "22:00:00",
      "earliestShiftStart": "06:00:00"
    }
  ],
  "shifts": [
    {
      "name": "morning_shift",
      "from": "2024-01-15T06:00:00",
      "to": "2024-01-15T14:00:00",
      "skills": ["nursing", "patient_care"],
      "cost": 25.0,
      "value": 3,
      "priority": 1,
      "assignedEmployee": null,
      "fullyStaffed": false
    },
    {
      "name": "afternoon_shift",
      "from": "2024-01-15T14:00:00",
      "to": "2024-01-15T22:00:00",
      "skills": ["nursing", "patient_care"],
      "cost": 30.0,
      "value": 3,
      "priority": 2,
      "assignedEmployee": null,
      "fullyStaffed": false
    },
    {
      "name": "night_shift",
      "from": "2024-01-15T22:00:00",
      "to": "2024-01-16T06:00:00",
      "skills": ["nursing", "patient_care", "emergency"],
      "cost": 35.0,
      "value": 2,
      "priority": 3,
      "assignedEmployee": null,
      "fullyStaffed": false
    }
  ],
  "employees": [
    {
      "name": "Alice Johnson",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care", "emergency"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["morning_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    },
    {
      "name": "Bob Smith",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["afternoon_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    },
    {
      "name": "Carol Davis",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care", "emergency"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["night_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    }
  ],
  "options": {
    "partialPlanning": false,
    "maxIterations": 1000,
    "timeLimit": 300
  },
  "weights": {
    "requiredSkills": 1000,
    "workingHours": 1000,
    "consecutiveWorkDays": 500,
    "restBetweenShifts": 500,
    "shiftPreferences": 100,
    "workloadBalance": 50,
    "costMinimization": 25,
    "fairness": 75
  }
}

API Integration Examples

cURL

Command Line
curl -X POST https://api.plansolve.com/api/shift/solve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{\n  "name": "Hospital Shift Assignment",\n  "description": "Weekly shift assignment for hospital staff",\n  "contracts": [\n    {\n      "name": "FULL_TIME",\n      "max": "PT40H",\n      "min": "PT32H",\n      "maxConsecutiveWorkDays": 5,\n      "maxShiftsDay": 1,\n      "minRestBetweenShiftsSameDay": "PT11H",\n      "maxWorkingDays": 5,\n      "latestShiftStart": "22:00:00",\n      "earliestShiftStart": "06:00:00"\n    }\n  ],\n  "shifts": [\n    {\n      "name": "morning_shift",\n      "from": "2024-01-15T06:00:00",\n      "to": "2024-01-15T14:00:00",\n      "skills": ["nursing", "patient_care"],\n      "cost": 25.0,\n      "value": 3,\n      "priority": 1,\n      "assignedEmployee": null,\n      "fullyStaffed": false\n    },\n    {\n      "name": "afternoon_shift",\n      "from": "2024-01-15T14:00:00",\n      "to": "2024-01-15T22:00:00",\n      "skills": ["nursing", "patient_care"],\n      "cost": 30.0,\n      "value": 3,\n      "priority": 2,\n      "assignedEmployee": null,\n      "fullyStaffed": false\n    },\n    {\n      "name": "night_shift",\n      "from": "2024-01-15T22:00:00",\n      "to": "2024-01-16T06:00:00",\n      "skills": ["nursing", "patient_care", "emergency"],\n      "cost": 35.0,\n      "value": 2,\n      "priority": 3,\n      "assignedEmployee": null,\n      "fullyStaffed": false\n    }\n  ],\n  "employees": [\n    {\n      "name": "Alice Johnson",\n      "contract": "FULL_TIME",\n      "skills": ["nursing", "patient_care", "emergency"],\n      "lastRestDate": "2024-01-14",\n      "availability": ["2024-01-15"],\n      "preference": ["morning_shift"],\n      "periodRules": [],\n      "shifts": [],\n      "totalWorkingHours": 0,\n      "consecutiveWorkingDays": 0,\n      "workingDays": 0\n    },\n    {\n      "name": "Bob Smith",\n      "contract": "FULL_TIME",\n      "skills": ["nursing", "patient_care"],\n      "lastRestDate": "2024-01-14",\n      "availability": ["2024-01-15"],\n      "preference": ["afternoon_shift"],\n      "periodRules": [],\n      "shifts": [],\n      "totalWorkingHours": 0,\n      "consecutiveWorkingDays": 0,\n      "workingDays": 0\n    },\n    {\n      "name": "Carol Davis",\n      "contract": "FULL_TIME",\n      "skills": ["nursing", "patient_care", "emergency"],\n      "lastRestDate": "2024-01-14",\n      "availability": ["2024-01-15"],\n      "preference": ["night_shift"],\n      "periodRules": [],\n      "shifts": [],\n      "totalWorkingHours": 0,\n      "consecutiveWorkingDays": 0,\n      "workingDays": 0\n    }\n  ],\n  "options": {\n    "partialPlanning": false,\n    "maxIterations": 1000,\n    "timeLimit": 300\n  },\n  "weights": {\n    "requiredSkills": 1000,\n    "workingHours": 1000,\n    "consecutiveWorkDays": 500,\n    "restBetweenShifts": 500,\n    "shiftPreferences": 100,\n    "workloadBalance": 50,\n    "costMinimization": 25,\n    "fairness": 75\n  }\n}'

JavaScript

Node.js / Browser
const response = await fetch('https://api.plansolve.com/api/shift/solve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
  "name": "Hospital Shift Assignment",
  "description": "Weekly shift assignment for hospital staff",
  "contracts": [
    {
      "name": "FULL_TIME",
      "max": "PT40H",
      "min": "PT32H",
      "maxConsecutiveWorkDays": 5,
      "maxShiftsDay": 1,
      "minRestBetweenShiftsSameDay": "PT11H",
      "maxWorkingDays": 5,
      "latestShiftStart": "22:00:00",
      "earliestShiftStart": "06:00:00"
    }
  ],
  "shifts": [
    {
      "name": "morning_shift",
      "from": "2024-01-15T06:00:00",
      "to": "2024-01-15T14:00:00",
      "skills": ["nursing", "patient_care"],
      "cost": 25.0,
      "value": 3,
      "priority": 1,
      "assignedEmployee": null,
      "fullyStaffed": false
    },
    {
      "name": "afternoon_shift",
      "from": "2024-01-15T14:00:00",
      "to": "2024-01-15T22:00:00",
      "skills": ["nursing", "patient_care"],
      "cost": 30.0,
      "value": 3,
      "priority": 2,
      "assignedEmployee": null,
      "fullyStaffed": false
    },
    {
      "name": "night_shift",
      "from": "2024-01-15T22:00:00",
      "to": "2024-01-16T06:00:00",
      "skills": ["nursing", "patient_care", "emergency"],
      "cost": 35.0,
      "value": 2,
      "priority": 3,
      "assignedEmployee": null,
      "fullyStaffed": false
    }
  ],
  "employees": [
    {
      "name": "Alice Johnson",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care", "emergency"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["morning_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    },
    {
      "name": "Bob Smith",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["afternoon_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    },
    {
      "name": "Carol Davis",
      "contract": "FULL_TIME",
      "skills": ["nursing", "patient_care", "emergency"],
      "lastRestDate": "2024-01-14",
      "availability": ["2024-01-15"],
      "preference": ["night_shift"],
      "periodRules": [],
      "shifts": [],
      "totalWorkingHours": 0,
      "consecutiveWorkingDays": 0,
      "workingDays": 0
    }
  ],
  "options": {
    "partialPlanning": false,
    "maxIterations": 1000,
    "timeLimit": 300
  },
  "weights": {
    "requiredSkills": 1000,
    "workingHours": 1000,
    "consecutiveWorkDays": 500,
    "restBetweenShifts": 500,
    "shiftPreferences": 100,
    "workloadBalance": 50,
    "costMinimization": 25,
    "fairness": 75
  }
})
});

const result = await response.json();
console.log('Job ID:', result.jobId);

.NET

C#
using System.Text.Json;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var requestData = {
          ""name"": ""Hospital Shift Assignment"",
          ""description"": ""Weekly shift assignment for hospital staff"",
          ""contracts"": [
            {
              ""name"": ""FULL_TIME"",
              ""max"": ""PT40H"",
              ""min"": ""PT32H"",
              ""maxConsecutiveWorkDays"": 5,
              ""maxShiftsDay"": 1,
              ""minRestBetweenShiftsSameDay"": ""PT11H"",
              ""maxWorkingDays"": 5,
              ""latestShiftStart"": ""22:00:00"",
              ""earliestShiftStart"": ""06:00:00""
            }
          ],
          ""shifts"": [
            {
              ""name"": ""morning_shift"",
              ""from"": ""2024-01-15T06:00:00"",
              ""to"": ""2024-01-15T14:00:00"",
              ""skills"": [""nursing"", ""patient_care""],
              ""cost"": 25.0,
              ""value"": 3,
              ""priority"": 1,
              ""assignedEmployee"": null,
              ""fullyStaffed"": false
            },
            {
              ""name"": ""afternoon_shift"",
              ""from"": ""2024-01-15T14:00:00"",
              ""to"": ""2024-01-15T22:00:00"",
              ""skills"": [""nursing"", ""patient_care""],
              ""cost"": 30.0,
              ""value"": 3,
              ""priority"": 2,
              ""assignedEmployee"": null,
              ""fullyStaffed"": false
            },
            {
              ""name"": ""night_shift"",
              ""from"": ""2024-01-15T22:00:00"",
              ""to"": ""2024-01-16T06:00:00"",
              ""skills"": [""nursing"", ""patient_care"", ""emergency""],
              ""cost"": 35.0,
              ""value"": 2,
              ""priority"": 3,
              ""assignedEmployee"": null,
              ""fullyStaffed"": false
            }
          ],
          ""employees"": [
            {
              ""name"": ""Alice Johnson"",
              ""contract"": ""FULL_TIME"",
              ""skills"": [""nursing"", ""patient_care"", ""emergency""],
              ""lastRestDate"": ""2024-01-14"",
              ""availability"": [""2024-01-15""],
              ""preference"": [""morning_shift""],
              ""periodRules"": [],
              ""shifts"": [],
              ""totalWorkingHours"": 0,
              ""consecutiveWorkingDays"": 0,
              ""workingDays"": 0
            },
            {
              ""name"": ""Bob Smith"",
              ""contract"": ""FULL_TIME"",
              ""skills"": [""nursing"", ""patient_care""],
              ""lastRestDate"": ""2024-01-14"",
              ""availability"": [""2024-01-15""],
              ""preference"": [""afternoon_shift""],
              ""periodRules"": [],
              ""shifts"": [],
              ""totalWorkingHours"": 0,
              ""consecutiveWorkingDays"": 0,
              ""workingDays"": 0
            },
            {
              ""name"": ""Carol Davis"",
              ""contract"": ""FULL_TIME"",
              ""skills"": [""nursing"", ""patient_care"", ""emergency""],
              ""lastRestDate"": ""2024-01-14"",
              ""availability"": [""2024-01-15""],
              ""preference"": [""night_shift""],
              ""periodRules"": [],
              ""shifts"": [],
              ""totalWorkingHours"": 0,
              ""consecutiveWorkingDays"": 0,
              ""workingDays"": 0
            }
          ],
          ""options"": {
            ""partialPlanning"": false,
            ""maxIterations"": 1000,
            ""timeLimit"": 300
          },
          ""weights"": {
            ""requiredSkills"": 1000,
            ""workingHours"": 1000,
            ""consecutiveWorkDays"": 500,
            ""restBetweenShifts"": 500,
            ""shiftPreferences"": 100,
            ""workloadBalance"": 50,
            ""costMinimization"": 25,
            ""fairness"": 75
          }
        };

var json = JsonSerializer.Serialize(requestData);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://api.plansolve.com/api/shift/solve", content);
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine($"Response: {result}");

Response Example

Optimization Results

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Hospital Shift Assignment",
  "shifts": [
    {
      "name": "morning_shift",
      "assignedEmployee": {
        "name": "Alice Johnson",
        "skills": ["nursing", "patient_care", "emergency"]
      },
      "fullyStaffed": true,
      "missingStaffCount": 0
    },
    {
      "name": "afternoon_shift",
      "assignedEmployee": {
        "name": "Bob Smith",
        "skills": ["nursing", "patient_care"]
      },
      "fullyStaffed": true,
      "missingStaffCount": 0
    },
    {
      "name": "night_shift",
      "assignedEmployee": {
        "name": "Carol Davis",
        "skills": ["nursing", "patient_care", "emergency"]
      },
      "fullyStaffed": true,
      "missingStaffCount": 0
    }
  ],
  "score": {
    "hardScore": 0,
    "softScore": -1200,
    "feasible": true
  },
  "feasible": true,
  "assignedShifts": ["morning_shift", "afternoon_shift", "night_shift"],
  "unassignedShifts": []
}

What's Next?

Now that you've seen the basics, explore our SDK documentation for more detailed examples, or try the interactive playground to experiment with different scenarios.

SDK DocumentationTry Playground