Skip to main content

​
Introduction

This is a guide aimed at helping you achieving the synchronization of all leaves edited in Lucca Absences with a third-party app. The implementation is a regular synchronization of all leaves that have been created, deleted or modified by the users since your last synchronization attempt {lastSyncDateTime}. This process can be done on an users business-establishment basis leavePeriod.owner.legalEntityId in order to adapt to different time zones.
About legal establishments filtering: Be careful, this filter on the establishments is applied on the current establishment of the user (at the time of the request), and not his establishment at the time of the leave creation / confirmation / deletion. You’ll get eventual consistency as long as all establishments are synchronized.
Please note that the server will return the latest state of each leave (rather than the difference since the last synchronization). So your synchronization logic should be “delete and replace”:
  1. Delete if cancellationDate is not null;
  2. Update or insert otherwise.

​
Prerequisites

You’ll need:
  • (required) Your domain name {yourDomain}, eg: “https://myawesomecompany.ilucca.net”.
  • (required) An API key {apiKey} that has access to the leaves of the users concerned by your integration project. This key should be created with the help of a Lucca Customer Success Manager.
  • (optional) When filtering on legal establishments, the unique identifiers of said establishments.

​
Fields

Leaves have a large number of fields. A complete list of all fields can be found in the API reference. Here are the commonly used ones:
  • (integer) id: unique identifier of the leave.
  • (date) date: date of the leave.
  • (boolean) isAm: half day: true for the morning or false for the afternoon.
  • (integer) ownerId: identifier of the user.
  • (date-time) creationDate: time-stamp of the creation of the leave.
  • (string) comment: comment.
  • (date-time) cancellationDate: time-stamp of the cancellation of the leave.
  • (date-time) leavePeriod.confirmationDate: time-stamp of the confirmation of the associated leave-period (a leave-period is a set of consecutive leaves that were requested simultaneously).
Fields are requested via the fields query parameter, which accepts a comma-separated list of field names. Example: 
GET /api/v3/leaves?leavePeriod.ownerId=416&date=between,2025-01-01,2025-12-31&fields=id,date,isAm,ownerId,creationDate,comment,cancellationDate,leavePeriod[confirmationDate],collection.count&paging=0,1 HTTP/1.1
Host: {yourDomain}
Authorization: application={apiKey}
Accept: application/json

> Response
{
  "data": {
    "count": 1,
    "items": [
      {
        "id": 176,
        "date": "2021-01-01",
        "isAm": true,
        "ownerId": 416,
        "leavePeriod": {
          "confirmationDate": "2020-12-27 13:42:12"
        }
      }
    ]
  }
}

​
Paging

The leaves endpoint is paginated. Paging is handled through the paging request parameter which takes two arguments: the index of the first element in the collection to return start (starts at zero) and the number of elements to return per page (maximum 10,000). For example, to return 100 elements from the 15th: ?paging=14,100.
We recommend not to exceed 1,000 results per page in order to guarantee satisfactory response times.
The total number of elements across all pages that meet the criteria of the query can be retrieved through the collection.count field: 
GET /api/v3/leaves?leavePeriod.ownerId=notequal,0&date=since,2025-01-01&fields=collection.count HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  "data": {
    "count": 2874,
    "items": [
      {
        "id": 1
      }
    ]
  }
}
From then on, it is possible to predict the total number of pages that it will be necessary to request: 
// Javascript:
var itemsPerPage = 100;
var responseBodyJSON = JSON.parse(response.data);
var pageCount = Math.ceil(responseBodyJSON.data.count / itemsPerPage);
A first request asking only for the collection.count field can therefore be sent to retrieve this value, and the sequence of paginated calls shall follow.

​
Retrieve Created & Confirmed Leaves

Confirmed leaves are leaves that have been approved by a manager. Only confirmed leaves should be considered as effective.
The parameters of the request are the following:
  • (required) (int) {leavePeriod.ownerId}: bounding the request to a set of owners is required by the server, send ?leavePeriod.ownerId=notequal,0 to retrieve leaves of ALL users.
  • (required) (date) {maxRange}: UTC date in ISO-8601 format, eg: 2021-01-01. This parameter is used to avoid retrieving leaves that are too far in the past.
  • (date-time) {lastSyncDateTime}: UTC date and time of the last synchronization in ISO-8601 format, eg: 2021-01-01T08:25:45Z.
  • (integer) {offset}: index of the first element to be returned (paging). Starts at zero.
  • (integer) {limit}: number of elements to return (pagination). Maximum value: 10,000.
  • (optional) (array<integer>) {legalEntityIds}: filter on the establishment(s) of the declarants (separated by commas). Allows to return only the time-entries of employees of one or several establishments targeted by their identifier.
  • (array<string>) {fields}: the list of fields (see section above) separated by a comma that you want to retrieve.
