> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/lucca-hr/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

## Step-by-step deployment guide

### 1. Which data is imported from Lucca?

The integration with Lucca imports the following data per employee:

<table data-search="false"><thead><tr><th width="294.396484375">Attribute</th></tr></thead><tbody><tr><td>Login</td></tr><tr><td>Email</td></tr><tr><td>First Name</td></tr><tr><td>Last Name</td></tr><tr><td>Job Title</td></tr><tr><td>Employee Number</td></tr><tr><td>Department </td></tr><tr><td>Department Code</td></tr><tr><td>Legal Entity</td></tr><tr><td>Manager Id</td></tr><tr><td>Manager Name</td></tr><tr><td>Manager Email</td></tr><tr><td>Seniority Date</td></tr><tr><td>Contract Start Date</td></tr><tr><td>End Date</td></tr><tr><td>Last Modified</td></tr><tr><td>Status</td></tr><tr><td>Primary Role</td></tr><tr><td>Secondary Roles</td></tr><tr><td>Contract Type</td></tr></tbody></table>

The connector calls Lucca's user API (`GET /api/v3/users`) and pages through every user, requesting these fields via Lucca's `fields=` projection and department, manager and legal entity come back embedded on the same response.&#x20;

**Contract Type** is fetched from a second call to the work-contracts API (`GET /directory/api/4.0/work-contracts`) and matched to each user by their ID.&#x20;

**Status** is derived from the contract end date (a user is *inactive* if their contract ended in the past otherwise *active*). Former employees are also imported. To see only active or only former users, please filter on the status attribute in Elimity Insights. Sensitive data (bank details, social security number, health, home address, birth date) is intentionally not imported.

### 2. Request API access from Lucca

The connector authenticates against Lucca with an **API key**, sent on every request as the header `Authorization: lucca application=<api_key>`.

An administrator generates the key in Lucca. Please see Lucca's [Generating an API key](https://support.luccasoftware.com/s/article/generating-an-api-key) guide. Each key is given its own dedicated role that determines its access, the key needs **read** access to users, departments, legal entities and work-contracts.

In the end you should have the following configuration values:

* The Lucca **instance URL** (`host`) e.g. `https://your-instance.ilucca.net`
* An **API key** (`api_key`)

> **Tip:** before continuing please confirm the key works with a quick call:\
> `curl -H "Authorization: lucca application=<api_key>" "https://<host>/api/v3/users?paging=0,1"`\
> If it returns a user, the connector will authenticate too

> **Note:** Lucca rate-limits API requests to **50 per minute per domain**. The connector stays well under this and retries on `429` responses.

### 3. Configure the source in Elimity Insights

You can now register the connector in Elimity Insights:

1. Go to **Sources** in the left navigation bar and click **Add Source**.
2. Search for **Custom** and click **Set Up**.
3. Click **Set Up** again and give the source a name (e.g. `Lucca`).
4. Select **Upload export file**, click **Continue** and upload the data model file: `insights-client-lucca-data-model-export.json`&#x20;

{% file src="/files/GkS2qOfFL3HAmrOMR1LG" %}

5. Open the **Config** tab and click **Edit**.
6. Check the **Enable automatic imports via custom gateway** and fill in the Gateway URL: `https://lucca-gateway-1027270379075.europe-west1.run.app`
7. Click **Add configuration value** and add the two entries below.

<table><thead><tr><th width="367">Key</th><th>Type</th></tr></thead><tbody><tr><td>host</td><td><code>Text</code></td></tr><tr><td><code>api_key</code></td><td><code>Password</code></td></tr></tbody></table>

`host` and `api_key` are required. If either of `host` or `api_key` is missing or incorrect, the connector will fail to authenticate against Lucca and the import will not start.

8. Click **Save and run** to launch your first import. You can monitor the progress in the **Logs** tab, and the **Imports** tab will show the summary for each run.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/lucca-hr/step-by-step-deployment-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.