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 the last synchronization date{lastSyncDateTime}
.
This synchronization can be done on an users establishment basis leavePeriod.owner.legalEntityId
in order to be executed at hours, thus taking into account the 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. This should not be a problem as long as all legal entities are synchronized.
Prerequisites
You 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 most commonly relevant ones:(integer) id
: unique identifier of the leave.(date) date
: date of the leave.(boolean) isAm
: half day:true
for the morning orfalse
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) leavePeriod.confirmationDate
: time-stamp of the confirmation of the leave.
?fields=a,b,c
query parameter (separated by commas). For example to retrieve all the fields listed above:
Paging
The leaves endpoint is paginated. It is therefore impossible to retrieve more than 10,000 items in a single GET request. Paging is done through the paging request parameter which takes two arguments: the index in the collection of the first element to return start (starts at zero) and the number of elements to return limit (maximum 10,000 on the leaves API). 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.
collection.count
field:
collection.count
field can therefore be sent to retrieve this value, and the sequence of paginated calls shall follow.
Retrieve created & confirmed leaves
The parameters of the request are the following:(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.
Retrieve unconfirmed leaves
The parameters of the request are the following:(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.
Retrieve deleted leaves
(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.