canonical: https://jentic.com/apis/lucca.fr/lucca

# Lucca Fr Lucca HR API

Lucca is a French HR management platform whose API spans directory, time tracking, absences, expenses, training, compensation, office management, meal vouchers, invoicing, and project management. The 163 endpoints are tag-grouped by Lucca product (Lucca Absences, Lucca Expenses, Lucca Office, Lucca Project, Lucca Timesheet, Lucca Training, Lucca-Compensation, Lucca-MealVoucher, Lucca.Files, Directory) so integrations can scope to the modules an employer has activated. Authentication uses an API key sent in the Authorization header against the employer's own ilucca.net instance.

## For AI agents

Run Lucca HR workflows - directory, absences, time, expenses, meal vouchers, training, compensation, office, and project endpoints - across 163 operations behind an API key on the employer's ilucca.net instance.

## Scope

Does not handle French payroll bank-file generation, social-security filings, or non-French statutory rules - use for Lucca directory, absences, expenses, meal vouchers, time, training, compensation, and project operations only.

## Capabilities

- Read and update the employee directory including departments, roles, and reporting lines
- Submit and approve absence and leave records across the Lucca Absences module
- Create, list, and update expense claims and individual expense items including receipts
- Manage meal-voucher statutories, distributions, and per-employee computations
- Track timesheet entries and project-time allocations across the Lucca Timesheet and Project modules
- Manage training catalogues and employee training records via Lucca Training
- Read compensation grids and run compensation reviews via Lucca-Compensation

## Use cases

### Expense automation for French employers

Finance teams use Lucca's Expenses endpoints to ingest receipts, validate items, and roll them up into claims that trigger reimbursement payroll runs. The API distinguishes ExpenseTempItems (pending) from ExpenseClaimItems (committed), so an OCR pipeline can stage temporary items before the employee finalises a claim. Most teams ship the integration in a couple of weeks.

Example prompt: POST `/api/v3/expenseTempItems` for each OCR'd receipt, then POST `/api/v3/expenseClaims/creation` grouping the temp items for the employee.

### Absence and leave self-service

HR portals call the Lucca Absences endpoints to let employees submit leave requests, view balances, and receive approvals - without the admin opening Lucca directly. The directory endpoints supply manager hierarchy so the right approver receives the request, and the Absences workflow handles the approval state transitions.

Example prompt: Look up the employee and their manager via Directory, then submit the absence request through Lucca Absences and notify the manager.

### Meal-voucher reconciliation

Payroll teams reconcile monthly meal-voucher distributions using the statutory and computation endpoints. `/mealvoucher/api/statutories` lists the active statutories, the parameters endpoint exposes thresholds, and the computations endpoint returns per-employee detail so payroll can confirm totals before the bank file is generated. The dedicated MealVoucher tag keeps the workflow scoped.

Example prompt: GET `/mealvoucher/api/statutories`, then for each statutory iterate its distributions and computations to compile the monthly per-employee totals.

### Project timesheet roll-up for client billing

Services firms use the Lucca Timesheet and Project endpoints to roll up billable hours by client and project before invoicing. The API exposes time entries against project codes, so the billing workflow extracts the week's entries, applies the client rate card, and produces the invoice line items without manual time-export.

Example prompt: Pull this week's time entries for a project, sum hours per employee, multiply by the rate card, and post invoice lines into the billing system.

### Agent-driven HR concierge via Jentic

An AI HR concierge in a workplace chat answers questions like 'what is my remaining holiday?' and 'submit my expenses for last week' by calling Lucca through Jentic. The agent navigates the 10-product surface using Jentic's intent search rather than reading the developer portal, and the API key never enters the chat context.

