> ## 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 Departments to the Lucca API (v5)

> Migration steps from the V3 or V4 departments APIs to the Lucca API (v5) department resource.

<CardGroup cols={1}>
  <Card title="V3 Departments API" horizontal>
    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`
  </Card>

  <Card title="V4 Departments API" horizontal>
    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.
  </Card>
</CardGroup>

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

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

<Tip>
  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`.
</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">
    ### Quick Start

    <Steps titleSize="p">
      <Step title="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.
      </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/departments?paging=0,1000` for `GET /lucca-api/departments?include=links`. 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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    ***

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

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

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

    ```json theme={null}
    // 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:

    ```json theme={null}
    // 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:

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

    ```http Building the link manually theme={null}
    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

    <CodeGroup>
      ```http V3 theme={null}
      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
            }
          ]
        }
      }
      ```

      ```http V5 theme={null}
      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" }
        }
      }
      ```
    </CodeGroup>

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

    #### 2. Retrieve a Department by ID

    <CodeGroup>
      ```http V3 theme={null}
      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
        }
      }
      ```

      ```http V5 theme={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"
          }
        }
      }
      ```
    </CodeGroup>

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

    ```http theme={null}
    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`.

    <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

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

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

    <Steps titleSize="p">
      <Step title="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.
      </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/departments?limit=10` for `GET /lucca-api/departments?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

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

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

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

    ```json theme={null}
    // 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:

    ```json theme={null}
    // 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:

    ```json theme={null}
    // 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

    <CodeGroup>
      ```http V4 theme={null}
      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"
      }
      ```

      ```http V5 theme={null}
      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" }
        }
      }
      ```
    </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 a Department by ID

    <CodeGroup>
      ```http V4 theme={null}
      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
      }
      ```

      ```http V5 theme={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"
          }
        }
      }
      ```
    </CodeGroup>

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

    ```http theme={null}
    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        |
  </Tab>
</Tabs>

***

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

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

### Create a Department

```http V5 theme={null}
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:

```http V5 theme={null}
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" }
}
```

***

## 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 Department Reference" icon="sitemap" cta="Read more" href="/api-reference/latest/organization/department">
    Full reference for the Lucca API department 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>