​
Introduction

The import feature is the only way to create and update user-locations. This guide explains how to achieve this, through four steps:
1

Format Your CSV File

Make sure your file conforms to the expected CSV formatting.
2

Analyze Your CSV File

Check if there’s any error with your CSV file by uploading it with the ?create=false query parameter.
3

Import Your File

Once there’s no more errors, then your may upload it for processing with the ?create=true query parameter.
4

Track The Import Progress

Import may take a while depending on the number of rows, you can poll for its progress through the API.
You need to give your API key the Import schedule permission in Lucca Office.

​
1. Format Your CSV File

UTF-8 encoded

The CSV file must be UTF-8 encoded (with BOM).

Semi-colon column divider

The expected divider between columns is a semi-colon character ”;”. Make sure to escape this character in cell values.
Here are the available columns:
HeaderDescriptionRequiredType
loginLogin of the employee.✅string
workLocationNameName of the work location in Lucca Office (can be found in the work location admin page).✅string
areaNameName of the work location in Lucca Office (can be found in the work location admin page).❌string
dateDate of the user location.✅Date<'YYYY-MM-DD' | 'YYYY/MM/DD'>
positionThe granularity of the user-location.✅Enum<'FullDay' | 'FirstHalf' | 'SecondHalf'>
commentOptional comment associated with the user location.❌string
isDeletionWhether the existing user-location for this day and employee should be deleted (true) or not (false).❌bool (default: false)
Make sure to include the exact column headers in the first row of your CSV, as these are used for identification.
As a result, you’ll obtain one row per day or half-day of each employee.
Please note:
  • the login can be found by using the Users or Employee API endpoints.
  • workLocationName and areaName can be found by using Work-locations API.
login;firstName;lastName;workLocationName;areaName;date;position;comment;isDeletion
jdupont;Jean;Dupont;Paris;Service Client;2025/09/18;FullDay;;false
mlefevre;Marie;lefevre;Nantes;B1;2025/09/19;SecondHalf;this is a comment;false

​
2. Upload Your File For Analysis

POST /work-locations/public/api/import/user-locations?create=false&overrideUserLocations=false HTTPS/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: multipart/form-data
Form: file={file}
The server will respond with a summaryId, make sure to keep a note of it, you’ll need it. For example, you can use it to track the progress of the analysis: 
GET /work-locations/public/api/import/user-locations/progress?summaryId={summaryId}
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Once processing is done, you may retrieve the analysis results, which are comprised of:
  • Errors: these will block any proper import and thus must be fixed.
  • Warnings: point out minor inconsistencies in the corresponding rows, but they can still be imported successfully.
GET /work-locations/public/api/import/user-locations/analysis?summaryId={summaryId}
Host: example.ilucca.net
Authorization: lucca application={API_KEY}

​
3. Process Import

Please note that an import, once launched, cannot be undone.
The actual import processing is triggered in the same way as the analysis. The only difference being the ?create=true query parameter. Feel free to set the overrideUserLocations query parameter to true if you want to replace existing User Locations. 
POST /work-locations/public/api/import/user-locations?create=true&overrideUserLocations=false
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: multipart/form-data
Form: file={file}
Make sure to keep the summaryId returned by the server. 
GET /work-locations/public/api/import/user-locations/progress?summaryId={summaryId}
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Once processing is done, you may retrieve the results, which are comprised of:
  • Errors indicate lines were not imported.
  • Warnings point out minor inconsistencies in the corresponding rows, but still, they were imported successfully.
Other rows were processed successfully (creations, updates or even deletions). 
GET /work-locations/public/api/import/user-locations/results?summaryId={summaryId}
Host: example.ilucca.net
Authorization: lucca application={API_KEY}