Example prompt: Use Jentic to search 'submit lucca expense claim', load POST `/api/v3/expenseClaims/creation`, and execute it with the temp items the agent has already staged for the employee.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v3/expenseClaims` | List expense claims |
| POST | `/api/v3/expenseClaims/creation` | Create a new expense claim |
| GET | `/api/v3/expenseTempItems` | List temporary expense items |
| POST | `/api/v3/expenseTempItems` | Create a temporary expense item |
| GET | `/mealvoucher/api/statutories` | List meal-voucher statutories |
| GET | `/mealvoucher/api/statutories/{statutoryId}/distributions` | List a statutory's distributions |
| GET | `/mealvoucher/api/computations/{computationId}/details` | Retrieve a meal-voucher computation's details |
| GET | `/api/v3/expenseClaimItems` | List expense claim items |

## Key resources

- **Directory** — Employee directory with departments, roles, and reporting structure
- **Lucca Absences** — Submit, approve, and report on absence and leave records
- **Lucca Expenses** — Manage expense temp items, expense claims, and expense claim items
- **Lucca-MealVoucher** — Statutories, parameters, distributions, and computations for meal vouchers
- **Lucca Timesheet** — Time entries by employee, project, and date
- **Lucca Project** — Project codes and project time allocations
- **Lucca Training** — Training catalogue and per-employee training records
- **Lucca-Compensation** — Compensation grids and review cycles
- **Lucca Office** — Office and seat management endpoints
- **Lucca.Files** — Attachments and file uploads referenced from other Lucca records

## Why Jentic

- **Setup:** Wiring the Lucca HR API by hand means setting the Authorization header to its 'lucca application={key}' format, pointing at your own {instance}.ilucca.net subdomain, and threading one key across directory, absence, expense, meal-voucher, time, training, and compensation paths. Through Jentic you install once, import the Lucca HR API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** You choose which Lucca operations the agent may call, so you can limit it to the ones it needs, such as listing expense claims or reading meal-voucher distributions, and leave out writes like creating an expense claim unless you add them. Because you pick the operation set, the agent only ever touches the parts of the HR directory you allow.
- **Credential handling:** Your Lucca key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit a Lucca expense claim' or 'list absences', and Jentic returns the matching Lucca operation with its input schema so the agent calls the right endpoint without knowing which product tag owns the path.

## Related APIs

- **Personio API** — European HR platform covering employees, absences, and basic payroll across multiple countries
- **Factorial HR API** — All-in-one HR platform covering people, time, and basic payroll across Europe
- **Loket.nl API** — Dutch payroll engine that pairs with HR-of-record systems to handle Netherlands payroll
- **Calendly API** — Scheduling API for HR meetings, reviews, and onboarding sessions

## FAQ

### What authentication does the Lucca HR API use?

Lucca uses an API key sent in the Authorization header (luccaApiKey scheme) against the employer's own ilucca.net instance - for example https://acme.ilucca.net. Through Jentic, the key and instance hostname are stored together in the vault so the agent only refers to 'the Lucca tenant for employer X'.

### Can I submit an expense claim through the Lucca HR API?

Yes. Stage receipts as ExpenseTempItems via POST `/api/v3/expenseTempItems`, then group them into a claim with POST `/api/v3/expenseClaims/creation.` List endpoints (`/api/v3/expenseClaims`, `/api/v3/expenseClaimItems`) confirm the result before the manager approves.

### What are the rate limits for the Lucca HR API?

Lucca enforces per-instance rate limits and returns HTTP 429 when exceeded; published guidance is to back off and retry. Because the API is partitioned by employer instance (each tenant on its own ilucca.net subdomain), one customer's traffic does not affect another's quota.

### How do I list meal-voucher distributions through Jentic?

Search Jentic for 'list lucca meal voucher distributions', load GET `/mealvoucher/api/statutories/{statutoryId}/distributions`, and execute it with the statutory ID. Combine with GET `/mealvoucher/api/statutories` first to find the active statutory for the period.

### Does the Lucca HR API cover compensation reviews?

Yes - the Lucca-Compensation tag exposes endpoints for compensation grids and review cycles, so a compensation tool can read current grids and post review outcomes back to Lucca.

### How are the 163 Lucca endpoints organised?

By product tag - Directory, Lucca Absences, Lucca Expenses, Lucca Office, Lucca Project, Lucca Timesheet, Lucca Training, Lucca-Compensation, Lucca-MealVoucher, and Lucca.Files. When using Jentic, search by the intent ('submit expense claim') rather than navigating tags manually.

### Can I limit what my agent is allowed to do with the Lucca HR API?

Yes. Because you run Jentic One yourself, your own rules decide which Lucca operations the agent may call and which credentials it may use. You can grant only the operations it needs, such as GET `/api/v3/expenseClaims` to list claims or GET `/mealvoucher/api/statutories` to read meal-voucher distributions, and leave out writes like POST `/api/v3/expenseClaims/creation` unless you add them. Since you pick the operation set, the agent only ever touches the parts of the Lucca directory, absences, and expense modules you allow.