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

# Response Schema

> Fill API solution response structure and field reference

The Fill API returns optimized shift assignments with scoring information and optional explanations.

## Response Structure

```json theme={null}
{
  "id": "job-uuid-123",
  "status": "SOLVED",
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -5,
    "feasible": true
  },
  "assignments": [...],
  "unassigned": [...],
  "violations": [...],
  "suggestions": [...]
}
```

## Top-Level Fields

<ResponseField name="id" type="string (UUID)" required>
  Unique identifier for the solve job.
</ResponseField>

<ResponseField name="status" type="string" required>
  Job status: `QUEUED`, `SOLVING`, or `SOLVED`.
</ResponseField>

<ResponseField name="score" type="object" required>
  Solution quality indicator. See [Score](#score).
</ResponseField>

<ResponseField name="assignments" type="array" required>
  List of employee-shift pairings. See [Assignment](#assignment).
</ResponseField>

<ResponseField name="unassigned" type="array">
  List of shift names that could not be filled.
</ResponseField>

<ResponseField name="violations" type="array">
  List of constraint violations. See [ViolatedConstraint](#violatedconstraint).
</ResponseField>

<ResponseField name="suggestions" type="array">
  Alternative assignments from suggest API. See [Suggestion](#suggestion).
</ResponseField>

***

## Score

The score indicates solution quality using a three-tier system.

```json theme={null}
{
  "hardScore": 0,
  "mediumScore": 0,
  "softScore": -15,
  "feasible": true
}
```

<ResponseField name="hardScore" type="integer" required>
  Hard constraint violations. Must be `0` for a feasible solution.
</ResponseField>

<ResponseField name="mediumScore" type="integer" required>
  Medium constraint violations. Less critical than hard constraints.
</ResponseField>

<ResponseField name="softScore" type="integer" required>
  Soft constraint penalties. Used to optimize solution quality.
</ResponseField>

<ResponseField name="feasible" type="boolean" required>
  `true` if `hardScore` is `0`. Indicates all hard constraints are satisfied.
</ResponseField>

### Score Interpretation

| Hard Score    | Feasible | Meaning                                |
| ------------- | -------- | -------------------------------------- |
| `0`           | `true`   | All hard constraints satisfied         |
| `-1` or lower | `false`  | One or more hard constraint violations |

<Info>
  A negative soft score is normal and expected. The solver minimizes soft score violations while keeping hard constraints satisfied.
</Info>

***

## Assignment

Each assignment represents an employee assigned to a shift.

```json theme={null}
{
  "shift": "morning-kitchen",
  "from": "2024-04-18T08:00:00",
  "to": "2024-04-18T14:00:00",
  "skills": ["kitchen"],
  "employee": "Alice",
  "travelTimeInSeconds": 1200
}
```

<ResponseField name="shift" type="string" required>
  Shift identifier from the request.
</ResponseField>

<ResponseField name="from" type="datetime" required>
  Shift start time.
</ResponseField>

<ResponseField name="to" type="datetime" required>
  Shift end time.
</ResponseField>

<ResponseField name="skills" type="array" required>
  Skills required for this shift.
</ResponseField>

<ResponseField name="employee" type="string" required>
  Assigned employee name.
</ResponseField>

<ResponseField name="travelTimeInSeconds" type="integer">
  Travel time from employee location to shift location (if locations provided).
</ResponseField>

### Example Assignment List

```json theme={null}
{
  "assignments": [
    {
      "shift": "morning-kitchen",
      "from": "2024-04-18T08:00:00",
      "to": "2024-04-18T14:00:00",
      "skills": ["kitchen"],
      "employee": "Alice"
    },
    {
      "shift": "evening-bar",
      "from": "2024-04-18T18:00:00",
      "to": "2024-04-18T23:00:00",
      "skills": ["bar"],
      "employee": "Bob"
    }
  ]
}
```

***

## ViolatedConstraint

Details about constraints that were violated in the solution.

```json theme={null}
{
  "name": "Employee Skill Match",
  "value": 2,
  "level": "SOFT"
}
```

<ResponseField name="name" type="string" required>
  Constraint identifier.
</ResponseField>

<ResponseField name="value" type="number" required>
  Violation magnitude. Higher values indicate larger deviations.
</ResponseField>

<ResponseField name="level" type="string" required>
  Constraint level: `HARD`, `MEDIUM`, or `SOFT`.
</ResponseField>

***

## Suggestion

Alternative assignment options returned by the suggest API.

```json theme={null}
{
  "shift": "morning-kitchen",
  "employee": "Carol",
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -3,
    "feasible": true
  },
  "violations": [...]
}
```

<ResponseField name="shift" type="string" required>
  Shift being evaluated.
</ResponseField>

<ResponseField name="employee" type="string" required>
  Suggested employee.
</ResponseField>

<ResponseField name="score" type="object" required>
  Impact on solution score if this assignment is made.
</ResponseField>

<ResponseField name="violations" type="array">
  Constraints violated by this suggestion.
</ResponseField>

***

## Weights Reference

Available constraint weights for customization in requests.

| Constraint              | Property           | Default | Description                      |
| :---------------------- | :----------------- | :------ | :------------------------------- |
| Maximum Working Days    | `maxWorkingDays`   | HARD    | Max days in planning period      |
| Maximum Hours           | `maxHours`         | HARD    | Max hours in planning period     |
| Minimum Hours           | `minHours`         | HARD    | Min hours in planning period     |
| Earliest Shift Start    | `shiftStart`       | HARD    | Earliest allowed start time      |
| Latest Shift Start      | `latestShiftStart` | HARD    | Latest allowed start time        |
| Latest Shift End        | `shiftEnd`         | HARD    | Latest allowed end time          |
| Maximum Shift Length    | `maxShift`         | HARD    | Max shift duration               |
| Minimum Shift Length    | `minShift`         | HARD    | Min shift duration               |
| DayOfWeek Working       | `dayOfWeek`        | HARD    | Day-based availability           |
| Maximum Shifts Same Day | `sameDay`          | HARD    | Max shifts per day               |
| Minimum Rest Same Day   | `sameDayMinRest`   | HARD    | Min rest between same-day shifts |
| Employee Availability   | `availability`     | HARD    | Time-based availability          |
| Locked Assignment       | `locked`           | HARD    | Fixed assignments                |
| Max Consecutive Days    | `maxConsecutive`   | HARD    | Max consecutive working days     |
| Minimum Rest            | `minRest`          | HARD    | Min rest between shifts          |
| No Concurrent           | `concurrent`       | HARD    | Prevent overlapping assignments  |
| Skill Requirements      | `requirements`     | HARD    | Shared skill requirements        |
| Employee Skill Match    | `skills`           | HARD    | Skill matching                   |
| Shift Blocklist         | `blacklist`        | HARD    | Blocked employee-shift pairs     |
| Employee Working Days   | `working`          | HARD    | Respect working day limits       |
| Travel Time             | `distance`         | SOFT    | Minimize travel                  |
| Priority                | `priority`         | SOFT    | Shift priorities                 |
| Shift Preference        | `pref`             | MEDIUM  | Employee preferences             |
| Financial Costs         | `costs`            | SOFT    | Shift costs                      |
| Wage Costs              | `wages`            | SOFT    | Employee wage costs              |
| Unassigned Employee     | `unassigned`       | MEDIUM  | Minimize unassigned employees    |
| Soft Skill Match        | `softSkills`       | SOFT    | Soft skill matching              |
| Critical Skill Match    | `criticalSkills`   | SOFT    | Critical shift preference        |
| Efficiency              | `efficiency`       | SOFT    | Employee efficiency              |
| Skill Level Match       | `softSkillsLevel`  | SOFT    | Skill proficiency matching       |

### Custom Weight Format

Override defaults using the format `<weight><priority>`:

```json theme={null}
{
  "weights": {
    "locked": "100hard",
    "unassigned": "5soft",
    "skills": "50hard"
  }
}
```

<Tip>
  Use weights to balance competing objectives. Increase weights for constraints that matter most to your business.
</Tip>