Quickstart

Your First API Call

Test the Fill solver with a single command:

curl https://api.solvice.io/v2/fill/demo -H "Authorization: YOUR_API_KEY" | \
curl https://api.solvice.io/v2/fill/solve -H "Authorization: YOUR_API_KEY" \
     -X POST -H "Content-Type: application/json" -d @-

This queues a demo problem for solving and returns a job id, e.g. {"id": "job-123", "status": "QUEUED"}. Replace YOUR_API_KEY with your actual API key from the dashboard.

Basic Fill Request

A Fill request requires two things: employees (your workforce) and shifts (time slots to fill).

{
  "employees": [
    {
      "name": "Alice",
      "skills": [{ "name": "kitchen" }]
    },
    {
      "name": "Bob",
      "skills": [{ "name": "bar" }]
    }
  ],
  "shifts": [
    {
      "name": "morning-kitchen",
      "from": "2024-04-18T08:00:00",
      "to": "2024-04-18T14:00:00",
      "skills": [{ "name": "kitchen" }],
      "min": 1,
      "max": 1
    },
    {
      "name": "evening-bar",
      "from": "2024-04-18T18:00:00",
      "to": "2024-04-18T23:00:00",
      "skills": [{ "name": "bar" }],
      "min": 1,
      "max": 1
    }
  ]
}

curl -X POST https://api.solvice.io/v2/fill/solve \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

/v2/fill/solve queues the problem and returns immediately with a job id — it does not wait for the solver to finish:

Queued

{
  "id": "job-123",
  "status": "QUEUED"
}

Retrieving the Solution

Solving happens asynchronously. Poll the status endpoint until status is SOLVED, then fetch the solution.

curl https://api.solvice.io/v2/fill/jobs/job-123/status \
  -H "Authorization: YOUR_API_KEY"

curl https://api.solvice.io/v2/fill/jobs/job-123/solution \
  -H "Authorization: YOUR_API_KEY"

Understanding the Response

Once the job status is SOLVED, GET /v2/fill/jobs/{id}/solution returns the optimized shift assignments:

Solution

{
  "id": "job-123",
  "status": "SOLVED",
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -2,
    "feasible": true
  },
  "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"
    }
  ]
}

boolean

true if all hard constraints are satisfied (skills match, no conflicts)

array

List of shift-employee pairings with timing details

Key Concepts

Concept	Description
Employee	A worker with skills who can be assigned to shifts
Shift	A time slot requiring specific skills and number of workers
Skills	Capabilities that match employees to appropriate shifts
Score	Solution quality indicator (hard/medium/soft constraints)

Next Steps

Rules & Constraints

Add working day limits, sequences, and labor rules

Patterns

Define preferred or prohibited shift sequences

Fairness

Distribute workload evenly across employees

Request Schema

Complete request format documentation

Platform

VRP API

Fill API

Your First API Call

Basic Fill Request

Retrieving the Solution

Understanding the Response

Key Concepts

Next Steps

Rules & Constraints

Patterns

Fairness

Request Schema

​Your First API Call

​Basic Fill Request

​Retrieving the Solution

​Understanding the Response

​Key Concepts

​Next Steps

Rules & Constraints

Patterns

Fairness

Request Schema

Your First API Call

Basic Fill Request

Retrieving the Solution

Understanding the Response

Key Concepts

Next Steps