Migrating Departments to the Lucca API (v5)

V3 Departments API

The V3 departments API is deprecated. The following routes will stop responding starting from September 2026:

GET /api/v3/departments
GET /api/v3/departments/{id}
GET /api/v3/departments/tree

V4 Departments API

The V4 departments API has 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.

The V5 Lucca API departments API endpoints are stable and will not undergo breaking changes. It supports both read and write operations. 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.

The V3 GET /api/v3/departments/tree endpoint has no equivalent in the V5 Lucca API. It was removed because its tree structure made pagination impossible to enforce, causing serious performance issues in large organizations. To reconstruct a tree client-side, page through GET /lucca-api/departments and use each department’s parent.id field to build the hierarchy.

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 departments	`departments.readonly`
Create or update departments	`departments.readwrite`
Read employees (for department membership)	`employees.readonly job-positions.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=departments.readonly employees.readonly job-positions.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
Migrating from V4

Quick Start

Get an OAuth 2.0 token

Request a bearer token with the departments.readonly scope (add departments.readwrite 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 /api/v3/departments?paging=0,1000 for GET /lucca-api/departments?include=links. Page through results using the cursor token in links.next.

Update your data model

Refer to the field mapping reference below for all changes.

Replace embedded user lists

The users, currentUsers, and currentUsersCount fields no longer appear on department objects. Use GET /lucca-api/employees?applicableJobPosition.department.id={id}&status=active&include=totalCount instead.

What Changes

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.
isActive → isArchived: the boolean is semantically inverted.
code → remoteId.
parentId is now parent: was an opaque hierarchy path string (e.g. "/1/2/"); now a typed { id, type, url } reference object.
IDs become strings: integers in v3 (32), strings in v5 ("32").
No embedded users/currentUsers: use the links.activeEmployees or the employees API endpoint filtered by department ID.
Pagination: v3 used ?paging={offset},{limit}; the Lucca API uses cursor tokens. Max 100 items per page (default 25).
Write operations (new in v5): POST and PATCH are now available. v3 had no write endpoints.

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.

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

v3	v5	Meaning
`isActive: true`	`isArchived: false`	Department is in use
`isActive: false`	`isArchived: true`	Department is no longer in use

A department can only be archived when no employees are currently attached to it.

IDs became strings in v5

// v3: integer
{ "id": 32 }

// v5: string
{ "id": "32" }

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

`parent` became a typed reference object in v5

In v3, parentId in the response was an opaque hierarchy path string (e.g. "/1/2/"), not a numeric ID. In v5, the parent is a typed reference:

// v3 response
{ "parentId": "/1/2/" }

// v5 response
{ "parent": { "id": "12", "type": "department", "url": "https://example.ilucca.net/lucca-api/departments/12" } }

Root-level departments have "parent": null. Use parent.id to navigate the hierarchy.

Field `code` was renamed `remoteId`

Map v3 code to v5 remoteId. Use it for external identifiers.

Embedded `users` and `currentUsers` fields were removed

v3 department objects included users, currentUsers, and currentUsersCount directly on the department. In v5, you may either follow the activeEmployees link (only returned when include=links is specified) or build the link to the employees endpoint manually:

ActiveEmployees link

{
  "id": "32",
  ...,
  "links": {
    "activeEmployees": {
      "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32&status=active&include=totalCount"
    }
  }
}

Building the link manually

GET /lucca-api/employees?applicableJobPosition.department.id={DEPARTMENT_ID}&status=active&include=links,totalCount HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01

The totalCount in the response is the equivalent of currentUsersCount. Each department also exposes a pre-built links.activeEmployees.href pointing to this query.

Migration by Use Case

1. List All Departments

GET /api/v3/departments?paging=0,1000 HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json

{
  "data": {
    "items": [
      {
        "id": 32,
        "name": "Finances",
        "code": "FIN",
        "hierarchy": "/1/",
        "parentId": null,
        "isActive": true,
        "level": 1,
        "sortOrder": 1,
        "headID": 416,
        "currentUsersCount": 12
      }
    ]
  }
}

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

{
  "type": "departments",
  "url": "https://example.ilucca.net/lucca-api/departments?limit=25",
  "items": [
    {
      "id": "32",
      "type": "department",
      "url": "https://example.ilucca.net/lucca-api/departments/32",
      "name": "Finances",
      "description": null,
      "remoteId": "FIN",
      "isArchived": false,
      "parent": null,
      "level": 1,
      "sortOrder": 0,
      "manager": {
        "id": "416",
        "type": "employee",
        "url": "https://example.ilucca.net/lucca-api/employees/416"
      },
      "owningApplication": null,
      "links": {
        "activeEmployees": {
          "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32"
        }
      }
    }
  ],
  "links": {
    "prev": null,
    "next": { "href": "https://example.ilucca.net/lucca-api/departments?page=!sdk87Sdh&limit=25" }
  }
}

The v5 department.id value is numerically the same as the v3 value, though v5 represents it as a string ("32") rather than an integer (32) in JSON.

2. Retrieve a Department by ID

GET /api/v3/departments/32 HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json

{
  "data": {
    "id": 32,
    "name": "Finances",
    "code": "FIN",
    "hierarchy": "/1/",
    "parentId": null,
    "isActive": true,
    "level": 1,
    "sortOrder": 1,
    "headID": 416
  }
}

GET /lucca-api/departments/32 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json

{
  "id": "32",
  "type": "department",
  "url": "https://example.ilucca.net/lucca-api/departments/32",
  "name": "Finances",
  "description": null,
  "remoteId": "FIN",
  "isArchived": false,
  "parent": null,
  "level": 1,
  "sortOrder": 0,
  "manager": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "owningApplication": null,
  "links": {
    "activeEmployees": {
      "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32"
    }
  }
}

3. Filter by Active / Archived Status

Intent	v3	v5
Active only	Filter client-side on `isActive: true`	`?isArchived=false`
Inactive only	Filter client-side on `isActive: false`	`?isArchived=true`
All	All returned by default	Same behavior (omit `isArchived`)

4. Navigate the Hierarchy

V3 supported a ?parentId={integer} query filter to retrieve direct children of a department. v5 has no server-side equivalent — page through all departments and group by parent.id client-side. The level field (1 = root) and sortOrder (0-based among siblings) help reconstruct the correct display order.

5. Find Employees in a Department

V3 embedded currentUsers directly on each department object. In v5, use activeEmployees link (to obtain it, add ?include=links) or query the employees endpoint directly:

GET /lucca-api/employees?applicableJobPosition.department.id=32&status=active&include=links,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 currentUsersCount.

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

v3 field	v5 field	Notes
`id`	`id`	String in v5 (integer in v3)
(new in v5)	`type`	Always `"department"`
`url`	`url`	Self-link URI
`name`	`name`
`description`	`description`
`code`	`remoteId`
`hierarchy`	(removed)	Opaque internal path; do not parse or store
`parentId`	`parent`	Now a `{ id, type, url }` reference (`null` if root)
`isActive`	`isArchived`	Semantics inverted
`position`	(removed)	Replaced by `level` and `sortOrder`
`level`	`level`	Min 1 in v5; root = 1
`sortOrder`	`sortOrder`	0-based index among siblings in v5
`headID`	`manager`	Now a `{ id, type, url }` reference
`head` (SimpleUser)	`manager`	Full reference object in v5
`owningApplication`	`owningApplication`	Set by Lucca apps; write attempts rejected with `403` if set
`users`	(removed)	Query the employees endpoint
`currentUsers`	(removed)	Use `links.activeEmployees` or query the employees endpoint
`currentUsersCount`	(removed)	Add `?include=totalCount` to the employee query
(new in v5)	`links.activeEmployees`	Pre-built link to active employees in this department

Quick Start

Get an OAuth 2.0 token

Request a bearer token with the departments.readonly scope (add departments.readwrite 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/departments?limit=10 for GET /lucca-api/departments?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

Authentication: v4 uses a proprietary API key; the Lucca API uses OAuth 2.0 bearer tokens.
Paging is cursor-based in the Lucca API, not offset-based. Max 100 items per page (default 25).
Versioning: requests must include the Api-Version: 2024-11-01 HTTP header.
Endpoint path: GET /organization/structure/api/departments → GET /lucca-api/departments.
Response envelope: { items, count, prev, next } → { type, url, items, totalCount, links: { prev, next } }.
isActive → isArchived: the boolean is semantically inverted.
code was renamed remoteId: use it for external identifiers.
parentLuccaId is now parent: integer ID replaced by a typed { id, type, url } reference object.
IDs are strings: integers in v4 (32), strings in v5 ("32").
createdAt / lastModifiedAt removed: these audit timestamps are not available in v5.
sortOrderInSiblings → sortOrder: same meaning, renamed.
Write operations (new in v5): POST and PATCH are now available. v4 had no write endpoints.

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.

`isActive` became `isArchived` (inverted semantics)

V4	v5	Meaning
`isActive: true`	`isArchived: false`	Department is in use
`isActive: false`	`isArchived: true`	Department is no longer in use

A department can only be archived when no employees are currently attached to it.

IDs became strings in v5

// V4: integer
{ "id": 32 }

// v5: string
{ "id": "32" }

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

`parentLuccaId` replaced with `parent` — an object reference

v4 exposed the parent department’s numeric ID as parentLuccaId. In v5, this is replaced by a typed reference object:

// V4 response
{
  "parentId": "/1/2/",
  "parentLuccaId": 12
}

// v5 response
{
  "parent": { "id": "12", "type": "department", "url": "https://example.ilucca.net/lucca-api/departments/12" }
}

Root-level departments have "parent": null. The opaque parentId path string is removed entirely.

`code` renamed `remoteId`

Use remoteId for external identifiers.

`createdAt` and `lastModifiedAt` removed

These audit timestamps are not available in v5.

Response envelope changed

The collection response structure differs between v4 and v5:

// V4
{
  "items": [ ... ],
  "count": 11,
  "prev": null,
  "next": "!cursorToken"
}

// v5
{
  "type": "departments",
  "url": "https://example.ilucca.net/lucca-api/departments?limit=25",
  "items": [ ... ],
  "totalCount": 11,
  "links": {
    "prev": null,
    "next": { "href": "https://example.ilucca.net/lucca-api/departments?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 Departments

GET /organization/structure/api/departments?limit=10 HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json

{
  "items": [
    {
      "id": 32,
      "name": "Finances",
      "code": "FIN",
      "description": null,
      "parentId": "/1/",
      "parentLuccaId": null,
      "hierarchy": "/1/",
      "isActive": true,
      "headId": 416,
      "createdAt": "2020-01-01T00:00:00+00:00",
      "lastModifiedAt": "2024-03-15T10:00:00+00:00",
      "sortOrderInSiblings": null
    }
  ],
  "count": 11,
  "prev": null,
  "next": "!nextCursorToken"
}

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

{
  "type": "departments",
  "url": "https://example.ilucca.net/lucca-api/departments?limit=25",
  "items": [
    {
      "id": "32",
      "type": "department",
      "url": "https://example.ilucca.net/lucca-api/departments/32",
      "name": "Finances",
      "description": null,
      "remoteId": "FIN",
      "isArchived": false,
      "parent": null,
      "level": 1,
      "sortOrder": 0,
      "manager": {
        "id": "416",
        "type": "employee",
        "url": "https://example.ilucca.net/lucca-api/employees/416"
      },
      "owningApplication": null,
      "links": {
        "activeEmployees": {
          "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32"
        }
      }
    }
  ],
  "links": {
    "prev": null,
    "next": { "href": "https://example.ilucca.net/lucca-api/departments?page=!sdk87Sdh&limit=25" }
  }
}

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 a Department by ID

GET /organization/structure/api/departments/32 HTTP/1.1
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json

{
  "id": 32,
  "name": "Finances",
  "code": "FIN",
  "description": null,
  "parentId": "/1/",
  "parentLuccaId": null,
  "hierarchy": "/1/",
  "isActive": true,
  "headId": 416,
  "createdAt": "2020-01-01T00:00:00+00:00",
  "lastModifiedAt": "2024-03-15T10:00:00+00:00",
  "sortOrderInSiblings": null
}

GET /lucca-api/departments/32 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Accept: application/json

{
  "id": "32",
  "type": "department",
  "url": "https://example.ilucca.net/lucca-api/departments/32",
  "name": "Finances",
  "description": null,
  "remoteId": "FIN",
  "isArchived": false,
  "parent": null,
  "level": 1,
  "sortOrder": 0,
  "manager": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "owningApplication": null,
  "links": {
    "activeEmployees": {
      "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32"
    }
  }
}

3. Filter by Active / Archived Status

Intent	v4	v5
Active only	Filter client-side on `isActive: true`	`?isArchived=false`
Inactive only	Filter client-side on `isActive: false`	`?isArchived=true`
All	All returned by default	Same behavior (omit `isArchived`)

4. Navigate the Hierarchy

v4 had no server-side parent filter either. Continue paging through all departments and grouping client-side — replace parentLuccaId lookups with parent.id. The level and renamed sortOrder (previously sortOrderInSiblings) fields provide the same ordering information.

5. Find Employees in a Department

Each department’s links.activeEmployees.href pre-builds the URL for you, or you can construct it directly:

GET /lucca-api/employees?applicableJobPosition.department.id=32&status=active&include=links,totalCount HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01

Field Mapping Reference

v4 field	v5 field	Notes
`id`	`id`	String in v5 (integer in v4)
(new in v5)	`type`	Always `"department"`
(new in v5)	`url`	Self-link URI
`name`	`name`
`code`	`remoteId`	Use it for external identifiers
`description`	`description`
`hierarchy`	(removed)	Opaque internal path; do not parse or store
`parentId` (path string)	(removed)	Opaque hierarchy path; replaced by `parent` reference
`parentLuccaId`	`parent`	Now a full `{ id, type, url }` reference; `null` if root
`isActive`	`isArchived`	Semantics inverted
`headId`	`manager.id`	Now a full `{ id, type, url }` reference
(new in v5)	`level`	Depth in tree; root = 1
`sortOrderInSiblings`	`sortOrder`	Renamed; 0-based index among siblings
(new in v5)	`owningApplication`	Set by Lucca apps; write attempts rejected with `403` if set
`createdAt`	(removed)	Not available in v5
`lastModifiedAt`	(removed)	Not available in v5
(new in v5)	`links.activeEmployees`	Pre-built link to active employees in this department

Writing Departments (New in v5)

Neither v3 nor v4 officially exposed write endpoints. The Lucca API introduces POST (create) and PATCH (update) operations, both requiring the departments.readwrite scope.

There is no DELETE endpoint for departments. To decommission a department, set isArchived: true via PATCH. A department can only be archived when no employees are currently attached to it.

Create a Department

POST /lucca-api/departments HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Content-Type: application/json

{
  "name": "Legal",
  "description": "Legal & Compliance team",
  "remoteId": "LEGAL",
  "parent": { "id": "32" },
  "manager": { "id": "420" },
  "sortOrder": 0
}

On success, the server responds with 201 Created, the full department representation, and a Location header pointing to the new resource URL.

Update a Department

Use PATCH with a partial body — only the fields you include will be updated:

PATCH /lucca-api/departments/55 HTTP/1.1
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: 2024-11-01
Content-Type: application/json

{
  "name": "Legal & Compliance",
  "manager": { "id": "421" }
}

Lucca API Introduction

Overview of the Lucca API, versioning, and pagination.

V5 Department Reference

Full reference for the Lucca API department 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.

V3 Departments API

V4 Departments API

​Before You Start: Switch to OAuth 2.0

Authentication

Versioning

​Pick Your Starting Version

​Quick Start

​What Changes

Pagination

​Notable Breaking Changes

​isActive is now isArchived (inverted semantics)

​IDs became strings in v5

​parent became a typed reference object in v5

​Field code was renamed remoteId

​Embedded users and currentUsers fields were removed

​Migration by Use Case

​1. List All Departments

​2. Retrieve a Department by ID

​3. Filter by Active / Archived Status

​4. Navigate the Hierarchy

​5. Find Employees in a Department

​Field Mapping Reference

​Quick Start

​What Changes

Pagination

​Notable Breaking Changes

​isActive became isArchived (inverted semantics)

​IDs became strings in v5

​parentLuccaId replaced with parent — an object reference

​code renamed remoteId

​createdAt and lastModifiedAt removed

​Response envelope changed

​Migration by Use Case

​1. List All Departments

​2. Retrieve a Department by ID

​3. Filter by Active / Archived Status

​4. Navigate the Hierarchy

​5. Find Employees in a Department

​Field Mapping Reference

​Writing Departments (New in v5)

​Create a Department

​Update a Department

​Further Reading

Lucca API Introduction

V5 Department Reference

Authentication

Pagination

Rate Limits

Before You Start: Switch to OAuth 2.0

Pick Your Starting Version

Quick Start

What Changes

Notable Breaking Changes

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

IDs became strings in v5

`parent` became a typed reference object in v5

Field `code` was renamed `remoteId`

Embedded `users` and `currentUsers` fields were removed

Migration by Use Case

1. List All Departments

2. Retrieve a Department by ID

3. Filter by Active / Archived Status

4. Navigate the Hierarchy

5. Find Employees in a Department

Field Mapping Reference

Quick Start

What Changes

Notable Breaking Changes

`isActive` became `isArchived` (inverted semantics)

IDs became strings in v5

`parentLuccaId` replaced with `parent` — an object reference

`code` renamed `remoteId`

`createdAt` and `lastModifiedAt` removed

Response envelope changed

Migration by Use Case

1. List All Departments

2. Retrieve a Department by ID

3. Filter by Active / Archived Status

4. Navigate the Hierarchy

5. Find Employees in a Department

Field Mapping Reference

Writing Departments (New in v5)

Create a Department

Update a Department

Further Reading