Skip to main content
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:
  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 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), 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. New integrations should target the New Model whenever possible.

​
Old Model (Workcycles)

ResourceRole
WorkcycleA recurring weekly pattern of working hours, assigned to employees via their V3 User’s userWorkcycles property.
Workcycle ExceptionA one-time override of an employee’s working hours on a specific half-day.

Workcycle

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.

Workcycle Exception

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)

ResourceRole
Working Time Arrangement (WTA)Replaces the Workcycle. Defines recurring working hours, contractual time, full-time equivalent, and associated rules.
Collective ScheduleThe weekly hours pattern within a Working Time Arrangement (WTA) over a given date-range. A WTA can have successive collective schedules over time.
Employee AssignmentLinks a Working Time Arrangement to an employee for a given period (via a work-contract amendment).
Shift OverrideReplaces the Workcycle Exception. A one-time modification to an employee’s schedule on a specific day.

Working Time Arrangement

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.

Collective Schedule

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.

Employee Assignment

Assigns a Working Time Arrangement to an employee starting on a given date. Creating an assignment generates a work-contract amendment automatically.

Shift Override

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 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:
FieldMeaning
dttTheoretical working time — what the employee should work on that day.
drtActual working time — what the employee actually worked (defaults to dtt if no time entry).
drajLeave duration — time absent via leaves.
isHolidayWhether the day is a public holiday.
isWeeklyRestWhether 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:
UnitMeaningExample
DayDurations are expressed as fractions of a day. 12:00:00 = half a day.”I worked half a day”
HourDurations are expressed in hours. 03:30:00 = 3 hours and 30 minutes.”I worked 3h30”
TimeDurations 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: 
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: 
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 for the employee on that date: 
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: 
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:
1
End the employee’s current assignment on June 30th (the eve of the new start date).
2
Create a work-contract amendment effective July 1st with the new Working Time Arrangement.

​
Model comparison at a glance

AspectOld ModelNew Model
Base scheduleWorkcycleWorking Time Arrangement + Collective Schedule
Assignment mechanismV3 User userWorkcyclesEmployee Assignment (creates work-contract amendment)
One-time overrideWorkcycle ExceptionShift Override
Override API stylePOST individual exceptionsPUT replaces all overrides in a date range
Computed resultUserDateUserDate