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:

Base recurring schedule — defines the default working hours for each day of the week (possibly alternating odd/even weeks).
Public Holidays — days marked as non-working in the employee’s public-holidays calendar override the base schedule.
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)

Resource	Role
Workcycle	A recurring weekly pattern of working hours, assigned to employees via their V3 User’s `userWorkcycles` property.
Workcycle Exception	A 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)

Resource	Role
Working Time Arrangement (WTA)	Replaces the Workcycle. Defines recurring working hours, contractual time, full-time equivalent, and associated rules.
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	Links a Working Time Arrangement to an employee for a given period (via a work-contract amendment).
Shift Override	Replaces 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:

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:

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:

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

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Get Started with the Schedule API

Key concepts

Two co-existing models

Old Model (Workcycles)

Workcycle

Workcycle Exception

New Model (Working Time Arrangements)

Working Time Arrangement

Collective Schedule

Employee Assignment

Shift Override

The UserDate: reading the effective schedule

Understanding time units

Typical integration scenarios

Reading an employee’s schedule

Overriding an employee’s schedule for one day

Assigning a new schedule to an employee (New Model only)

Model comparison at a glance

​Key concepts

​Two co-existing models

​Old Model (Workcycles)

Workcycle

Workcycle Exception

​New Model (Working Time Arrangements)

Working Time Arrangement

Collective Schedule

Employee Assignment

Shift Override

​The UserDate: reading the effective schedule

​Understanding time units

​Typical integration scenarios

​Reading an employee’s schedule

​Overriding an employee’s schedule for one day

​Assigning a new schedule to an employee (New Model only)

​Model comparison at a glance

Key concepts

Two co-existing models

Old Model (Workcycles)

New Model (Working Time Arrangements)

The UserDate: reading the effective schedule

Understanding time units

Typical integration scenarios

Reading an employee’s schedule

Overriding an employee’s schedule for one day

Assigning a new schedule to an employee (New Model only)

Model comparison at a glance