Import vs. Replace entitlements

Introduction

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

Choosing the right endpoint is critical: they have very different consequences on employee leave balances.

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

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.

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:

LegalEntityCode;EmployeeNumber;LastName;FirstName;CP 2024/2025;RTT 2025
001;10045;Doe;Jane;25;10
001;10046;Smith;John;20;8

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

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)

{
  "globalErrors": [],
  "lineErrors": [],
  "successLinesCount": 2
}

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.

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.

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

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`

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

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

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

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Import vs. Replace entitlements

Introduction

Key differences

File format (both endpoints)

Query parameters (both endpoints)

Response format (both endpoints)

Import entitlements

Form-data fields

Example request

Replace entitlements

Supported entry types

Form-data fields

Example request

​Introduction

​Key differences

​File format (both endpoints)

​Query parameters (both endpoints)

​Response format (both endpoints)

​Import entitlements

​Form-data fields

​Example request

​Replace entitlements

​Supported entry types

​Form-data fields

​Example request

Introduction

Key differences

File format (both endpoints)

Query parameters (both endpoints)

Response format (both endpoints)

Import entitlements

Form-data fields

Example request

Replace entitlements

Supported entry types

Form-data fields

Example request