A leave is a period an employee takes off work while he should otherwise be working. Employees are entitled to these either by law or by contract.

The leave-account & details

A leave references a leave-account which represents the type of leave: annual leaves, maternity, sick leave, etc... The leave-account determines:

  1. The unit (days, hours) of any leave taken on this leave-account.
  2. Whether some extra details are needed on leave taken on this leave-account. For example, companies in France are required to give a lot of details when it comes to sick leaves. Otherwise, these details should be left null.

The leave status

The leave status indicates whether the leave resource should be considered valid (i.e. the company management gave its approval) or not.

The leave-request

A leave may be subject to an approval process by the management. In this case, it must be created with the "pending" status (an "approved" leave needs no further approval) which then automatically creates a leave-request for this leave.

If a leave is created with an "approved" status, then it has no leave-request, and its status may then be changed directly through a PATCH request. The only available status would then be "cancelled".

Half-days of absence

An employee may work in the morning, and take the afternoon off, and vice versa. The startPosition and endPosition attributes represent this behavior. For example, taking the Jan. 2nd afternoon off:

{
"startsOn": "2023-01-02",
"startPosition": "secondHalfDay",
"endsOn": "2023-01-02",
"endPosition": "secondHalfDay"
}
​
id
string
default:1
required

Unique identifier of the leave

​
type
string
required
Allowed value: "leave"
​
url
string<uri>
required
​
startsOn
string<date>
required

Date (only). First day (included) of this employee's leave.

​
endsOn
string<date>
required

Date (only). Last day (included) of this employee's leave.

​
employee
object
required

Reference to an employee resource.

Examples:
{
  "id": "416",
  "type": "employee",
  "url": "https://example.ilucca.net/lucca-api/employees/416"
}
​
leaveAccount
object
required

Reference to a leave-account resource.

Examples:
{
  "id": "754",
  "type": "leave-account",
  "url": "https://example.ilucca.net/lucca-api/leave-accounts/754"
}
​
startPosition
enum<string>
default:firstHalfDay

Does this leave start on the first half-day (often: "morning") or the second one (often: "afternoon")? Either the first (i.e. "morning") or the second (i.e. "afternoon") half day.

Available options:
firstHalfDay,
secondHalfDay
​
endPosition
enum<string>
default:secondHalfDay

Does this leave end on the first half-day (often: "morning") or the second one (often: "afternoon")? Either the first (i.e. "morning") or the second (i.e. "afternoon") half day.

Available options:
firstHalfDay,
secondHalfDay
​
days
leave-day · object[]

Read-only. Lists the days or half-days (when on two different leave-accounts) of absence. It is automatically calculated by the server depending on the leave-account settings (e.g. should Saturdays be included?).

Maximum length: 365
​
totalDuration
object

ISO 8601 formatted time interval. More about this in the documentation. Examples:

  • "35 hours": {"value": 35, "iso": "P1DT11H", "unit": "hours"}
  • "5 days": {"value": 5, "iso": "P5D", "unit": "days"} Depending on the related leave-account, a leave may be taken in hours or in days. This attribute sums up the duration of the leave on all of the days it covers. Can only be written on when creating a leave in "hours" unit.
Examples:
{
  "iso": "PT35H",
  "value": 35,
  "unit": "days"
}
​
status
enum<string>

Depends on the status of this leave's related leave-request.

  • tentative: the leave is uncertain as it has yet to be confirmed.
  • confirmed: the leave will definitely be taken.
  • cancelled: the leave was finally cancelled, either through the approval workflow or by the employee.
Available options:
tentative,
confirmed,
cancelled
​
details
object | null

Extension object. Definition depends on the type of leave. Some leave-accounts required further details about the leave. This is typically the case for sick leaves in France. In this case, set these details in this object. Otherwise, you can just leave this null. "Maladie ordinaire" Common sickness.

​
createdAt
string<date-time>

Timestamp of this leave creation.

​
lastUpdatedAt
string<date-time>

Timestamp of the time this leave was last updated.

​
links
object | null