> ## Documentation Index
> Fetch the complete documentation index at: https://developers.lucca.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Import user locations

## Introduction

The import feature is the only way to create and update user-locations.

This guide explains how to achieve this, through four steps:

<Steps titleSize="h3">
  <Step title="Format Your CSV File">
    Make sure your file conforms to the expected CSV formatting.
  </Step>

  <Step title="Analyze Your CSV File">
    Check if there's any error with your CSV file by uploading it with the `?create=false` query parameter.
  </Step>

  <Step title="Import Your File">
    Once there's no more errors, then your may upload it for processing with the `?create=true` query parameter.
  </Step>

  <Step title="Track The Import Progress">
    Import may take a while depending on the number of rows, you can poll for its progress through the API.
  </Step>
</Steps>

<Tip>You need to give your API key the `Import schedule` permission in Lucca Office.</Tip>

***

## 1. Format Your CSV File

<CardGroup cols={2}>
  <Card title="UTF-8 encoded">
    The CSV file must be **UTF-8** encoded (with BOM).
  </Card>

  <Card title="Semi-colon column divider">
    The expected divider between columns is a semi-colon character ";". Make sure to escape this character in cell values.
  </Card>
</CardGroup>

Here are the available columns:

| Header             | Description                                                                                               | Required | Type                                             |
| :----------------- | :-------------------------------------------------------------------------------------------------------- | -------- | :----------------------------------------------- |
| `login`            | Login of the employee.                                                                                    | ✅        | `string`                                         |
| `workLocationName` | Name of the work location in Lucca Office (can be found in the work location admin page).                 | ✅        | `string`                                         |
| `areaName`         | Name of the work location in Lucca Office (can be found in the work location admin page).                 | ❌        | `string`                                         |
| `date`             | Date of the user location.                                                                                | ✅        | `Date<'YYYY-MM-DD' \| 'YYYY/MM/DD'>`             |
| `position`         | The granularity of the user-location.                                                                     | ✅        | `Enum<'FullDay' \| 'FirstHalf' \| 'SecondHalf'>` |
| `comment`          | Optional comment associated with the user location.                                                       | ❌        | `string`                                         |
| `isDeletion`       | Whether the existing user-location for this day and employee should be deleted (`true`) or not (`false`). | ❌        | `bool` (default: false)                          |

<Tip>Make sure to include the exact column headers in the first row of your CSV, as these are used for identification.</Tip>

<Tip>As a result, you'll obtain one row per day or half-day of each employee.</Tip>

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.

<CodeGroup>
  ```csv Example theme={null}
  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
  ```
</CodeGroup>

***

## 2. Upload Your File For Analysis

<CodeGroup>
  ```http Analyze The CSV File theme={null}
  POST /work-locations/public/api/imports/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}
  ```
</CodeGroup>

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:

<CodeGroup>
  ```http Track Analysis Progress theme={null}
  GET /work-locations/public/api/imports/user-locations/progress?summaryId={summaryId}
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  ```
</CodeGroup>

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.

<CodeGroup>
  ```http Retrieve The Analysis Results theme={null}
  GET /work-locations/public/api/imports/user-locations/analysis?summaryId={summaryId}
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  ```
</CodeGroup>

***

## 3. Process Import

<Warning>Please note that an import, once launched, cannot be undone.</Warning>

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.

<CodeGroup>
  ```http Process Import theme={null}
  POST /work-locations/public/api/imports/user-locations?create=true&overrideUserLocations=false
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: multipart/form-data
  Form: file={file}
  ```
</CodeGroup>

Make sure to keep the `summaryId` returned by the server.

<CodeGroup>
  ```http Track Progress of Import Processing theme={null}
  GET /work-locations/public/api/imports/user-locations/progress?summaryId={summaryId}
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  ```
</CodeGroup>

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).

<CodeGroup>
  ```http Retrieve Import Results theme={null}
  GET /work-locations/public/api/imports/user-locations/results?summaryId={summaryId}
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  ```
</CodeGroup>