Since the maximum precision is the minute, and to avoid forgetting any leaves modified at the same time as the synchronization procedure (it is paged), it is recommended to round down at least to the nearest minute, if not more. 
GET /api/v3/leaves?leavePeriod.ownerId=notequal,0&date=since,{maxRange}&leavePeriod.confirmationDate=since,{lastSyncDateTime}&paging={offset},{limit}&owner.legalEntityId={legalEntityIds}&fields={fields} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  "data": {
    "count": 1298,
    "items": [...]
  }
}

​
Retrieve Unconfirmed Leaves

Unconfirmed leaves are leaves that have been created but not yet approved by a manager. These should be considered “tentative” leave requests.
The parameters of the request are the following:
  • (required) (int) {leavePeriod.ownerId}: bounding the request to a set of owners is required by the server, send ?leavePeriod.ownerId=notequal,0 to retrieve leaves of ALL users.
  • (required) (date) {maxRange}: UTC date in ISO-8601 format, eg: 2021-01-01. This parameter is used to avoid retrieving leaves that are too far in the past.
  • (date-time) {lastSyncDateTime}: UTC date and time of the last synchronization in ISO-8601 format, eg: 2021-01-01T08:25:45Z.
  • (integer) {offset}: index of the first element to be returned (paging). Starts at zero.
  • (integer) {limit}: number of elements to return (pagination). Maximum value: 10,000.
  • (optional) (array<integer>) {legalEntityIds}: filter on the establishment(s) of the declarants (separated by commas). Allows to return only the leaves of employees of one or several establishments targeted by their identifier.
  • (array<string>) {fields}: the list of fields (see section above) separated by a comma that you want to retrieve.
  • (bool) leavePeriod.isconfirmed: set to false to retrieve only unconfirmed leaves.
Since the maximum precision is the minute, and to avoid forgetting any leaves modified at the same time as the synchronization procedure (it is paged), it is recommended to round down at least to the nearest minute, if not more. 
GET /api/v3/leaves?leavePeriod.ownerId=notequal,0&date=since,{maxRange}&creationDate=since,{lastSyncDateTime}&leavePeriod.isconfirmed=false&paging={offset},{limit}&owner.legalEntityId={legalEntityIds}&fields={fields} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  "data": {
    "count": 1298,
    "items": [...]
  }
}

​
Retrieve Deleted (i.e. Cancelled) Leaves

Cancelled leaves are leaves that have been rejected and as a result should be considered as deleted.
The parameters of the request are the following:
  • (required) (int) {leavePeriod.ownerId}: bounding the request to a set of owners is required by the server, send ?leavePeriod.ownerId=notequal,0 to retrieve leaves of ALL users.
  • (required) (date) {maxRange}: UTC date in ISO-8601 format, eg: 2021-01-01. This parameter is used to avoid retrieving leaves that are too far in the past.
  • (date-time) {lastSyncDateTime}: UTC date and time of the last synchronization in ISO-8601 format, eg: 2021-01-01T08:25:45Z.
  • (integer) {offset}: index of the first element to be returned (paging). Starts at zero.
  • (integer) {limit}: number of elements to return (pagination). Maximum value: 10,000.
  • (optional) (array<integer>) {legalEntityIds}: filter on the establishment(s) of the declarants (separated by commas). Allows to return only the leaves of users of one or several establishments targeted by their identifier.
  • (array<string>) {fields}: the list of fields (see section above) separated by a comma that you want to retrieve.
Since the maximum precision is the minute, and to avoid forgetting any leaves modified at the same time as the synchronization procedure (it is paged), it is recommended to round down at least to the nearest minute, if not more. 
GET /api/v3/leaves?leavePeriod.ownerId=notequal,0&date=since,{maxRange}&cancellationDate=since,{lastSyncDateTime}&creationDate=until,{lastSyncDateTime}&isActive=false&paging={offset},{limit}&owner.legalEntityId={legalEntityIds}&fields={fields} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  "data": {
    "count": 1298,
    "items": [...]
  }
}