> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Optimize employee-to-shift assignments with intelligent scheduling that respects skills, availability, and labor rules

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.

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

## Core Capabilities

<CardGroup cols={3}>
  <Card title="Skill Matching" icon="puzzle-piece">
    Match employee skills to shift requirements at multiple proficiency levels
  </Card>

  <Card title="Labor Compliance" icon="scale-balanced">
    Enforce rest periods, working hour limits, and consecutive day rules
  </Card>

  <Card title="Fair Distribution" icon="balance-scale">
    Balance workload across employees based on hours or shift counts
  </Card>
</CardGroup>

## 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 |

<Tabs>
  <Tab title="Create API">
    Use **Create** when you know *how many* people you need but not *when*:

    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="Fill API">
    Use **Fill** when you have shifts and need to assign employees:

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

    **Output:** Employee-to-shift assignments
  </Tab>

  <Tab title="Combined Workflow">
    Use both APIs together for end-to-end scheduling:

    1. **Create API** generates optimal shifts from demand forecasts
    2. **Fill API** assigns employees to those shifts

    ```mermaid theme={null}
    graph LR
        A[Demand Forecast] --> B[Create API]
        B --> C[Generated Shifts]
        C --> D[Fill API]
        E[Employee Pool] --> D
        D --> F[Assignments]
    ```
  </Tab>
</Tabs>

## API Endpoints

### Optimization Actions

<Tabs>
  <Tab title="Solve">
    ```bash theme={null}
    POST /v2/fill/solve
    ```

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

    <Tip>
      Use this for weekly schedule generation, shift assignment optimization, and coverage planning.
    </Tip>
  </Tab>

  <Tab title="Suggest">
    ```bash theme={null}
    POST /v2/fill/suggest
    ```

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

    <Tip>
      Use this for manual schedule adjustments or understanding why certain assignments were made.
    </Tip>
  </Tab>
</Tabs>

### Result Retrieval

<ParamField path="job_id" type="string" required>
  The unique identifier returned when you submit a request
</ParamField>

<CodeGroup>
  ```bash Status Check theme={null}
  GET /v2/fill/jobs/{job_id}/status
  ```

  ```bash Get Solution theme={null}
  GET /v2/fill/jobs/{job_id}/solution
  ```

  ```bash Get Explanation theme={null}
  GET /v2/fill/jobs/{job_id}/explanation
  ```
</CodeGroup>

## How It Works

<Steps>
  <Step title="Submit Request">
    Send your scheduling problem with employees and shifts to the solve endpoint.

    ```json theme={null}
    {
      "employees": [...],
      "shifts": [...],
      "rules": [...],
      "options": {...}
    }
    ```
  </Step>

  <Step title="Monitor Progress">
    Check the job status while the solver optimizes assignments.

    ```json theme={null}
    {
      "id": "job_123",
      "status": "SOLVING"
    }
    ```
  </Step>

  <Step title="Retrieve Solution">
    Get the optimized assignments once the solver completes.

    ```json theme={null}
    {
      "assignments": [...],
      "unassigned": [...],
      "score": { "feasible": true },
      "status": "SOLVED"
    }
    ```
  </Step>
</Steps>

## Key Features

<AccordionGroup>
  <Accordion title="Multi-Level Skill Matching">
    * Required skills as hard constraints
    * Skill proficiency levels (1-5)
    * Soft skill preferences for optimization
    * Critical shift skill bonuses
  </Accordion>

  <Accordion title="Labor Rule Engine">
    * Maximum working days per period
    * Minimum/maximum hours constraints
    * Consecutive day limits
    * Mandatory rest periods between shifts
    * Weekend idle requirements
  </Accordion>

  <Accordion title="Availability Management">
    * Time-based availability windows
    * Day-of-week restrictions
    * Blocked employee-shift pairs
    * Locked (pre-assigned) shifts
  </Accordion>

  <Accordion title="Fairness & Preferences">
    * Workload balancing across employee groups
    * Shift preferences (preferred/unpreferred)
    * Pattern-based scheduling (avoid late→early)
    * Target hours per employee
  </Accordion>
</AccordionGroup>

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Healthcare Staffing" icon="user-nurse">
    Schedule nurses and caregivers with skill matching and mandatory rest compliance
  </Card>

  <Card title="Retail Scheduling" icon="store">
    Balance coverage across peak hours while respecting employee availability
  </Card>

  <Card title="Hospitality" icon="utensils">
    Assign kitchen, floor, and bar staff based on skills and shift patterns
  </Card>

  <Card title="Contact Centers" icon="headset">
    Optimize agent schedules for service level targets with fair workload distribution
  </Card>
</CardGroup>

## 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    |

<Info>
  A solution is **feasible** only when all hard constraints are satisfied (hardScore = 0).
</Info>

## Quick Start

<Note>
  Need an API key? Visit the [Dashboard](https://platform.solvice.io) to get started.
</Note>

Ready to optimize your first schedule?

<Card title="Fill Quickstart Guide" icon="rocket" href="/guides/fill/quickstart">
  Assign employees to shifts in under 5 minutes
</Card>

## Additional Resources

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/api-reference/fill/solve">
    Detailed endpoint documentation
  </Card>

  <Card title="Examples" icon="lightbulb" href="/guides/fill/examples/rule">
    Rules, patterns, and constraints
  </Card>

  <Card title="Request Schema" icon="brackets-curly" href="/guides/fill/schemas/request">
    Complete field reference
  </Card>
</CardGroup>