> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/departments.md).

# Departments

## Introduction

`Departments` represent organizational units used by roles, user membership, targeting, permissions, and notifications.

## Model Definition

**Alias**

`department`

**Capabilities**

* [Targetables](/introduction/resource-capabilities/targetables.md) - Departments can be selected as explicit targets for supported resources.
* [URL Context](/introduction/resource-capabilities/url-context.md) - Department URLs resolve to access-checked context.

**Relations**

| Key             | Relation                                                                | Type                   | Relation Field(s)         |
| --------------- | ----------------------------------------------------------------------- | ---------------------- | ------------------------- |
| `roles`         | [Roles](/api-reference/roles.md)                                        | Has many               | `department_id`           |
| `users`         | [Users](/api-reference/users.md)                                        | Has many through roles | Role membership           |
| `attributeSets` | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) | Morph to many          | Target entity type and ID |

## List

List visible `Departments`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/departments`

**Request Keys**

| Key         | Type      | Default           | Description                               |
| ----------- | --------- | ----------------- | ----------------------------------------- |
| `selects`   | `string`  | All fields        | Comma-separated fields to return.         |
| `relations` | `string`  | Default relations | Pipe-separated relations to include.      |
| `limit`     | `integer` | No limit          | Maximum number of departments.            |
| `filter`    | `object`  | No filters        | Filters, including tag-aware text search. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/departments', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 6,
    "name": "Engineering",
    "user_id": 7,
    "folder_id": 12,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  },
  {
    "id": 9,
    "name": "Product",
    "user_id": 8,
    "folder_id": null,
    "created_at": "2026-08-06 09:05:00",
    "updated_at": "2026-08-06 09:05:00",
    "deleted_at": null
  }
]
```

## Show

Show one visible `Department`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/departments/{department}`

**Route Parameters**

| Parameter    | Type      | Description    |
| ------------ | --------- | -------------- |
| `department` | `integer` | Department ID. |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/departments/6', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 6,
  "name": "Engineering",
  "user_id": 7,
  "folder_id": 12,
  "created_at": "2026-08-06 09:00:00",
  "updated_at": "2026-08-06 09:00:00",
  "deleted_at": null
}
```

## Availability Information

Show availability information for `Departments`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/departments/availability-information`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/departments/availability-information', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "total_available": 20,
  "available": 14,
  "used": 6
}
```

## Create

Create a new `Department`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/departments`

**Request Keys**

| Key                        | Type                | Default                | Description                                                                                                                    |
| -------------------------- | ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `name`\*                   | `string`            | -                      | Unique department name.                                                                                                        |
| `folder_id`                | `integer` \| `null` | `null`                 | Parent [Folder](/api-reference/folders.md) ID.                                                                                 |
| `notification_setting_ids` | `array`             | Current or no settings | Notification-setting IDs assigned to the department.                                                                           |
| `attribute_set_ids`        | `array`             | Current or no sets     | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) to attach; records may include `id` and `sort_number`. |
| Additional attribute keys  | `mixed`             | Defined by set         | Values for fields from the attached AttributeSets.                                                                             |

Keys with `*` are required.

**Behavior**

The authenticated user becomes `user_id`. The example attaches the department attribute set and supplies both values needed to materialize those additional attributes.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/departments', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Customer Success',
        'folder_id' => 12,
        'notification_setting_ids' => [14],
        'attribute_set_ids' => [[
            'id' => 31,
            'sort_number' => 1
        ]],
        'cost-center' => 'CS-410',
        'office-floor' => 4
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 10,
    "name": "Customer Success",
    "user_id": 7,
    "folder_id": 12,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 09:00:00",
    "deleted_at": null
  }
}
```

## Update

Update an existing `Department`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/departments/{department}`

**Route Parameters**

| Parameter    | Type      | Description    |
| ------------ | --------- | -------------- |
| `department` | `integer` | Department ID. |

**Request Keys**

| Key                        | Type                | Default                | Description                                                                                                                    |
| -------------------------- | ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `name`\*                   | `string`            | -                      | Unique department name.                                                                                                        |
| `folder_id`                | `integer` \| `null` | `null`                 | Parent [Folder](/api-reference/folders.md) ID.                                                                                 |
| `notification_setting_ids` | `array`             | Current or no settings | Notification-setting IDs assigned to the department.                                                                           |
| `attribute_set_ids`        | `array`             | Current or no sets     | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) to attach; records may include `id` and `sort_number`. |
| Additional attribute keys  | `mixed`             | Defined by set         | Values for fields from the attached AttributeSets.                                                                             |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/departments/10', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Customer Experience',
        'folder_id' => null,
        'notification_setting_ids' => [14],
        'attribute_set_ids' => [[
            'id' => 31,
            'sort_number' => 1
        ]],
        'cost-center' => 'CX-410',
        'office-floor' => 5
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 10,
    "name": "Customer Experience",
    "user_id": 7,
    "folder_id": null,
    "created_at": "2026-08-06 09:00:00",
    "updated_at": "2026-08-06 10:00:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `Department`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/departments/{department}`

**Route Parameters**

| Parameter    | Type      | Description    |
| ------------ | --------- | -------------- |
| `department` | `integer` | Department ID. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/departments/10', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```