> 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/introduction/additional-attributes.md).

# Additional Attributes

## Introduction

Additional attribute provide configurable fields for entities such as [Departments](/api-reference/departments.md) and [Roles](/api-reference/roles.md). An `AttributeSet` acts as a container for fields (similar to Forms/TaskTemplates), while values are stored per target entity.

## Request flow

Before linking `AttributeSets` to target entities, you should create the attribute set and fill it with attributes.

* [**AttributeSet**](/api-reference/additional-attributes/attribute-sets.md): Defines the grouping and structure of additional fields.
* [**AttributeFields**](/api-reference/additional-attributes/attribute-fields.md): Concrete fields inside an `AttributeSet`.

## Target entity linking and attribute value assignment

For entities that use `AttributeSets` (currently especially `Department` and `Role`), the request structure for linking and submitting values follows the same pattern.

### Payload keys for creating and updating entities with AttributeSets

for example these endpoints:

* `PUT /api/departments/{department}`
* `PUT /api/roles/{role}`
* `POST /api/departments/{department}`
* `POST /api/roles/{role}`

| Key                     | Type     | Description                                                                 |
| ----------------------- | -------- | --------------------------------------------------------------------------- |
| `attribute_set_ids`     | `array`  | Which `AttributeSets` should be linked to the target entity.                |
| `additional_attributes` | `object` | Values grouped by `attributeSet.key` and field key (`field-{formFieldId}`). |

### `attribute_set_ids` formats

`attribute_set_ids` supports two formats:

#### IDs only

```json
{
  "attribute_set_ids": [1, 2, 3]
}
```

#### IDs with sorting

```json
{
  "attribute_set_ids": [
    { "id": 1, "sort_number": 1 },
    { "id": 2, "sort_number": 2 }
  ]
}
```

### `additional_attributes` structure

Values are passed per `attributeSet.key`. Inside each set, field keys follow the pattern `field-{formFieldId}`.

```json
{
  "additional_attributes": {
    "employee-data": {
      "field-17": "Max Mustermann",
      "field-18": "DE"
    },
    "contract": {
      "field-24": "2026-05-01"
    }
  }
}
```

### Combined example

```json
{
  "name": "Operations",
  "attribute_set_ids": [
    { "id": 1, "sort_number": 1 },
    { "id": 2, "sort_number": 2 }
  ],
  "additional_attributes": {
    "employee-data": {
      "field-17": "Max Mustermann",
      "field-18": "DE"
    }
  }
}
```

## See also

* [Additional Attributes detailed API reference](/api-reference/additional-attributes.md)
* [Departments](/api-reference/departments.md)
* [Roles](/api-reference/roles.md)