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

# Migrating to Lucca API (v5) Business-Establishments & Legal-Entities

> Migration steps from V3 legal-entities or V4 establishments to the Lucca API (v5) business-establishments and legal-entities.

<CardGroup cols={1}>
  <Card title="V3 Legal-Entities API" horizontal>
    The V3 legal-entities API is deprecated. The following routes will stop responding starting from **September 2026**:

    * `GET /api/v3/legalentities`
    * `GET /api/v3/legalentities/{id}`
  </Card>

  <Card title="V4 Establishments & Legal-Units APIs" horizontal>
    The V4 APIs have no announced sunset date, but the Lucca API (V5) is the long-term strategic target.

    If you are on V3 and want a lower-friction interim step (same API-key authentication), you may migrate to V4 first —
    but a future migration to the V5 Lucca API will still be required.

    * `GET /organization/structure/api/establishments`
    * `GET /organization/structure/api/legal-units`
  </Card>
</CardGroup>

<Note>
  The V5 Lucca API business-establishments and legal-entities endpoints are **stable** and will not undergo breaking changes.
  We recommend moving to the Lucca API as soon as possible to take advantage of its improved performance, richer data model,
  and long-term support.
</Note>

<Warning>
  **Naming change — read carefully.** What was called a **"legal-entity"** (or `legalentity`) in V3 is now called a
  **"business-establishment"** in V5 (and "establishment" in v4). The V5 Lucca API also has a resource called **"legal-entity"**, but it represents
  a *different* concept — the parent legal company structure. See the [concept mapping](#understanding-the-naming-change)
  section below for a detailed explanation.
</Warning>

***

## Understanding the Naming Change

In V3, the `legalentity` resource bundled two concerns into one: the legal company (SIREN in France) **and** the physical
office site (SIRET in France). V4 separated these into `legal-units` and `establishments`.

The V5 Lucca API continues this separation but **renames both resources**:

| V3                                 | V4              | V5 (Lucca API)                | Description                                                          |
| :--------------------------------- | :-------------- | :---------------------------- | :------------------------------------------------------------------- |
| `legalentity`                      | `establishment` | **`business-establishments`** | A physical site, office, or branch — identified by a SIRET in France |
| `legalentity.legalUnit` (embedded) | `legal-unit`    | **`legal-entity`**            | The legal company structure — identified by a SIREN in France        |

<Warning>
  If you are migrating from V3 `legalentities`, your target is **`/lucca-api/business-establishments`**, not
  `/lucca-api/legal-entities`. The V5 `legal-entity` is the equivalent of the V4 `legal-unit` — the parent company,
  not the establishment.
</Warning>

***

## Before You Start: Switch to OAuth 2.0

Regardless of your starting version, the Lucca API requires an **OAuth 2.0 bearer token** in place of the legacy API key.
Request the scope that matches your use case:

| Operation                    | Required scope                     |
| :--------------------------- | :--------------------------------- |
| Read business-establishments | `business-establishments.readonly` |
| Read legal-entities          | `legal-entities.readonly`          |

Additionally, all requests must include the `Api-Version: 2024-11-01` HTTP header.

<Tip>
  A single OAuth 2.0 token can carry multiple scopes. Combine all the scopes you need in one token request —
  for example: `scope=business-establishments.readonly legal-entities.readonly`.
</Tip>

<CardGroup cols={1}>
  <Card title="Authentication" icon="key" cta="Read more" href="/documentation/using-api/authentication" horizontal>
    How to obtain and use OAuth 2.0 bearer tokens with the Lucca authorization server.
  </Card>

  <Card title="Versioning" icon="code-branch" cta="Read more" href="/documentation/using-api/versioning" horizontal>
    How to use the `Api-Version` header to specify the API version.
  </Card>
</CardGroup>

***

## Pick Your Starting Version

<Tabs>
  <Tab title="Migrating from V3 Legal-Entities">
    ### Quick Start

    <Steps titleSize="p">
      <Step title="Get an OAuth 2.0 token">
        Request a bearer token with the `business-establishments.readonly` scope (add `legal-entities.readonly` if you also need the parent legal company). See the auth section above.
      </Step>

      <Step title="Add the Api-Version header">
        Include `Api-Version: 2024-11-01` on every request.
      </Step>

      <Step title="Replace the list endpoint">
        Swap `GET /api/v3/legalentities?paging=0,1000` for `GET /lucca-api/business-establishments?include=links,embedded`. Page through results using the cursor token in `links.next`.
      </Step>

      <Step title="Update your data model">
        Refer to the [field mapping reference](#field-mapping-reference) below for all changes. Remember that V3 `legalentity` maps to V5 `business-establishment`.
      </Step>

      <Step title="Retrieve the parent legal company separately">
        V3 embedded the `legalUnit` inside the `legalentity` object. In V5, use the `legalEntity` reference on business-establishments and either request `?include=embedded` to inline the legal-entity, or call `GET /lucca-api/legal-entities/{id}` directly.
      </Step>

      <Step title="Replace embedded user lists">
        The `users`, `currentUsers`, and `roles` fields no longer appear on business-establishment objects.
        Use `GET /lucca-api/employees?applicableJobPosition.businessEstablishment.id={id}&status=active&include=totalCount` instead.
      </Step>
    </Steps>

    ***

    ### What Changes

    * **Resource renamed**: V3 `legalentity` → V5 **`business-establishment`**. The V5 `legal-entity` is a *different* resource (the parent company).
    * **Authentication**: V3 uses a proprietary API key; the Lucca API uses **OAuth 2.0 bearer tokens**.
    * **Versioning**: requests must include the `Api-Version: 2024-11-01` HTTP header.
    * **`code` → `remoteId`**: renamed for consistency.
    * **`isActive` → `isArchived`**: the boolean is **semantically inverted**.
    * **`legalIdentificationNumber` → `taxIdentificationNumber`**: now a structured `{ format, value }` object instead of a plain string.
    * **`activityCode` → `industryCode`**: now a structured `{ format, value }` object.
    * **`countryID` / `country` moved**: country information is now on the parent `legal-entity`, not on the business-establishment.
    * **IDs become strings**: integers in V3 (`1`), strings in V5 (`"1"`).
    * **No embedded `users`/`currentUsers`/`roles`**: query the employees endpoint instead.
    * **Pagination**: V3 used `?paging={offset},{limit}`; the Lucca API uses cursor tokens. Max **100 items per page** (default 25).
    * **`address` restructured**: V3 had `street`/`zipCode`/`city`; V5 uses `addressLines`/`postalCode`/`locality`/`administrativeArea`/`countryCode`.
    * **New fields**: `isHeadquarters`, `lastArchivedAt`, `lastUpdatedAt`, `links`.

    <CardGroup cols={1}>
      <Card title="Pagination" icon="forward" cta="Read more" href="/documentation/using-api/paging" horizontal>
        How cursor-based pagination works in the Lucca API.
      </Card>
    </CardGroup>

    ***

    ### Notable Breaking Changes

    <Warning>
      Pay close attention to these changes — some may cause silent data errors if overlooked.
    </Warning>

    #### Resource name changed from `legalentity` to `business-establishment`

    This is the most critical change. The V3 "legal entity" is **not** the V5 "legal entity" — it maps to the V5 **business-establishment**. Update all endpoint URLs accordingly:

    | V3                               | V5                                            |
    | :------------------------------- | :-------------------------------------------- |
    | `GET /api/v3/legalentities`      | `GET /lucca-api/business-establishments`      |
    | `GET /api/v3/legalentities/{id}` | `GET /lucca-api/business-establishments/{id}` |

    #### `isActive` is now `isArchived` (inverted semantics)

    | V3                | V5                  | Meaning                           |
    | :---------------- | :------------------ | :-------------------------------- |
    | `isActive: true`  | `isArchived: false` | Establishment is in use           |
    | `isActive: false` | `isArchived: true`  | Establishment is no longer in use |

    #### IDs became strings in V5

    ```json theme={null}
    // V3: integer
    { "id": 1 }

    // V5: string
    { "id": "1" }
    ```

    The numeric value is preserved. Update any code that stores or compares IDs to treat them as strings.

    #### `legalIdentificationNumber` became `taxIdentificationNumber` — a structured object

    In V3, `legalIdentificationNumber` was a plain string (e.g. the French SIRET code). In V5, it is a structured object with a format discriminator:

    ```json theme={null}
    // V3 response
    { "legalIdentificationNumber": "44163769100012" }

    // V5 response
    {
      "taxIdentificationNumber": {
        "format": "franceSIRET",
        "value": "44163769100012"
      }
    }
    ```

    The `format` field can be `"franceSIRET"`, `"spainNIF"`, or `"other"`.

    #### `activityCode` became `industryCode` — a structured object

    Same pattern as above:

    ```json theme={null}
    // V3 response (embedded from country)
    { "activityCode": "7022Z" }

    // V5 response
    {
      "industryCode": {
        "format": "franceAPE",
        "value": "7022Z"
      }
    }
    ```

    The `format` field can be `"franceAPE"`, `"spainCNAE"`, `"germanyWZ"`, `"usaNAICS"`, or `"other"`.

    #### `code` renamed `remoteId`

    Map V3 `code` to V5 `remoteId`. Use it for external identifiers.

    #### `address` restructured

    ```json theme={null}
    // V3 response
    {
      "address": {
        "street": "10 Place de la Joliette",
        "zipCode": "13002",
        "city": "Marseille"
      }
    }

    // V5 response
    {
      "address": {
        "addressLines": ["Lucca", "10 Place de la Joliette", "Les Docks Atrium 10.2"],
        "postalCode": "13002",
        "locality": "Marseille",
        "administrativeArea": "Bouches-du-Rhône",
        "countryCode": "FRA"
      }
    }
    ```

    * `street` → `addressLines` (array, supports multiple lines)
    * `zipCode` → `postalCode`
    * `city` → `locality`
    * `administrativeArea` and `countryCode` are new fields

    #### Country and currency information moved to the parent `legal-entity`

    V3 had `countryID`, `country`, and currency details on the legal entity (now business-establishment). In V5, this information lives on the parent `legal-entity` resource. Use the business-establishment's `legalEntity` reference to retrieve it:

    ```http theme={null}
    GET /lucca-api/legal-entities/{legalEntityId} HTTP/1.1
    ```

    Or include `?include=embedded` on the business-establishment request to get the legal-entity inlined.

    #### Embedded `users`, `currentUsers`, and `roles` fields were removed

    V3 legal-entity objects included full user and role lists. These are no longer available on business-establishment objects. Query the employees endpoint instead.

    ***

    ### Migration by Use Case

    #### 1. List All Establishments

    <CodeGroup>
      ```http V3 theme={null}
      GET /api/v3/legalentities?paging=0,1000 HTTP/1.1
      Host: example.ilucca.net
      Authorization: lucca application={API_KEY}
      Accept: application/json

      {
        "header": { ... },
        "data": {
          "items": [
            {
              "id": 1,
              "code": "00128",
              "name": "Lucca Paris",
              "countryID": 1,
              "country": {
                "id": 1,
                "name": "France"
              },
              "legalIdentificationNumber": "44163769100012",
              "activityCode": "7022Z",
              "isActive": true,
              "legalUnitId": 3,
              "legalUnit": {
                "id": 3,
                "name": "Lucca SAS",
                "code": "LUCCA_FR"
              },
              "timeZoneId": "Europe/Paris",
              "users": [ ... ],
              "currentUsers": [ ... ]
            }
          ]
        }
      }
      ```

      ```http V5 theme={null}
      GET /lucca-api/business-establishments?include=links,embedded&limit=25 HTTP/1.1
      Host: example.ilucca.net
      Authorization: Bearer {ACCESS_TOKEN}
      Api-Version: 2024-11-01
      Accept: application/json

      {
        "type": "business-establishments",
        "url": "https://example.ilucca.net/lucca-api/business-establishments?limit=25",
        "totalCount": 28,
        "items": [
          {
            "id": "5",
            "type": "business-establishment",
            "url": "https://example.ilucca.net/lucca-api/business-establishments/5",
            "name": "Lucca Marseille",
            "remoteId": "00004",
            "legalEntity": {
              "id": "123",
              "type": "legal-entity",
              "url": "https://example.ilucca.net/lucca-api/legal-entities/123"
            },
            "isHeadquarters": false,
            "taxIdentificationNumber": {
              "format": "franceSIRET",
              "value": "0000000000000"
            },
            "industryCode": null,
            "address": {
              "addressLines": ["Lucca", "10 Place de la Joliette", "Les Docks Atrium 10.2"],
              "postalCode": "13002",
              "locality": "Marseille",
              "administrativeArea": "Bouches-du-Rhône",
              "countryCode": "FRA"
            },
            "timezoneId": "Europe/Paris",
            "isArchived": false,
            "lastArchivedAt": null,
            "createdAt": "2024-05-23T13:45:26.0001Z",
            "lastUpdatedAt": "2024-05-23T13:45:26.0001Z",
            "links": {}
          }
        ],
        "links": {
          "prev": null,
          "next": { "href": "https://example.ilucca.net/lucca-api/business-establishments?page=!sdk87Sdh&limit=25" }
        },
        "embedded": {
          "legal-entity": {
            "123": {
              "id": "123",
              "type": "legal-entity",
              "url": "https://example.ilucca.net/lucca-api/legal-entities/123",
              "legalName": "Lucca S.A.S.",
              "remoteId": "LE:83.2938",
              "countryCode": "FRA",
              "currencyCode": "EUR",
              "taxIdentificationNumber": {
                "format": "franceSIREN",
                "value": "44163769100128"
              },
              "industryCode": {
                "format": "franceAPE",
                "value": "7022Z"
              },
              "createdAt": "2024-01-01T08:34:23.0001Z",
              "lastUpdatedAt": "2024-01-01T08:34:23.0001Z",
              "lastArchivedAt": null,
              "links": {
                "businessEstablishments": {
                  "href": "https://example.ilucca.net/lucca-api/business-establishments?legalEntity.id=123"
                }
              }
            }
          }
        }
      }
      ```
    </CodeGroup>

    <Tip>Add `?include=embedded` to inline the parent legal-entities. This avoids extra requests when you need the country or legal identifiers that were previously on the V3 legal entity.</Tip>

    #### 2. Retrieve an Establishment by ID

    <CodeGroup>
      ```http V3 theme={null}
      GET /api/v3/legalentities/1 HTTP/1.1
      Host: example.ilucca.net
      Authorization: lucca application={API_KEY}
      Accept: application/json

      {
        "header": { ... },
        "data": {
          "id": 1,
          "code": "00128",
          "name": "Lucca Paris",
          "countryID": 1,
          "country": { "id": 1, "name": "France" },
          "legalIdentificationNumber": "44163769100012",
          "isActive": true,
          "legalUnitId": 3,
          "legalUnit": { "id": 3, "name": "Lucca SAS" },
          "timeZoneId": "Europe/Paris",
          "users": [ ... ],
          "currentUsers": [ ... ]
        }
      }
      ```

      ```http V5 theme={null}
      GET /lucca-api/business-establishments/1?include=embedded HTTP/1.1
      Host: example.ilucca.net
      Authorization: Bearer {ACCESS_TOKEN}
      Api-Version: 2024-11-01
      Accept: application/json

      {
        "id": "1",
        "type": "business-establishment",
        "url": "https://example.ilucca.net/lucca-api/business-establishments/1",
        "name": "Lucca Paris",
        "remoteId": "00128",
        "legalEntity": {
          "id": "3",
          "type": "legal-entity",
          "url": "https://example.ilucca.net/lucca-api/legal-entities/3"
        },
        "isHeadquarters": true,
        "taxIdentificationNumber": {
          "format": "franceSIRET",
          "value": "44163769100012"
        },
        "industryCode": null,
        "address": {
          "addressLines": ["Lucca", "2 Rue Pillet-Will"],
          "postalCode": "75009",
          "locality": "Paris",
          "administrativeArea": "Île-de-France",
          "countryCode": "FRA"
        },
        "timezoneId": "Europe/Paris",
        "isArchived": false,
        "lastArchivedAt": null,
        "createdAt": "2020-01-01T00:00:00.0001Z",
        "lastUpdatedAt": "2025-03-12T09:19:19.0001Z",
        "links": {},
        "embedded": {
          "legal-entity": {
            "3": {
              "id": "3",
              "type": "legal-entity",
              "url": "https://example.ilucca.net/lucca-api/legal-entities/3",
              "legalName": "Lucca SAS",
              "countryCode": "FRA",
              "currencyCode": "EUR"
            }
          }
        }
      }
      ```
    </CodeGroup>

    #### 3. Filter by Active / Archived Status

    | Intent        | V3                                                 | V5                                |
    | :------------ | :------------------------------------------------- | :-------------------------------- |
    | Active only   | `isActive: true` on response (filter client-side)  | `?isArchived=false`               |
    | Inactive only | `isActive: false` on response (filter client-side) | `?isArchived=true`                |
    | All           | All returned by default                            | Same behavior (omit `isArchived`) |

    #### 4. Get the Parent Legal Company

    V3 embedded `legalUnit` directly on the legal-entity object. In V5, the parent legal company is a separate resource:

    ```http theme={null}
    GET /lucca-api/legal-entities/3 HTTP/1.1
    Host: example.ilucca.net
    Authorization: Bearer {ACCESS_TOKEN}
    Api-Version: 2024-11-01

    {
      "id": "3",
      "type": "legal-entity",
      "url": "https://example.ilucca.net/lucca-api/legal-entities/3",
      "legalName": "Lucca S.A.S.",
      "remoteId": "LE:83.2938",
      "isArchived": false,
      "countryCode": "FRA",
      "currencyCode": "EUR",
      "taxIdentificationNumber": {
        "format": "franceSIREN",
        "value": "44163769100128"
      },
      "industryCode": {
        "format": "franceAPE",
        "value": "7022Z"
      },
      "createdAt": "2024-01-01T08:34:23.0001Z",
      "lastUpdatedAt": "2024-01-01T08:34:23.0001Z",
      "lastArchivedAt": null,
      "links": {
        "businessEstablishments": {
          "href": "https://example.ilucca.net/lucca-api/business-establishments?legalEntity.id=3"
        }
      }
    }
    ```

    <Tip>You can also use `?include=embedded` on the business-establishment request to get the parent legal-entity inlined in the `embedded` section — this avoids extra round-trips.</Tip>

    #### 5. Find Employees in an Establishment

    V3 embedded `users` and `currentUsers` directly on the legal-entity object. In V5, query the employees endpoint:

    ```http theme={null}
    GET /lucca-api/employees?applicableJobPosition.businessEstablishment.id=1&status=active&include=totalCount HTTP/1.1
    Host: example.ilucca.net
    Authorization: Bearer {ACCESS_TOKEN}
    Api-Version: 2024-11-01
    ```

    <Tip>You need the `employees.readonly` and `job-positions.readonly` scopes to query the employees endpoint.</Tip>

    ***

    ### Field Mapping Reference

    | V3 legalentity field                         | V5 business-establishment field | Notes                                                                                            |
    | :------------------------------------------- | :------------------------------ | :----------------------------------------------------------------------------------------------- |
    | `id`                                         | `id`                            | String in V5 (integer in V3)                                                                     |
    | *(new in V5)*                                | `type`                          | Always `"business-establishment"`                                                                |
    | `url`                                        | `url`                           | Self-link URI                                                                                    |
    | `name`                                       | `name`                          |                                                                                                  |
    | `code`                                       | `remoteId`                      | Renamed                                                                                          |
    | `countryID`                                  | *(moved)*                       | Now on the parent legal-entity as `countryCode` (ISO 3166 alpha-3)                               |
    | `country`                                    | *(moved)*                       | Now on the parent legal-entity                                                                   |
    | `newCountryId`                               | *(removed)*                     | Use the parent legal-entity's `countryCode`                                                      |
    | `newCountry`                                 | *(removed)*                     | Use the parent legal-entity                                                                      |
    | `legalUnitId`                                | `legalEntity.id`                | Now a typed `{ id, type, url }` reference                                                        |
    | `legalUnit`                                  | *(embedded)*                    | Use `?include=embedded` or query `/lucca-api/legal-entities/{id}`                                |
    | `legalIdentificationNumber`                  | `taxIdentificationNumber`       | Now `{ format, value }` — format: `"franceSIRET"`, `"spainNIF"`, or `"other"`                    |
    | *(from country)* `activityCode`              | `industryCode`                  | Now `{ format, value }` on the business-establishment; also available on the parent legal-entity |
    | `isActive`                                   | `isArchived`                    | Semantics **inverted**                                                                           |
    | `timeZoneId`                                 | `timezoneId`                    | Casing changed                                                                                   |
    | `address.street`                             | `address.addressLines`          | Array of strings instead of single string                                                        |
    | `address.zipCode`                            | `address.postalCode`            | Renamed                                                                                          |
    | `address.city`                               | `address.locality`              | Renamed                                                                                          |
    | *(new in V5)*                                | `address.administrativeArea`    | Region / state                                                                                   |
    | *(new in V5)*                                | `address.countryCode`           | ISO 3166 alpha-3 country code                                                                    |
    | *(new in V5)*                                | `isHeadquarters`                | Whether this is the headquarters of its legal-entity                                             |
    | `modifiedOn`                                 | `lastUpdatedAt`                 | Renamed                                                                                          |
    | *(new in V5)*                                | `createdAt`                     |                                                                                                  |
    | *(new in V5)*                                | `lastArchivedAt`                |                                                                                                  |
    | `users`                                      | *(removed)*                     | Query the employees endpoint                                                                     |
    | `currentUsers`                               | *(removed)*                     | Query the employees endpoint with `status=active`                                                |
    | `roles`                                      | *(removed)*                     | Not available in V5                                                                              |
    | `modifiedByID` / `modifiedBy`                | *(removed)*                     | Not available in V5                                                                              |
    | `authorizedOperations` / `authorizedActions` | *(removed)*                     | Not available in V5                                                                              |
  </Tab>

  <Tab title="Migrating from V4 Establishments">
    ### Quick Start

    <Steps titleSize="p">
      <Step title="Get an OAuth 2.0 token">
        Request a bearer token with the `business-establishments.readonly` scope (add `legal-entities.readonly` if needed). See the auth section above.
      </Step>

      <Step title="Add the Api-Version header">
        Include `Api-Version: 2024-11-01` on every request.
      </Step>

      <Step title="Replace the list endpoint">
        Swap `GET /organization/structure/api/establishments?limit=10` for `GET /lucca-api/business-establishments?include=links`. The response envelope changes: `next` moves from a bare string to `links.next.href`.
      </Step>

      <Step title="Update your data model">
        Refer to the [field mapping reference](#field-mapping-reference-2) below for all changes.
      </Step>
    </Steps>

    ***

    ### What Changes

    * **Resource renamed**: V4 `establishment` → V5 **`business-establishment`**.
    * **Authentication**: V4 uses a proprietary API key; the Lucca API uses **OAuth 2.0 bearer tokens**.
    * **Versioning**: requests must include the `Api-Version: 2024-11-01` HTTP header.
    * **Endpoint path**: `GET /organization/structure/api/establishments` → `GET /lucca-api/business-establishments`.
    * **Response envelope**: `{ items, count, prev, next }` → `{ type, url, items, totalCount, links: { prev, next } }`.
    * **`code` → `remoteId`**: renamed for consistency.
    * **`legalUnitId` → `legalEntity`**: integer ID replaced by a typed `{ id, type, url }` reference.
    * **`legalIdentificationNumber` → `taxIdentificationNumber`**: now a structured `{ format, value }` object.
    * **`activityCode` → `industryCode`**: now a structured `{ format, value }` object.
    * **`address` restructured**: `street`/`zipCode`/`city` → `addressLines`/`postalCode`/`locality`/`administrativeArea`/`countryCode`.
    * **IDs are strings**: integers in V4 (`5`), strings in V5 (`"5"`).
    * **`usersCount` removed**: query the employees endpoint with `?include=totalCount`.
    * **`calendarId` removed**: not available in V5.
    * **`author` / `createdAt` changes**: `author` removed; `createdAt` and `lastUpdatedAt` available.
    * **New fields**: `isHeadquarters`, `lastArchivedAt`, `links`.

    <CardGroup cols={1}>
      <Card title="Pagination" icon="forward" cta="Read more" href="/documentation/using-api/paging" horizontal>
        How cursor-based pagination works in the Lucca API.
      </Card>
    </CardGroup>

    ***

    ### Notable Breaking Changes

    <Warning>
      Pay close attention to these changes — some may cause silent data errors if overlooked.
    </Warning>

    #### Resource renamed from `establishment` to `business-establishment`

    | V4                                                    | V5                                            |
    | :---------------------------------------------------- | :-------------------------------------------- |
    | `GET /organization/structure/api/establishments`      | `GET /lucca-api/business-establishments`      |
    | `GET /organization/structure/api/establishments/{id}` | `GET /lucca-api/business-establishments/{id}` |

    #### IDs became strings in V5

    ```json theme={null}
    // V4: integer
    { "id": 5 }

    // V5: string
    { "id": "5" }
    ```

    The numeric value is preserved. Update any code that stores or compares IDs to treat them as strings.

    #### `legalUnitId` replaced with `legalEntity` — a typed reference

    V4 exposed the parent legal-unit's numeric ID as `legalUnitId`. In V5, this is a typed reference:

    ```json theme={null}
    // V4 response
    { "legalUnitId": 3 }

    // V5 response
    {
      "legalEntity": {
        "id": "3",
        "type": "legal-entity",
        "url": "https://example.ilucca.net/lucca-api/legal-entities/3"
      }
    }
    ```

    Note: V4 `legal-unit` is now V5 `legal-entity`.

    #### `legalIdentificationNumber` became `taxIdentificationNumber` — a structured object

    ```json theme={null}
    // V4 response
    { "legalIdentificationNumber": "44163769100012" }

    // V5 response
    {
      "taxIdentificationNumber": {
        "format": "franceSIRET",
        "value": "44163769100012"
      }
    }
    ```

    The `format` field can be `"franceSIRET"`, `"spainNIF"`, or `"other"`.

    #### `activityCode` became `industryCode` — a structured object

    ```json theme={null}
    // V4 response
    { "activityCode": "7022Z" }

    // V5 response
    {
      "industryCode": {
        "format": "franceAPE",
        "value": "7022Z"
      }
    }
    ```

    #### `code` renamed `remoteId`

    Use `remoteId` for external identifiers.

    #### `address` restructured

    * `address.street` → `address.addressLines` (array)
    * `address.zipCode` → `address.postalCode`
    * `address.city` → `address.locality`
    * New fields: `address.administrativeArea`, `address.countryCode`

    #### Response envelope changed

    ```json theme={null}
    // V4
    {
      "items": [ ... ],
      "count": 28,
      "prev": null,
      "next": "!cursorToken"
    }

    // V5
    {
      "type": "business-establishments",
      "url": "https://example.ilucca.net/lucca-api/business-establishments?limit=25",
      "items": [ ... ],
      "totalCount": 28,
      "links": {
        "prev": null,
        "next": { "href": "https://example.ilucca.net/lucca-api/business-establishments?page=!sdk87Sdh&limit=25" }
      }
    }
    ```

    In V5, `prev` and `next` are nested under a `links` object and are `{ href }` objects rather than bare strings.
    `count` is renamed `totalCount` and only returned when you add `totalCount` to the `?include=` parameter.

    ***

    ### Migration by Use Case

    #### 1. List All Establishments

    <CodeGroup>
      ```http V4 theme={null}
      GET /organization/structure/api/establishments?limit=10 HTTP/1.1
      Host: example.ilucca.net
      Authorization: lucca application={API_KEY}
      Accept: application/json

      {
        "items": [
          {
            "id": 5,
            "name": "Lucca Marseille",
            "code": "00004",
            "legalUnitId": 123,
            "legalIdentificationNumber": "0000000000000",
            "activityCode": "7022Z",
            "calendarId": 1,
            "address": {
              "street": "10 Place de la Joliette",
              "zipCode": "13002",
              "city": "Marseille"
            },
            "timezoneId": "Europe/Paris",
            "usersCount": 42,
            "createdAt": "2024-05-23T13:45:26+00:00",
            "isArchived": false
          }
        ],
        "count": 28,
        "prev": null,
        "next": "!nextCursorToken"
      }
      ```

      ```http V5 theme={null}
      GET /lucca-api/business-establishments?include=links&limit=25 HTTP/1.1
      Host: example.ilucca.net
      Authorization: Bearer {ACCESS_TOKEN}
      Api-Version: 2024-11-01
      Accept: application/json

      {
        "type": "business-establishments",
        "url": "https://example.ilucca.net/lucca-api/business-establishments?limit=25",
        "totalCount": 28,
        "items": [
          {
            "id": "5",
            "type": "business-establishment",
            "url": "https://example.ilucca.net/lucca-api/business-establishments/5",
            "name": "Lucca Marseille",
            "remoteId": "00004",
            "legalEntity": {
              "id": "123",
              "type": "legal-entity",
              "url": "https://example.ilucca.net/lucca-api/legal-entities/123"
            },
            "isHeadquarters": false,
            "taxIdentificationNumber": {
              "format": "franceSIRET",
              "value": "0000000000000"
            },
            "industryCode": null,
            "address": {
              "addressLines": ["Lucca", "10 Place de la Joliette", "Les Docks Atrium 10.2"],
              "postalCode": "13002",
              "locality": "Marseille",
              "administrativeArea": "Bouches-du-Rhône",
              "countryCode": "FRA"
            },
            "timezoneId": "Europe/Paris",
            "isArchived": false,
            "lastArchivedAt": null,
            "createdAt": "2024-05-23T13:45:26.0001Z",
            "lastUpdatedAt": "2024-05-23T13:45:26.0001Z",
            "links": {}
          }
        ],
        "links": {
          "prev": null,
          "next": { "href": "https://example.ilucca.net/lucca-api/business-establishments?page=!sdk87Sdh&limit=25" }
        }
      }
      ```
    </CodeGroup>

    To paginate in V5, follow the full URL in `links.next.href`. Add `totalCount` to the `include` parameter to also receive the total count: `?include=links,totalCount`.

    #### 2. Retrieve an Establishment by ID

    <CodeGroup>
      ```http V4 theme={null}
      GET /organization/structure/api/establishments/5 HTTP/1.1
      Host: example.ilucca.net
      Authorization: lucca application={API_KEY}
      Accept: application/json

      {
        "id": 5,
        "name": "Lucca Marseille",
        "code": "00004",
        "legalUnitId": 123,
        "legalIdentificationNumber": "0000000000000",
        "activityCode": "7022Z",
        "calendarId": 1,
        "address": {
          "street": "10 Place de la Joliette",
          "zipCode": "13002",
          "city": "Marseille"
        },
        "timezoneId": "Europe/Paris",
        "usersCount": 42,
        "createdAt": "2024-05-23T13:45:26+00:00",
        "isArchived": false
      }
      ```

      ```http V5 theme={null}
      GET /lucca-api/business-establishments/5 HTTP/1.1
      Host: example.ilucca.net
      Authorization: Bearer {ACCESS_TOKEN}
      Api-Version: 2024-11-01
      Accept: application/json

      {
        "id": "5",
        "type": "business-establishment",
        "url": "https://example.ilucca.net/lucca-api/business-establishments/5",
        "name": "Lucca Marseille",
        "remoteId": "00004",
        "legalEntity": {
          "id": "123",
          "type": "legal-entity",
          "url": "https://example.ilucca.net/lucca-api/legal-entities/123"
        },
        "isHeadquarters": false,
        "taxIdentificationNumber": {
          "format": "franceSIRET",
          "value": "0000000000000"
        },
        "industryCode": null,
        "address": {
          "addressLines": ["Lucca", "10 Place de la Joliette", "Les Docks Atrium 10.2"],
          "postalCode": "13002",
          "locality": "Marseille",
          "administrativeArea": "Bouches-du-Rhône",
          "countryCode": "FRA"
        },
        "timezoneId": "Europe/Paris",
        "isArchived": false,
        "lastArchivedAt": null,
        "createdAt": "2024-05-23T13:45:26.0001Z",
        "lastUpdatedAt": "2024-05-23T13:45:26.0001Z",
        "links": {}
      }
      ```
    </CodeGroup>

    #### 3. Filter by Active / Archived Status

    | Intent        | V4                       | V5                                |
    | :------------ | :----------------------- | :-------------------------------- |
    | Active only   | `?isArchived=false`      | `?isArchived=false`               |
    | Inactive only | `?isArchived=true`       | `?isArchived=true`                |
    | All           | `?isArchived=true,false` | Same behavior (omit `isArchived`) |

    #### 4. Filter by Legal-Entity (formerly Legal-Unit)

    | V4               | V5                  |
    | :--------------- | :------------------ |
    | `?legalUnitId=3` | `?legalEntity.id=3` |

    #### 5. Get the Parent Legal Company

    V4 had an embedded `legalUnit` object or a `legalUnitId` integer. In V5, use the `legalEntity` reference on business-establishments:

    ```http theme={null}
    GET /lucca-api/legal-entities/123 HTTP/1.1
    Host: example.ilucca.net
    Authorization: Bearer {ACCESS_TOKEN}
    Api-Version: 2024-11-01
    ```

    Or include `?include=embedded` to get the legal-entity inlined in the response.

    #### 6. Get the Employee Count

    V4 provided `usersCount` directly on the establishment. In V5, query the employees endpoint:

    ```http theme={null}
    GET /lucca-api/employees?applicableJobPosition.businessEstablishment.id=5&status=active&include=totalCount HTTP/1.1
    Host: example.ilucca.net
    Authorization: Bearer {ACCESS_TOKEN}
    Api-Version: 2024-11-01
    ```

    The `totalCount` field in the response is the equivalent of the old `usersCount`.

    <Tip>You need the `employees.readonly` and `job-positions.readonly` scopes to query the employees endpoint, even if you only want the count.</Tip>

    ***

    ### Field Mapping Reference

    | V4 establishment field      | V5 business-establishment field   | Notes                                                           |
    | :-------------------------- | :-------------------------------- | :-------------------------------------------------------------- |
    | `id`                        | `id`                              | String in V5 (integer in V4)                                    |
    | *(new in V5)*               | `type`                            | Always `"business-establishment"`                               |
    | *(new in V5)*               | `url`                             | Self-link URI                                                   |
    | `name`                      | `name`                            |                                                                 |
    | `code`                      | `remoteId`                        | Renamed                                                         |
    | `legalUnitId`               | `legalEntity`                     | Now a `{ id, type, url }` reference                             |
    | `legalUnit` *(embedded)*    | *(use embedded or separate call)* | Use `?include=embedded` or `GET /lucca-api/legal-entities/{id}` |
    | `legalIdentificationNumber` | `taxIdentificationNumber`         | Now `{ format, value }`                                         |
    | `activityCode`              | `industryCode`                    | Now `{ format, value }`                                         |
    | `address.street`            | `address.addressLines`            | Array of strings                                                |
    | `address.zipCode`           | `address.postalCode`              | Renamed                                                         |
    | `address.city`              | `address.locality`                | Renamed                                                         |
    | *(new in V5)*               | `address.administrativeArea`      | Region / state                                                  |
    | *(new in V5)*               | `address.countryCode`             | ISO 3166 alpha-3                                                |
    | `timezoneId`                | `timezoneId`                      |                                                                 |
    | `isArchived`                | `isArchived`                      | Same semantics                                                  |
    | *(new in V5)*               | `isHeadquarters`                  | Whether this is the legal-entity's headquarters                 |
    | `usersCount`                | *(removed)*                       | Query the employees endpoint with `?include=totalCount`         |
    | `calendarId`                | *(removed)*                       | Not available in V5                                             |
    | `createdAt`                 | `createdAt`                       |                                                                 |
    | *(new in V5)*               | `lastUpdatedAt`                   |                                                                 |
    | *(new in V5)*               | `lastArchivedAt`                  |                                                                 |
    | `author`                    | *(removed)*                       | Not available in V5                                             |
  </Tab>
</Tabs>

***

## Migrating V4 Legal-Units to V5 Legal-Entities

If you were using V4 `legal-units`, the migration to V5 `legal-entities` is also needed.

| V4                                            | V5                              |
| :-------------------------------------------- | :------------------------------ |
| `GET /organization/structure/api/legal-units` | `GET /lucca-api/legal-entities` |

### What Changes

* **Resource renamed**: V4 `legal-unit` → V5 **`legal-entity`**.
* **`name` → `legalName`**: the field is renamed to clarify it is the legal name of the entity.
* **`code` → `remoteId`**: renamed for consistency.
* **`countryId` (ISO alpha-2) → `countryCode` (ISO alpha-3)**: changed from `"FR"` to `"FRA"`.
* **`legalIdentificationNumber` → `taxIdentificationNumber`**: now a structured `{ format, value }` object.
* **`activityCode` → `industryCode`**: now a structured `{ format, value }` object.
* **`headquartersId` removed**: the headquarters information is now on the business-establishment side (`isHeadquarters: true`).
* **`country` object removed**: replaced by `countryCode` and `currencyCode` top-level fields.
* **IDs are strings**: integers in V4 (`3`), strings in V5 (`"3"`).
* **New fields**: `currencyCode`, `links.businessEstablishments`, `lastArchivedAt`, `lastUpdatedAt`.

### Field Mapping Reference

| V4 legal-unit field         | V5 legal-entity field          | Notes                                                                                        |
| :-------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------- |
| `id`                        | `id`                           | String in V5 (integer in V4)                                                                 |
| *(new in V5)*               | `type`                         | Always `"legal-entity"`                                                                      |
| *(new in V5)*               | `url`                          | Self-link URI                                                                                |
| `name`                      | `legalName`                    | Renamed                                                                                      |
| `code`                      | `remoteId`                     | Renamed                                                                                      |
| `countryId` (alpha-2)       | `countryCode` (alpha-3)        | Changed from `"FR"` to `"FRA"`                                                               |
| `country` *(object)*        | *(removed)*                    | Replaced by `countryCode` and `currencyCode`                                                 |
| *(from country)*            | `currencyCode`                 | Top-level field in V5 (e.g. `"EUR"`)                                                         |
| `legalIdentificationNumber` | `taxIdentificationNumber`      | Now `{ format, value }` — format: `"franceSIREN"`, `"spainNIF"`, `"germanySN"`, or `"other"` |
| `activityCode`              | `industryCode`                 | Now `{ format, value }`                                                                      |
| `headquartersId`            | *(removed)*                    | Check `isHeadquarters` on business-establishments instead                                    |
| `isArchived`                | `isArchived`                   | Same semantics                                                                               |
| `createdAt`                 | `createdAt`                    |                                                                                              |
| *(new in V5)*               | `lastUpdatedAt`                |                                                                                              |
| *(new in V5)*               | `lastArchivedAt`               |                                                                                              |
| *(new in V5)*               | `links.businessEstablishments` | Pre-built link to business-establishments belonging to this entity                           |

***

## Further Reading

<CardGroup cols={2}>
  <Card title="Lucca API Introduction" icon="book-open" cta="Read more" href="/api-reference/latest/introduction">
    Overview of the Lucca API, versioning, and pagination.
  </Card>

  <Card title="V5 Business-Establishment Reference" icon="building" cta="Read more" href="/api-reference/latest/organization/business-establishment">
    Full reference for the Lucca API business-establishment resource.
  </Card>

  <Card title="V5 Legal-Entity Reference" icon="scale-balanced" cta="Read more" href="/api-reference/latest/organization/legal-entity">
    Full reference for the Lucca API legal-entity resource.
  </Card>

  <Card title="Authentication" icon="key" cta="Read more" href="/documentation/using-api/authentication">
    How to obtain and use OAuth 2.0 bearer tokens.
  </Card>

  <Card title="Pagination" icon="forward" cta="Read more" href="/documentation/using-api/paging">
    Cursor-based pagination in the Lucca API, with examples.
  </Card>

  <Card title="Rate Limits" icon="monitor-waveform" cta="Read more" href="/documentation/limits">
    Rate and size limits applied to the Lucca API.
  </Card>
</CardGroup>