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
required
​
startsOn
string
required

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

​
endsOn
string
required

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

​
employee
object
required

Reference to an employee resource.

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

Reference to a leave-account resource.

Example:
{
  "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")?

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")?

Available options:
firstHalfDay,
secondHalfDay
​
days
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?).

​
totalDuration
object

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.

Example:
{
  "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

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.

​
createdAt
string

Timestamp of this leave creation.

​
lastUpdatedAt
string

Timestamp of the time this leave was last updated.

​
links
object | null

Was this page helpful?