Getting started: Hello world

The Employee Shift Scheduling model assigns shifts to employees with the goals of creating schedules that minimize labor costs, ensure proper shift coverage, and treat employees fairly and with respect.

This guide introduces Timefold’s Employee Shift Scheduling model and walks you through the steps to use Timefold Platform to create an optimized Employee Shift Scheduling solution.

To follow the steps in this guide, you need to be registered on Timefold Platform and have access to an active tenant.

Start a trial

  1. Navigate to https://app.timefold.ai/free-trial.

  2. Click Sign up.

    Either enter the company email address and password you want to register with and click continue or select one of the federated log-in options and follow the prompts.

  3. Verify your email address.

  4. Add your details, agree to the terms and click Start free trial.

Hello world

The steps in this guide can be completed in under 10 minutes:

  1. Create a problem dataset

  2. Post the dataset

  3. Request the solution

This hello world example uses an example with 1 employee and 1 shift to demonstrate the process of requesting and retrieving a solution from Timefold’s Employee Shift Scheduling model.

At the end of this guide, you will have a solution for the Employee Shift Scheduling hello world problem.

getting started

This hello world uses the POST and GET methods and the API endpoint: https://app.timefold.ai/api/models/employee-scheduling/v1/schedules

Create a problem dataset

A dataset for the Employee Shift Scheduling model must include information about your shifts and your employees' availability.

The following is an example Employee Shift Scheduling input dataset:

{
  "config": {
    "run": {
      "name": "Hello world example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Beth"
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T00:00:00Z",
        "end": "2027-02-01T08:00:00Z"
      }
    ]
  }
}
Copy this example dataset into a file called sample.json to use in this hello world example.

There are two sections in the dataset: config and modelInput.

Config

The config section is entirely optional. It can be used to configure the dataset options, such as the dataset name in the example above.

If omitted, a default name will be used based on the timestamp when the dataset was submitted, in the format Dataset-YYYY-MM-DDThh:mm:ss.sZ. For now, this field is the only one that is relevant to this example.

ModelInput

The modelInput object of the dataset contains the data to be optimized.

At a minimum, modelInput must include employees and shifts. For now, these are the only fields relevant to this example.

Employees

Employees are the resource that can be assigned to fulfil shifts. In this example, there is one employee. At minimum, each employee object must include an id.

  • id can be any string of your choice. The id is the unique identifier for each individual employee.

{
  "employees": [
    {
      "id": "Beth"
    }
  ]
}

For now, this is the only option relevant to this example. In a realistic example, employees will need to specify additional options other than id in order to follow all the rules that govern a valid schedule.

Explore our documentation to learn about additional options that can be included for employees, such as those in the Employee resource constraints guides.

Shifts

Shifts are the demand for work that must be fulfilled by employees. In this example, there is one shift. At minimum, each shift object must include an id, start, and end.

  • id can be any string of your choice. The id is the unique identifier for each individual shift, which will be assigned to one individual employee.

  • start is the start datetime of the shift in ISO 8601 date and time format. This format can be summarized as YYYY-MM-DDThh:mm:ssZ.

  • end is the end datetime of the shift in ISO 8601 date and time format, as for the start.

{
  "shifts": [
    {
      "id": "Mon",
      "start": "2027-02-21T00:00:00Z",
      "end": "2027-02-21T08:00:00Z"
    }
  ]
}

For now, this is the only option relevant to this example. In a realistic example, shifts will need to specify additional options other than the above in order to follow all the rules that govern a valid schedule.

Explore our documentation to learn about additional options that can be included for shifts, such as those in the Shift service constraints guides.

Constraints

Constraints are the rules that govern which employees can fulfil which shifts. When the dataset is posted to Timefold, Timefold will attempt to assign employees to shifts, while considering the constraints of the domain. In this simple example, we do not yet have any constraints to consider. However, the concept of constraints is important to mention. In a more realistic scenario, configuring the correct constraints is essential to achieving a useful schedule.

Read more about constraints and how to configure them in our constraints documentation.

Post the dataset

You have two options to post the dataset.

  1. Post the dataset in the Timefold Platform UI

  2. Post the dataset to the Timefold API

Post the dataset in the Timefold Platform UI

Typically, you post the dataset to the API. However, for testing purposes, you can upload your sample.json file directly in the Timefold Platform UI:

  1. Log into the Timefold Platform dashboard: https://app.timefold.ai

  2. Select the Employee Shift Scheduling tile.

  3. Click New plan.

  4. Select Custom and click Next

  5. Upload the sample.json file you saved earlier.

  6. Click Next, then click Run.

Post the dataset to the Timefold API

You need an API key to access the API.

Learn how to configure an API Key to run the examples in this guide:

  1. Log in to Timefold Platform: app.timefold.ai.

  2. From the Dashboard, click your tenant, and from the drop-down menu select Manage tenant, then choose API Keys.

  3. Create a new API key or use an existing one. Ensure the list of models for the API key contains the current model.

In the examples, replace <API_KEY> with the API Key you just copied.

POST the dataset contained in the sample.json file for solving to the API endpoint: https://app.timefold.ai/api/models/employee-scheduling/v1/schedules

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY': <API_KEY> https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

The dataset will be validated. If the dataset is valid you will receive a response similar to:

{
  "id": "ID",
  "originId": "35849477-eb98-400b-8afe-9601798661c3",
  "name": "Hello world example",
  "submitDateTime": "2026-01-16T11:35:17.3496936Z",
  "solverStatus": "SOLVING_SCHEDULED",
  "tags": [
    "system.type:from-request",
    "system.profile:Standard profile"
  ]
}

The output includes an ID that has been assigned to the dataset. You’ll use this ID to retrieve the solution for your dataset.

solverStatus confirms the dataset has been scheduled for solving.

Request the solution

Append the <ID> from the output you received to the endpoint https://app.timefold.ai/api/models/employee-scheduling/v1/schedules and create a GET request to retrieve the solution:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>
{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Hello world example",
    "submitDateTime": "2026-01-16T11:42:35.903507885Z",
    "startDateTime": "2026-01-16T11:42:43.248796472Z",
    "activeDateTime": "2026-01-16T11:42:43.328084014Z",
    "completeDateTime": "2026-01-16T11:43:13.651780017Z",
    "shutdownDateTime": "2026-01-16T11:43:13.651785337Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:Standard profile"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 1,
          "durationWorked": "PT8H"
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 1,
    "pinnedShifts": 0,
    "mandatoryShifts": 1,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "disruptionPercentage": 0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 1
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "Hello world example",
    "submitDateTime": "2026-01-16T11:42:35.903507885Z",
    "startDateTime": "2026-01-16T11:42:43.248796472Z",
    "activeDateTime": "2026-01-16T11:42:43.328084014Z",
    "completeDateTime": "2026-01-16T11:43:13.651780017Z",
    "shutdownDateTime": "2026-01-16T11:43:13.651785337Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:Standard profile"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

The output shows the solverStatus is SOLVING_COMPLETED.

modelOutput contains the solution for the dataset.

{
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 1,
          "durationWorked": "PT8H"
        }
      }
    ]
  }
}

In this solution Beth has been assigned to the Mon shift.

getting started

Next