> 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 locations or user groups within the customer system and serve as the starting point of the permission system.

They are used to structure organizational units, which are essential for assigning permissions and managing access to content in various modules.

The assignment of content is typically based either on specific [Users](/api-reference/users.md) or on the associated `Department`.

## Model Definition

### Alias

`department`

### Relations

| Key             | Relation                                                                | Type          | Relation Field(s)                                                                                                                                |
| --------------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user`          | [User](/api-reference/users.md)                                         | Belongs to    | `user_id`                                                                                                                                        |
| `roles`         | [Roles](/api-reference/roles.md)                                        | Has many      | `roles.department_id`                                                                                                                            |
| `attributeSets` | [AttributeSets](/api-reference/additional-attributes/attribute-sets.md) | Morph to many | `target_entity_attribute_set.target_entity_type`, `target_entity_attribute_set.target_entity_id`, `target_entity_attribute_set.attribute_set_id` |

## List

Get a list of all `Departments`.

**Definition**

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

**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": 2,
    "name": "Standort 01",
    "user_id": 2,
    "folder_id": null,
    "created_at": "2019-01-15 12:00:00",
    "updated_at": "2019-01-15 12:00:00",
    "deleted_at": null
  },
  {
    "id": 3,
    "name": "Standort 02",
    "user_id": 2,
    "folder_id": null,
    "created_at": "2019-01-15 13:00:00",
    "updated_at": "2019-01-15 13:00:00",
    "deleted_at": null
  }
]
```

## Show

Show a single `Department` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 2,
  "name": "Standort 01",
  "user_id": 2,
  "folder_id": null,
  "created_at": "2019-01-15 12:00:00",
  "updated_at": "2019-01-15 12:00:00",
  "deleted_at": null
}
```

## Show availability information

Show the "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": 10,
  "available": 8,
  "used": 2
}
```

## Create

Create a new `Department`.

**Definition**

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

**Request Keys**

| Key                 | Type    | Default | Description                                                                                                                                                                                                                                       |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` \*           | string  | -       | The name of the `Department`.                                                                                                                                                                                                                     |
| `attribute_set_ids` | array   | -       | Attribute sets to link to this department (IDs or objects with `id` and optional `sort_number`, see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)). |
| `folder_id`         | integer | -       | The ID of [Folder](/api-reference/folders.md) the `Department` is assigned to.                                                                                                                                                                    |

Keys with `*` are required.

#### Advanced Key-Specifications

* `attribute_set_ids` - Supports two formats (see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)):
  * `[1, 2, 3]`
  * `[{"id": 1, "sort_number": 1}, {"id": 2, "sort_number": 2}]`

{% hint style="warning" %}
The request can fail if the maximum number of `Departments` is already reached.
{% endhint %}

**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' => 'Standort 03'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 4,
    "name": "Standort 03",
    "user_id": 2,
    "folder_id": null,
    "created_at": "2019-01-15 14:00:00",
    "updated_at": "2019-01-15 14:00:00",
    "deleted_at": null
  }
}
```

## Update

Update an existing `Department` by `id`.

**Definition**

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

**Request Keys**

| Key                 | Type    | Description                                                                                                                                                                                                                                       |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string  | The name of the `Department`.                                                                                                                                                                                                                     |
| `attribute_set_ids` | array   | Attribute sets to link to this department (IDs or objects with `id` and optional `sort_number`, see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)). |
| `folder_id`         | integer | The ID of [Folder](/api-reference/folders.md) the `Department` is assigned to.                                                                                                                                                                    |

#### Advanced Key-Specifications

* `attribute_set_ids` - Supports two formats (see [Linking AttributeSets to target entities](/api-reference/additional-attributes/attribute-sets.md#linking-attributesets-to-target-entities)):
  * `[1, 2, 3]`
  * `[{"id": 1, "sort_number": 1}, {"id": 2, "sort_number": 2}]`

**Example Request**

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

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

```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 4,
    "name": "Standort - 03",
    "user_id": 2,
    "folder_id": null,
    "created_at": "2019-01-15 14:00:00",
    "updated_at": "2019-01-15 14:30:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `Department` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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