> ## 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 vs. Replace entitlements

> Understand the differences between Import entitlements and Replace entitlements, their business and technical impact, and how to call each endpoint.

## Introduction

Lucca Absences provides two endpoints for managing leave entitlements via file import:

<Cards columns={2}>
  <Card title="Import entitlements" href="/api-reference/legacy/timmi-absences/guides/entitlements-imports#import-entitlements" cta="View API Reference">
    **Adds** the file values to existing balances
  </Card>

  <Card title="Replace entitlements" href="/api-reference/legacy/timmi-absences/guides/entitlements-imports#replace-entitlements" cta="View API Reference">
    **Adjusts** balances so that entitlement totals match the file values exactly.
  </Card>
</Cards>

<Tip>Choosing the right endpoint is critical: they have **very** different consequences on employee leave balances.</Tip>

## Key differences

| Aspect               | **Import** entitlements                                            | **Replace** entitlements                                                                 |
| :------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| **Behavior**         | File value is **added** to the current balance.                    | File value **becomes** the target total; the system computes and applies the difference. |
| **Idempotency**      | Not idempotent — importing the same file twice doubles the credit. | Effectively idempotent — re-importing produces zero adjustment.                          |
| **Accounting entry** | Credit entry (code `Repor`).                                       | Adjustment entry, positive or negative (code `Auto`).                                    |
| **Typical use case** | Periodic top-up (e.g., "grant 2.08 additional days this month").   | Full sync with an external system (e.g., "this employee should have 25 days total").     |

<Warning>
  With **Import entitlements**, accidentally re-importing a file will double-credit the accounts. Always call with `?simulate=true` query parameter first to preview the result.
</Warning>

## File format (both endpoints)

Accepted formats:

* **CSV** — UTF-8 encoding, semicolon (`;`) separator
* **XLSX**

**Required columns:**

| Column                       | Description                  |
| :--------------------------- | :--------------------------- |
| `LegalEntityCode`            | Employee's legal entity code |
| `EmployeeNumber`             | Employee's payroll number    |
| `LastName`                   | Last name                    |
| `FirstName`                  | First name                   |
| Leave account number or name | Value for each leave account |

**Example CSV:**

<CodeGroup>
  ```csv theme={null}
  LegalEntityCode;EmployeeNumber;LastName;FirstName;CP 2024/2025;RTT 2025
  001;10045;Doe;Jane;25;10
  001;10046;Smith;John;20;8
  ```
</CodeGroup>

<Tip>
  A template file can be downloaded from the Lucca Absences UI: **Credit / Debit > Imports**.
</Tip>

## Query parameters (both endpoints)

| Parameter Name | Type    | Default | Description                                                                                                                                 |
| :------------- | :------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `strict`       | boolean | `false` | When `true`, if any line has errors, **nothing** is imported. When `false`, errored lines are skipped but others are still imported .       |
| `simulate`     | boolean | `false` | When `true`, returns a preview of the import result without persisting any data. Useful for testing out the file before committing changes. |

## Response format (both endpoints)

<CodeGroup>
  ```json theme={null}
  {
    "globalErrors": [],
    "lineErrors": [],
    "successLinesCount": 2
  }
  ```
</CodeGroup>

| Field               | Description                                                                                 |
| :------------------ | :------------------------------------------------------------------------------------------ |
| `globalErrors`      | Fatal errors preventing the entire import (e.g., `FileEmpty`, `ColumnsFormatNotSupported`). |
| `lineErrors`        | Per-line errors (e.g., `EmployeeNumberNotExist`, `AccountNotFound`).                        |
| `successLinesCount` | Number of lines successfully processed.                                                     |

<Tip>
  Always run with `simulate=true` first to validate your file. All imports are recorded in the history and can be reviewed in the Lucca Absences UI.
</Tip>

## Import entitlements

Each call **adds** the file values to the current balance. A file value of `2.08` increases the balance by 2.08 days — regardless of the current total.

### Form-data fields

| Field           | Required | Description                                     |
| :-------------- | :------- | :---------------------------------------------- |
| `File`          | Yes      | The CSV or XLSX import file.                    |
| `Description`   | Yes      | Label visible to users in the account details.  |
| `ReferenceDate` | Yes      | Reference date in `yyyy-MM-ddTHH:mm:ss` format. |

### Example request

```http theme={null}
POST /timmi-absences/api/public/services/v1.0/leaveEntitlementsImport?strict=false&simulate=false HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="File"; filename="entitlements.csv"
Content-Type: application/octet-stream

LegalEntityCode;EmployeeNumber;LastName;FirstName;CP N;RTT
001;10045;Doe;Jane;2.08;0.83
------Boundary
Content-Disposition: form-data; name="Description"

Monthly entitlements credit - April 2026
------Boundary
Content-Disposition: form-data; name="ReferenceDate"

2026-04-01T00:00:00
------Boundary--
```

## Replace entitlements

Each call **sets** the entitlement total to the file value. The system computes `file_value − current_entitlement_total` and creates an adjustment entry for the difference (positive or negative).

The "current entitlement total" is computed only from the entry types specified by the `EntryTypes` parameter. By default: `AutoAccruals`, `ManualAccruals`, `Regularizations`.

### Supported entry types

| Value                | Description                           | Accounting codes included                |
| :------------------- | :------------------------------------ | :--------------------------------------- |
| `AutoAccruals`       | Automatic periodic accruals           | `Auto`, `Rounding`                       |
| `ManualAccruals`     | Manual adjustments by administrators  | `Odsa`, `SemiAuto`, `Manuel`, `Transfer` |
| `Regularizations`    | Regularization entries                | `Regul`, `RegulDeparture`                |
| `EntitlementsImport` | Previous entitlements import entries  | `Repor`                                  |
| `Seniority`          | Seniority-based entitlements          | `Seniority`                              |
| `Fractionnement`     | Fractionnement (French-specific rule) | `Fract`                                  |
| `TimeSavings`        | Time savings account entries          | `TimeSavings`                            |
| `Comp`               | Compensatory time entries             | `Comp`                                   |

<Info>
  To consider **all** entry types when computing the current total, pass all values explicitly. The default only covers the three most common accrual types.
</Info>

### Form-data fields

| Field           | Required | Description                                                                                                                               |
| :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `File`          | Yes      | The CSV or XLSX import file.                                                                                                              |
| `Description`   | Yes      | Label visible to users in the account details.                                                                                            |
| `ReferenceDate` | Yes      | Reference date in `yyyy-MM-ddTHH:mm:ss` format.                                                                                           |
| `EntryTypes`    | No       | Comma-separated list of entry types to consider when computing the current total. Default: `AutoAccruals,ManualAccruals,Regularizations`. |

### Example request

```http theme={null}
POST /timmi-absences/api/public/services/v1.0/leaveEntitlementsReplace?strict=false&simulate=false HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="File"; filename="entitlements.csv"
Content-Type: application/octet-stream

LegalEntityCode;EmployeeNumber;LastName;FirstName;CP N;RTT
001;10045;Doe;Jane;25;10
------Boundary
Content-Disposition: form-data; name="Description"

Payroll sync - April 2026
------Boundary
Content-Disposition: form-data; name="ReferenceDate"

2026-04-01T00:00:00
------Boundary
Content-Disposition: form-data; name="EntryTypes"

AutoAccruals,ManualAccruals,Regularizations
------Boundary--
```