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

# Lucca

> Sync Lucca users, departments, work cycles and Timmi Absences leaves into Pike capacity, and send approved Pike time to Timmi Timesheet.

The Lucca integration syncs users and departments from the Lucca directory into Pike [members](https://usepike.com/docs/members/overview.md) and teams, sets weekly capacity from each user's work cycle, and imports approved Timmi Absences leaves into Pike [time off](https://usepike.com/docs/members/time-off.md). When you turn it on, Pike also sends approved time to Timmi Timesheet at each pay period close, so your team logs hours once.

## At a glance

| | |
| - | - |
| **Direction** | Lucca to Pike for users, departments, work cycles and approved leaves. Pike to Timmi Timesheet for approved time, when turned on |
| **Who sets it up** | Workspace admins, with your Lucca address and a Lucca API key |
| **Plan** | All plans |
| **Sync** | Every 3 hours. On the Enterprise plan, changes sync in real time. |
| **Source of truth** | Lucca for person fields, work cycles and leaves. Pike for capacity, allocations, projects, time and cost profiles |

## Before you start

You need:

* The workspace admin role in Pike.
* Your Lucca address, for example `northlight.ilucca.net`.
* A Lucca API key. A Lucca administrator creates it under **Settings → API keys** with **Generate API key**, and gives it read access to the directory (users), organization structure (departments and legal entities) and Timmi Absences (leaves and leave accounts). To send time, the key also needs write access to Timmi Timesheet time entries. The key syncs only the users and data its rights allow.
* Pike time off types for the Lucca leave accounts you use, such as Congés payés or RTT. You map each leave account during setup. See [Time off](https://usepike.com/docs/members/time-off.md).

## Connect Lucca

**1. Open the integration**

Go to **Workspace settings → Integrations → Lucca** and click **Add
integration**.

**2. Enter your credentials**

Enter your Lucca address and the API key, then click **Connect**. Pike
checks the key and shows your Lucca company name.

**3. Choose legal entities**

Under **Legal entities**, choose which Lucca legal entities sync. Users of
other legal entities do not import.

**4. Map leave accounts**

Under **Time off types**, choose a Pike time off type for each Lucca leave
account. Pike suggests a mapping from the account names.

**5. Choose what syncs**

In the **What syncs with Lucca** card, turn **Read** and **Send** on or off
for each entity, and choose whether to turn on **Invite new employees**.

**6. Import**

Click **Import data**. Departments import first, then users, then work
cycles, then leaves.

The integration page shows **Connected**, the Lucca company name, **Last synced** and **Next sync**.

## What syncs

| Lucca | Pike | Direction |
| - | - | - |
| Users | Members | Lucca to Pike |
| Departments | Teams | Lucca to Pike |
| Legal entities | Which users sync | Chosen in the integration settings |
| Work cycles | Work schedule and capacity per week | Lucca to Pike |
| Leaves from approved requests | Time off | Lucca to Pike |
| Leave accounts | Time off types | Mapped in the integration settings |
| Timmi Timesheet time entries | Approved time from a closed pay period | Pike to Lucca, when **Send time to Timmi Timesheet** is on |

### Users

| Lucca field | Pike field | Notes |
| - | - | - |
| First name, last name | Member name | |
| Email | Member email | Also used to match existing members |
| Job title | Position | A position is created when no Pike position has the same name |
| Department | Team | A team is created when no Pike team has the same name |
| Manager | Manager | When the manager is also a synced user |
| Legal entity | Not stored | Only users of the legal entities you choose import |
| Contract start date | Hire date | |
| Contract end date | Member status | A user whose contract has ended becomes a deactivated member from that date |
| User ID | Lucca ID | Shown on the member as the Lucca marker |

### Work cycles

| Lucca field | Pike field | Notes |
| - | - | - |
| Work cycle | Work schedule | Hours per weekday. Days off in the cycle stay days off |
| Work cycle start date | Schedule start date | A new work cycle sets capacity from its own start date |

The weekly total of the work cycle sets the member's capacity per week. See [Working time](https://usepike.com/docs/members/working-time.md#work-schedule).

### Leaves

| Lucca field | Pike field | Notes |
| - | - | - |
| User | Member | |
| Leave account | Time off type | Through your type mapping |
| Date | Dates | |
| Morning or afternoon | Hours per day | A half-day leave removes only the hours of that half of the day |
| Leave request status | Not stored | Only leaves from approved requests import |

Default type mapping: vacation and Congés payés to Vacation, sick to Sick, parental to Parental, RTT and time off in lieu to Time off in lieu, unpaid to Unpaid leave, and every other account to Vacation. Each type counts toward the member's [norm hours](https://usepike.com/docs/members/working-time.md#norm-hours) as set on the Pike type.

### Send time to Timmi Timesheet

**Send time to Timmi Timesheet** is off by default. When on, closing a [pay period](https://usepike.com/docs/members/payroll.md) in Pike sends each linked member's approved time for the period to Timmi Timesheet as one time entry per day. Only approved entries count.

| Pike | Sent to Timmi Timesheet as |
| - | - |
| Approved hours for each day | A time entry for that day, with the hours |
| Member | The linked Lucca user |

Pike sends the entries as imported time, so employees edit their hours in Pike and not in Timmi Timesheet. The timesheet then follows your Timmi Timesheet approval workflow in Lucca. A correction to a period already sent replaces that period's entries the next time the period is sent.

## Matching and duplicates

On the first import, Pike matches before it creates:

* A user matches a Pike member with the same email. A match links the two, and Lucca values replace the Pike values for the fields in the mapping.
* A department matches a Pike team with the same name. A job title matches a Pike position with the same name.
* Leaves always import as new time off. Time off already entered in Pike for the same member and dates stays, and the Lucca leave is listed in **Sync issues** as an overlap.

A user with no matching member appears under **Unmatched employees** on the integration page. Click **Invite** to send a Pike invite, or **Link to member** to link the user to a member with a different email. With **Invite new employees** on, Pike sends the invite automatically with the default role the admin chose.

## Which system wins

| Entity | Lucca owns | Pike owns |
| - | - | - |
| Members | Name, email, position, team, manager, status, hire date | Role, rates, cost profile, project access, allocations |
| Capacity | Work schedule from the work cycle | Working time policy, allocations |
| Time off | Dates, half days and type of leaves from Lucca | Time off requested in Pike |
| Time entries | Approval of timesheets in Timmi Timesheet | Hours, projects and approval of time in Pike |

Edit Lucca-owned fields in Lucca. Pike shows them as read-only with the Lucca marker.

## Sync schedule

Pike syncs Lucca every 3 hours. On the Enterprise plan, changes sync in real time. Closing a pay period sends time to Timmi Timesheet straight away on every plan, as do **Import data**, **Sync now** and **Refresh**. See [How sync works](https://usepike.com/docs/integrations/how-sync-works.md).

## Sync settings

While Lucca is connected, the **What syncs with Lucca** card is below the top button row on the integration page. Toggles save immediately.

| Entity | Read | Send |
| - | - | - |
| Users | Yes | Not available |
| Work cycles | Yes | Not available |
| Leaves | Yes | Not available |
| Time entries | Not available | Yes, off by default |

New connections start with **Read** on for users, work cycles and leaves, every legal entity selected, **Invite new employees** off, and **Send time to Timmi Timesheet** off.

## How it works

```mermaid theme={"system"}
sequenceDiagram
  participant Person as Employee in Lucca
  participant Manager as Manager in Lucca
  participant Lucca
  participant Pike
  participant Admin as Admin in Pike
  Person->>Lucca: Request RTT for Wednesday afternoon
  Manager->>Lucca: Approve the request
  Lucca->>Pike: Approved leave, on the next sync or in real time
  Pike->>Pike: Remove 4 hours from Wednesday capacity
  Admin->>Pike: Close the October pay period
  Pike->>Lucca: Approved time as Timmi Timesheet entries
  Lucca-->>Manager: Timesheet ready for approval in Timmi Timesheet
```

## Use it in Pike

### Plan around approved leave

Open **Members → Allocations** to see each person's capacity for the week. Approved Lucca leaves show on the day with their type, and a half-day leave removes only its half of the day, so an over-allocated day stands out before the work is due. See [Workspace capacity](https://usepike.com/docs/allocation/workspace-capacity.md).

### Onboard a new hire

When a new user is added to the Lucca directory, they appear in Pike with their team, position and work schedule on the next sync. Turn on **Invite new employees**, or click **Invite** under **Unmatched employees**, and the person can log time on their first day.

### Offboard a leaver

When a user's contract end date passes in Lucca, the member is deactivated in Pike from that date. Their logged time, allocations and history stay on every project, and they stop counting toward capacity from the end date.

### Log time once

With **Send time to Timmi Timesheet** on, your team logs time against projects in Pike. Closing the pay period sends the approved hours to Timmi Timesheet, so nobody types the same week into Lucca.

## Deletes and removed records

An integration never deletes Pike data. A user deleted in Lucca is marked **Removed in Lucca** on the member, stays in Pike with their history, and stops syncing. A leave canceled in Lucca after approval is removed from Pike capacity on the next sync, and the change appears in the member's time off history.

## Troubleshooting

| Symptom | Fix |
| - | - |
| A user is missing in Pike | Check that the user's legal entity is selected under **Legal entities**, and that the API key can read that user. Then click **Sync now**. |
| A user shows under **Unmatched employees** | The email in Lucca differs from the member's email in Pike. Click **Link to member**, or correct the email in Lucca. |
| Weekly capacity is wrong | Check the user's current work cycle in Lucca. Then click **Refresh** on the member. |
| Approved leave is missing | Check that **Read** is on for leaves and that the request is approved in Lucca. Then click **Refresh** on the member. |
| Time off shows the wrong type | The Lucca leave account maps to a different Pike type. Change it under **Time off types**. Existing time off updates on the next sync. |
| **Sync issues** lists an overlap | Time off for the same dates already exists in Pike. Delete the Pike entry, then click **Retry**. |
| **Sync issues** lists a permission error on time entries | The API key has no write access to Timmi Timesheet. Ask a Lucca administrator to add it, then click **Retry**. |
| **Sync issues** lists an authentication error | The API key was deleted or its rights changed. Create a new key and enter it under **Credentials**. |

## Limits

* Pike writes to Lucca only to send approved time to Timmi Timesheet, and only when **Send time to Timmi Timesheet** is on.
* Timmi Timesheet entries do not import into Pike. Members log their time in Pike.
* Pending, denied or canceled leave requests do not sync.
* Compensation does not sync. Set cost profiles in Pike.
* The API key syncs only the users and data its rights allow.

## Disconnect

Go to **Workspace settings → Integrations → Lucca** and click **Disconnect**. Syncing stops and every member, team, position, work schedule and time off entry stays in Pike with its history. Time already sent to Timmi Timesheet stays in Lucca. Reconnecting the same Lucca account relinks the members.

## Related

* [How sync works](https://usepike.com/docs/integrations/how-sync-works.md): The schedule, real-time sync and sync issues.
* [Time off](https://usepike.com/docs/members/time-off.md): Time off types and how they count toward capacity.
* [Pay periods and payroll](https://usepike.com/docs/members/payroll.md): Period close and approved time.
* [PayFit](https://usepike.com/docs/integrations/payfit.md): Collaborators, contracts and absences.
* [Factorial](https://usepike.com/docs/integrations/factorial.md): Employees, contracts, leaves and compensation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.