How To Retrieve TimeEntries

​

Introduction

This guide is aimed at helping you retrieve TimeEntries edited in Lucca Timesheet. For example, you might want to extract daily the TimeEntries from Lucca Timesheet to import them in another reporting system, or your ERP.

If you need to do it the other way around, i.e. feed third-party date into Lucca Timesheet (e.g. a planner, a clock-in clock-out physical device, another time-tracking software, …), please see this other guide.

​

Overview

The implementation consists in a periodical synchronization of all TimeEntries that have been created, deleted or modified by the users since the last time synchronization was performed ({lastSuccessfullSyncDateTime}).

On your side, the implementation should follow a “delete and replace” logic.

This {lastSuccessfullSyncDateTime} must be stored on your side, as the date and time of the last synchronization in Central European Time (CET) and ISO-8601 format, eg: 2021-01-01T08:25:45. It should be updated to the starting DateTime of your synchronization only if the retrieval of timeentries was a success. In case of any technical error, do not update the {lastSuccessfullSyncDateTime} as it will allow you to try again.

Since the maximum precision is the minute, and to avoid forgetting any TimeEntries modified at the same time as the synchronization procedure, it is recommended to round down {lastSuccessfullSyncDateTime} to the nearest minute.

​

Prerequisites

​

Things you will need

• (required) Your domain name {yourDomain}, eg: “https://myawesomecompany.ilucca.net”.
• (required) An API key {apiKey} that has access to the TimeEntries of the users concerned by your integration project.
• (optional) When filtering on legal establishments, the unique identifiers of said establishments.

​

Choosing The Fields You Need

TimeEntries have a large number of fields. Please see the complete list of them in the API reference.

​

Filtering TimeEntries

Always add a layer=notequal,1 filter in your request in order to exclude theoretical working times (these exist for technical reasons). Please always set this to “1”, no questions asked.

Then, to avoid asking for all TimeEntries every time, you will need to filter your requests to retrieve only what changed since your {lastSuccessfullSyncDateTime} using a modifiedAt=since,{lastSuccessfullSyncDateTime}.

The synchronization can optionally be done per owner ownerId or per legal establishment owner.legalEntityId.

​

Paging your request

As the api/v3/timeentries endpoint is paginated, you cannot retrieve more than 10,000 items in a single GET request. Use the collection.count field to get the total number of elements that meet the criteria of your query before iterating over pages of content.

​

Sorting your request

Finally, it is highly recommended to sort results when paging. This can be achieved through the ?orderby={fieldName},{direction} query parameters, that takes two comma-separated values:

• fieldName: the name of the ressource’s field to sort on (recommended: id).
• direction: can be either asc (ascending order) or desc (descending order).

Read more about filtering, paging, and sorting here.

​

Guide

​

1. Retrieve Created or Modified TimeEntries

A first request asking only for the collection.count field to get the number of items matching your filtering criterion.

GET /api/v3/timeentries?layer=notequal,1&modifiedAt=since,{lastSuccessfullSyncDateTime}&paging=0,1&fields=id,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 run a series of paginated requests to retrieve all TimeEntries from first to last page.

GET /api/v3/timeentries?modifiedAt=since,{lastSuccessfullSyncDateTime}&paging={offset},{limit}&owner.legalEntityId={legalEntityIds}&orderby=modifiedAt,asc&fields={fields} HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

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

​

2. Retrieve Deleted (i.e. Archived) TimeEntries

By default, deleted TimeEntries are not returned in GET requests.

If you need to explicitly retrieve TimeEntries that have been deleted, you will need to filter on archivedAt=notequal,null. Or, if you are doing periodic synchronization, archivedAt=since,{lastSuccessfullSyncDateTime}.

GET /api/v3/timeentries?archivedAt=since,{lastSuccessfullSyncDateTime}&paging={offset},{limit}&owner.legalEntityId={legalEntityIds}&orderby=archivedAt,asc&fields={fields} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

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