> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Started with the Schedule API
The Schedule API allows you to manage your employees' **theoretical working schedules**: how many hours or days
they are expected to work, on which days, and at what times.
This is the foundation upon which other Lucca modules (Absences, Timesheet) rely to compute leave balances,
overtime, and time-tracking expectations.
***
## Key concepts
An employee's effective schedule (i.e. `UserDate`) on any given day is computed by layering three things, in order:
```mermaid theme={null}
flowchart TD
A["Base schedule\n(Workcycle or WTA)"] -->|+| B["Public Holidays\n(calendar)"]
B -->|+| C["One-time overrides\n(Exceptions or ShiftOverrides)"]
C -->|=| D(["UserDate"])
```
1. **Base recurring schedule** — defines the default working hours for each day of the week (possibly alternating odd/even weeks).
2. **Public Holidays** — days marked as non-working in the employee's public-holidays calendar override the base schedule.
3. **One-time overrides** — punctual modifications for a specific employee on a specific day (e.g. "exceptionally, this employee does not work next Thursday").
The **final, computed result** for a given employee on a given day is exposed via the [UserDate](./userdates/userdate) resource.
***
## Two co-existing models
The Schedule API is undergoing a major refactor. Depending on whether the **Working Time Arrangements** feature has been
enabled on your Lucca environment, you will use one of two models (more below). Both produce the same end result ([UserDates](./userdates/userdate)),
but they differ in how the base schedule and overrides are represented.
If you are unsure which model applies to your environment, contact [Lucca Support](https://support.lucca.fr).
New integrations should target the **New Model** whenever possible.
### Old Model (Workcycles)
| Resource | Role |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Workcycle** | A recurring weekly pattern of working hours, assigned to employees via their V3 User's `userWorkcycles` property. |
| [**Workcycle Exception**](./workcycle-exceptions/workcycle-exception) | A one-time override of an employee's working hours on a specific half-day. |
A workcycle is a theoretical **recurring** schedule assigned to an employee. It defines their working days and hours with a weekly (or bi-weekly) pattern. It is assigned to employees via the `userWorkcycles` property of the V3 User.
A workcycle exception overrides the employee's planned working hours on a specific **half-day** (AM or PM). Use it to add, remove, or change scheduled hours for one employee on one date.
### New Model (Working Time Arrangements)
| Resource | Role |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Working Time Arrangement**](./working-time-arrangements/working-time-arrangement) (WTA) | Replaces the Workcycle. Defines recurring working hours, contractual time, full-time equivalent, and associated rules. |
| [**Collective Schedule**](./working-time-arrangements/collective-schedule) | The weekly hours pattern within a Working Time Arrangement (WTA) over a given date-range. A WTA can have successive collective schedules over time. |
| [**Employee Assignment**](./employee-assignments/employee-assignment) | Links a Working Time Arrangement to an employee for a given period (via a work-contract amendment). |
| [**Shift Override**](./shift-overrides/shift-override) | Replaces the Workcycle Exception. A one-time modification to an employee's schedule on a specific day. |
The successor to the Workcycle. Defines recurring working hours, the contractual working time duration, the full-time equivalent, and the public-holidays calendar for a population of employees.
Describes the actual weekly pattern of a Working Time Arrangement (e.g. "Monday to Friday, 09:00-17:00") over a given date-range. Can be a single repeating week or alternate between odd and even weeks.
Assigns a Working Time Arrangement to an employee starting on a given date. Creating an assignment generates a work-contract amendment automatically.
A one-time modification to an employee's regular schedule. Can mark a day as worked, off, part-time, or weekly rest, and optionally change the duration or start time.
***
## The UserDate: reading the effective schedule
Regardless of which model you use, the **[UserDate](./userdates/userdate)** resource gives you the **final, computed schedule**
for one or more employees over a date range. It aggregates:
* **Theoretical hours** from the base schedule (Workcycle or WTA).
* **Public Holiday** overrides from the employee's holidays calendar.
* **Exception / Shift Override** modifications.
* **Leaves** from Lucca Absences (if applicable).
* **Time entries** from Lucca Timesheet (if applicable).
Each UserDate exposes:
| Field | Meaning |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `dtt` | **Theoretical working time** — what the employee should work on that day. |
| `drt` | **Actual working time** — what the employee actually worked (defaults to `dtt` if no time entry). |
| `draj` | **Leave duration** — time absent via leaves. |
| `isHoliday` | Whether the day is a public holiday. |
| `isWeeklyRest` | Whether the day is a weekly rest day (e.g. Sunday). |
| `items[]` | Detailed breakdown of all events for that day. |
For performance, always scope UserDate requests to a limited set of employees and a short date range.
As a rule of thumb, do not request more than \~10 employees over a single month.
***
## Understanding time units
Every schedule resource operates in one of three **units**. The unit is defined at the Workcycle or Working Time Arrangement level and determines how durations are expressed:
| Unit | Meaning | Example |
| -------- | ----------------------------------------------------------------------- | ------------------------------ |
| **Day** | Durations are expressed as fractions of a day. `12:00:00` = half a day. | "I worked half a day" |
| **Hour** | Durations are expressed in hours. `03:30:00` = 3 hours and 30 minutes. | "I worked 3h30" |
| **Time** | Durations are expressed in hours **with a start time**. | "I worked from 09:00 to 12:30" |
When creating Workcycle Exceptions or Shift Overrides, the unit you specify **must match** the unit of the
employee's applicable base schedule. If the employee's schedule is in "hours", you cannot create an exception in "days".
***
## Typical integration scenarios
### Reading an employee's schedule
To know what an employee is expected to work over a period, query the [UserDate endpoint](./userdates/userdate):
```http Get UserDates theme={null}
GET /api/v3/userdates?ownerId=42&date=between,2026-06-01,2026-06-30&fields=ownerId,date,dtt,isHoliday,isWeeklyRest,items[startsAt,duration,type,timeline] HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={api_key}
```
### Overriding an employee's schedule for one day
**Old Model** — Create a [Workcycle Exception](./workcycle-exceptions/workcycle-exception):
```http Create Exception theme={null}
POST /api/v3/workcycleExceptions HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={api_key}
Content-Type: application/json
{
"ownerId": 42,
"startsAt": "2026-06-15T00:00:00",
"isAm": true,
"duration": "00:00:00",
"unit": 1
}
```
This tells the system: "Employee #42 will not work on the morning of June 15th" (in hours unit).
**New Model** — Replace [Shift Overrides](./shift-overrides/shift-override) for the employee on that date:
```http Override theme={null}
PUT /schedule/api/shift-overrides?employee.id=42&startsAt.between=2026-06-15--2026-06-15 HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={api_key}
Content-Type: application/json
[
{
"employeeId": 42,
"position": "firstHalf",
"startsAt": "2026-06-15T00:00:00",
"duration": { "unit": "hours", "iso": "PT0H" },
"nature": "off"
}
]
```
The Shift Override PUT endpoint uses **replace semantics**: all existing overrides for the employee within the
specified date range are removed and replaced with the ones you provide. To clear all overrides for a period,
send an empty array `[]`.
### Assigning a new schedule to an employee (New Model only)
To change the Working Time Arrangement assigned to an employee:
```http Assign theme={null}
POST /schedule/api/employee-assignments HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={api_key}
Content-Type: application/json
{
"employeeId": 42,
"workingTimeArrangementId": 7,
"startsOn": "2026-07-01"
}
```
This will:
End the employee's current assignment on June 30th (the eve of the new start date).
Create a work-contract amendment effective July 1st with the new Working Time Arrangement.
***
## Model comparison at a glance
| Aspect | Old Model | New Model |
| :------------------- | :------------------------- | :---------------------------------------------------- |
| Base schedule | Workcycle | Working Time Arrangement + Collective Schedule |
| Assignment mechanism | V3 User `userWorkcycles` | Employee Assignment (creates work-contract amendment) |
| One-time override | Workcycle Exception | Shift Override |
| Override API style | POST individual exceptions | PUT replaces all overrides in a date range |
| Computed result | UserDate | UserDate |