API Overview

The Fill API assigns employees to shifts while respecting skills, availability, labor regulations, and employee preferences. It finds the optimal workforce allocation that maximizes coverage while minimizing constraint violations.

The Fill solver handles complex workforce scenarios including multi-skill matching, fairness balancing, and conditional labor rules.

Core Capabilities

Skill Matching

Match employee skills to shift requirements at multiple proficiency levels

Labor Compliance

Enforce rest periods, working hour limits, and consecutive day rules

Fair Distribution

Balance workload across employees based on hours or shift counts

Fill vs Create

Solvice provides two complementary scheduling APIs:

Aspect	Create API	Fill API
Question	What shifts should exist?	Who works each shift?
Input	Demand forecasts + templates	Shifts + employees
Output	Generated shifts	Employee assignments
When to use	You have demand data, need shift structure	You have defined shifts, need staffing

Create API
Fill API
Combined Workflow

Use Create when you know how many people you need but not when:

{
  "demands": [
    { "from": "09:00", "to": "15:00", "demand": 5 }
  ],
  "templates": [
    { "name": "morning", "from": "09:00", "to": "17:00" }
  ]
}

Output: Shift definitions with start/end times

Use Fill when you have shifts and need to assign employees:

{
  "shifts": [
    { "name": "morning-1", "from": "09:00", "to": "17:00", "skills": ["kitchen"] }
  ],
  "employees": [
    { "name": "Alice", "skills": [{ "name": "kitchen" }] }
  ]
}

Output: Employee-to-shift assignments

API Endpoints

Optimization Actions

Solve
Suggest

POST /v2/fill/solve

Finds optimal employee-to-shift assignments. This is the main endpoint for workforce scheduling.

Use this for weekly schedule generation, shift assignment optimization, and coverage planning.

POST /v2/fill/suggest

Evaluates all possible employees for a specific shift. Returns ranked alternatives with score impacts.

Use this for manual schedule adjustments or understanding why certain assignments were made.

Result Retrieval

job_id

string

required

The unique identifier returned when you submit a request

GET /v2/fill/jobs/{job_id}/status

GET /v2/fill/jobs/{job_id}/solution

GET /v2/fill/jobs/{job_id}/explanation

How It Works

Submit Request

Send your scheduling problem with employees and shifts to the solve endpoint.

{
  "employees": [...],
  "shifts": [...],
  "rules": [...],
  "options": {...}
}

Monitor Progress

Check the job status while the solver optimizes assignments.

{
  "id": "job_123",
  "status": "SOLVING"
}

Retrieve Solution

Get the optimized assignments once the solver completes.

{
  "assignments": [...],
  "unassigned": [...],
  "score": { "feasible": true },
  "status": "SOLVED"
}

Key Features

Multi-Level Skill Matching

Required skills as hard constraints
Skill proficiency levels (1-5)
Soft skill preferences for optimization
Critical shift skill bonuses

Labor Rule Engine

Rules are declarative: each rule picks a COUNTER (count occurrences) or SEQUENCE (longest streak) constraint, applies to a configurable period (including rolling windows), and can chain to a follow-up rule via then when a threshold is crossed.

Maximum working days per period
Minimum/maximum hours constraints
Consecutive day limits via the MAX_CONSECUTIVE_DAYS rule type
Minimum, maximum, and cumulative (total) rest duration requirements between shifts
Weekend idle requirements

Availability Management

Time-based availability windows
Day-of-week restrictions
Blocked employee-shift pairs
Locked (pre-assigned) shifts

Fairness & Preferences

Workload balancing across employee groups
Shift preferences (preferred/unpreferred)
Pattern-based scheduling (avoid late→early)
Target hours per employee

Common Use Cases

Healthcare Staffing

Schedule nurses and caregivers with skill matching and mandatory rest compliance

Retail Scheduling

Balance coverage across peak hours while respecting employee availability

Hospitality

Assign kitchen, floor, and bar staff based on skills and shift patterns

Contact Centers

Optimize agent schedules for service level targets with fair workload distribution

Constraint System

The Fill solver uses a three-tier scoring system:

Level	Purpose	Example
Hard	Must be satisfied	Skill requirements, availability
Medium	Should be satisfied	Unassigned shifts, preferences
Soft	Nice to have	Travel time, fairness balance

A solution is feasible only when all hard constraints are satisfied (hardScore = 0).

Quick Start

Need an API key? Visit the Dashboard to get started.

Ready to optimize your first schedule?

Fill Quickstart Guide

Assign employees to shifts in under 5 minutes

Additional Resources

API Reference

Detailed endpoint documentation

Examples

Rules, patterns, and constraints

Request Schema

Complete field reference

Platform

VRP API

Fill API

Core Capabilities

Skill Matching

Labor Compliance

Fair Distribution

Fill vs Create

API Endpoints

Optimization Actions

Result Retrieval

How It Works

Key Features

Common Use Cases

Healthcare Staffing

Retail Scheduling

Hospitality

Contact Centers

Constraint System

Quick Start

Fill Quickstart Guide

Additional Resources

API Reference

Examples

Request Schema

​Core Capabilities

Skill Matching

Labor Compliance

Fair Distribution

​Fill vs Create

​API Endpoints

​Optimization Actions

​Result Retrieval

​How It Works

​Key Features

​Common Use Cases

Healthcare Staffing

Retail Scheduling

Hospitality

Contact Centers

​Constraint System

​Quick Start

Fill Quickstart Guide

​Additional Resources

API Reference

Examples

Request Schema

Core Capabilities

Fill vs Create

API Endpoints

Optimization Actions

Result Retrieval

How It Works

Key Features

Common Use Cases

Constraint System

Quick Start

Additional Resources