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

V3 Legal-Entities API

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}

V4 Establishments & Legal-Units APIs

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

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.

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 section below for a detailed explanation.

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

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.

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.

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.

Authentication

How to obtain and use OAuth 2.0 bearer tokens with the Lucca authorization server.

Versioning

How to use the Api-Version header to specify the API version.

Pick Your Starting Version

Migrating from V3 Legal-Entities
Migrating from V4 Establishments

Quick Start

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.

Add the Api-Version header

Include Api-Version: 2024-11-01 on every request.

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.

Update your data model

Refer to the field mapping reference below for all changes. Remember that V3 legalentity maps to V5 business-establishment.

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.

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.

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.

Pagination

How cursor-based pagination works in the Lucca API.

Notable Breaking Changes

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

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

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

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

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

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

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

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": [ ... ]
      }
    ]
  }
}

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.

2. Retrieve an Establishment by ID

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": [ ... ]
  }
}

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:

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

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.

5. Find Employees in an Establishment

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

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

You need the employees.readonly and job-positions.readonly scopes to query the employees endpoint.

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

Quick Start

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.

Add the Api-Version header

Include Api-Version: 2024-11-01 on every request.

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.

Update your data model

Refer to the field mapping reference below for all changes.

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.

Pagination

How cursor-based pagination works in the Lucca API.

Notable Breaking Changes

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

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

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

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

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

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

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

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

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

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
}

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:

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:

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.

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

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

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

Lucca API Introduction

Overview of the Lucca API, versioning, and pagination.

V5 Business-Establishment Reference

Full reference for the Lucca API business-establishment resource.

V5 Legal-Entity Reference

Full reference for the Lucca API legal-entity resource.

Authentication

How to obtain and use OAuth 2.0 bearer tokens.

Pagination

Cursor-based pagination in the Lucca API, with examples.

Rate Limits

Rate and size limits applied to the Lucca API.

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

V3 Legal-Entities API

V4 Establishments & Legal-Units APIs

​Understanding the Naming Change

​Before You Start: Switch to OAuth 2.0

Authentication

Versioning

​Pick Your Starting Version

​Quick Start

​What Changes

Pagination

​Notable Breaking Changes

​Resource name changed from legalentity to business-establishment

​isActive is now isArchived (inverted semantics)

​IDs became strings in V5

​legalIdentificationNumber became taxIdentificationNumber — a structured object

​activityCode became industryCode — a structured object

​code renamed remoteId

​address restructured

​Country and currency information moved to the parent legal-entity

​Embedded users, currentUsers, and roles fields were removed

​Migration by Use Case

​1. List All Establishments

​2. Retrieve an Establishment by ID

​3. Filter by Active / Archived Status

​4. Get the Parent Legal Company

​5. Find Employees in an Establishment

​Field Mapping Reference

​Quick Start

​What Changes

Pagination

​Notable Breaking Changes

​Resource renamed from establishment to business-establishment

​IDs became strings in V5

​legalUnitId replaced with legalEntity — a typed reference

​legalIdentificationNumber became taxIdentificationNumber — a structured object

​activityCode became industryCode — a structured object

​code renamed remoteId

​address restructured

​Response envelope changed

​Migration by Use Case

​1. List All Establishments

​2. Retrieve an Establishment by ID

​3. Filter by Active / Archived Status

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

​5. Get the Parent Legal Company

​6. Get the Employee Count

​Field Mapping Reference

​Migrating V4 Legal-Units to V5 Legal-Entities

​What Changes

​Field Mapping Reference

​Further Reading

Lucca API Introduction

V5 Business-Establishment Reference

V5 Legal-Entity Reference

Authentication

Pagination

Rate Limits

Understanding the Naming Change

Before You Start: Switch to OAuth 2.0

Pick Your Starting Version

Quick Start

What Changes

Notable Breaking Changes

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

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

IDs became strings in V5

`legalIdentificationNumber` became `taxIdentificationNumber` — a structured object

`activityCode` became `industryCode` — a structured object

`code` renamed `remoteId`

`address` restructured

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

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

Migration by Use Case

1. List All Establishments

2. Retrieve an Establishment by ID

3. Filter by Active / Archived Status

4. Get the Parent Legal Company

5. Find Employees in an Establishment

Field Mapping Reference

Quick Start

What Changes

Notable Breaking Changes

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

IDs became strings in V5

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

`legalIdentificationNumber` became `taxIdentificationNumber` — a structured object

`activityCode` became `industryCode` — a structured object

`code` renamed `remoteId`

`address` restructured

Response envelope changed

Migration by Use Case

1. List All Establishments

2. Retrieve an Establishment by ID

3. Filter by Active / Archived Status

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

5. Get the Parent Legal Company

6. Get the Employee Count

Field Mapping Reference

Migrating V4 Legal-Units to V5 Legal-Entities

What Changes

Field Mapping Reference

Further Reading