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 treats 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 an active Timefold Platform account.

Request a trial

Navigate to https://app.timefold.ai.
Click Log in.
Click Sign up.

Either enter the 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.
Verify your email address.
Click Request a trial.

A member of our team will contact you to arrange a trial.

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

Create a problem dataset
Post the dataset
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/

1. 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:

{
  "modelInput": {
    "employees": [
      {
        "id": "Beth"
      }
    ],
    "shifts": [
      {
        "id": "Mon Night",
        "start": "2027-02-01T00:00:00Z",
        "end": "2027-02-02T08:00:00Z"
      }
    ]
  }
}

Copy this example dataset into a file called sample.json to use in this hello world example.

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

At a minimum, modelInput must include employees and shifts:

1.1. Employees

In this example, there is 1 employee. employees must include an id.

id is a unique identifier that identifies the individual employee.

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

Learn about additional options that can be included for employees in the Employee resource constraints guides.

1.2. Shifts

In this example, there is 1 shift. shift includes an id, start, and end.

id is a unique identifier that identifies the individual shift.
start is the start time of the shift in ISO 8601 date and time format.
end is the end time of the shift in ISO 8601 date and time format.

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

Learn about additional options that can be included for shifts in the Shift service constraints guides.

When the dataset is posted to Timefold, Timefold will attempt to assign employees to shifts, while considering the constraints of the domain.

2. Post the dataset

You have two options to post the dataset.

Post the dataset in the Timefold Platform UI
Post the dataset to the Timefold API

2.1. 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:

Log into the Timefold Platform dashboard: https://app.timefold.ai
Select the Employee Shift Scheduling tile.
Click New dataset.
Select Custom and click Next
Upload the sample.json file you saved earlier.
Click Next, then click Run.

2.2. 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:

Log in to Timefold Platform: app.timefold.ai.
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
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",
  "parentId": null,
  "originId": "ID",
  "name": "Dataset-2025-09-17T06:13:03.424997617Z",
  "submitDateTime": "2025-09-17T06:13:03.424997617Z",
  "startDateTime": null,
  "activeDateTime": null,
  "completeDateTime": null,
  "shutdownDateTime": null,
  "solverStatus": "SOLVING_SCHEDULED",
  "score": null,
  "tags": [
    "system.type:from-request",
    "system.profile:default"
  ],
  "validationResult": null
}

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.

3. 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/XXXX/v1/XXXX/<ID>

{
  "metadata": {
    "id": "ID",
    "parentId": null,
    "originId": "ID",
    "name": "Dataset-2025-09-17T06:13:03.424997617Z",
    "submitDateTime": "2025-09-17T06:13:03.424997617Z",
    "startDateTime": "2025-09-17T06:13:23.044444944Z",
    "activeDateTime": "2025-09-17T06:13:23.102121607Z",
    "completeDateTime": "2025-09-17T06:13:53.903832134Z",
    "shutdownDateTime": "2025-09-17T06:13:54.150644305Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon Night",
        "employee": "Beth"
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 1,
    "pinnedShifts": 0
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "disruptionPercentage": 0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 1,
    "assignedOptionalShifts": 0,
    "travelDistance": 0
  },
  "run": {
    "id": "531f5e8b-d705-4404-93f6-d10234445dec",
    "parentId": null,
    "originId": "531f5e8b-d705-4404-93f6-d10234445dec",
    "name": "Dataset-2025-09-17T06:13:03.424997617Z",
    "submitDateTime": "2025-09-17T06:13:03.424997617Z",
    "startDateTime": "2025-09-17T06:13:23.044444944Z",
    "activeDateTime": "2025-09-17T06:13:23.102121607Z",
    "completeDateTime": "2025-09-17T06:13:53.903832134Z",
    "shutdownDateTime": "2025-09-17T06:13:54.150644305Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

The output shows the solverStatus is SOLVING_COMPLETED.

modelOutput contains the solution for the dataset.

{
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon Night",
        "employee": "Beth"
      }
    ]
  }
}

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

getting started

See the full API spec or try the online API.
Learn more about employee shift scheduling from our YouTube playlist.
Configure a webhook.
Refer to the User guide or learn about Employee resource constraints and Shift service constraints.

Getting started: Hello world

1. Create a problem dataset

1.1. Employees

1.2. Shifts

2. Post the dataset

2.1. Post the dataset in the Timefold Platform UI

2.2. Post the dataset to the Timefold API

3. Request the solution

Next