> 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/forms/form-field-types.md).

# FormFieldTypes

## Introduction

`FormFieldTypes` describe how [FormFields](/api-reference/forms/form-fields.md) are rendered and which `config` they accept.

The `rich-text` and `description` type values and the `privacy-policy` type's `config.text` value use the shared [Rich Text](/introduction/rich-text.md) HTML format.

## Model Definition

**Alias**

`formFieldType`

**Attributes**

| Key              | Type      | Description                                                                                                                                                       |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | `string`  | Stable field type ID used by `form_field_type_id`.                                                                                                                |
| `icon_id`        | `integer` | Stable ID from [Available Icons](/api-reference/icons.md#available-icons) assigned to the field type.                                                             |
| `default_config` | `object`  | Source-defined starting `config` used when a field of this type is created without an explicit configuration; required editor placeholders may still need values. |
| `unique`         | `boolean` | Whether a form can contain only one field of this type.                                                                                                           |
| `relevant`       | `boolean` | Whether fields of this type are included when form results are processed.                                                                                         |

## Available Form Field Types

The following field types are available in the current API version. Each entry combines the complete source-defined default with the accepted configuration keys. The defaults are editor starting points and may contain required placeholders that must be replaced before submission. Dot notation identifies nested object keys; additional unlisted keys are not part of the public contract.

### `text` <a href="#form-field-type-text" id="form-field-type-text"></a>

**Default Config**

```json
{
  "scanner": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `72`    | `false` | `true`   |

Plain text input with optional scanner assistance.

**Configuration Keys**

| Key       | Type      | Requirement | Description                         |
| --------- | --------- | ----------- | ----------------------------------- |
| `scanner` | `boolean` | Required    | Enable scanner-assisted text input. |

### `boolean` <a href="#form-field-type-boolean" id="form-field-type-boolean"></a>

**Default Config**

```json
{
  "type": "labeled_buttons",
  "representation": {
    "true": "Ja",
    "false": "Nein"
  }
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `43`    | `false` | `true`   |

Boolean input with configurable labels, icons, and grades.

**Configuration Keys**

| Key                    | Type               | Requirement                 | Description                                                                                          |
| ---------------------- | ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `type`                 | `string`           | Required                    | Presentation type: `switch`, `labeled_buttons`, or `icon_buttons`.                                   |
| `representation.true`  | `string`           | Required                    | Translatable label for the true value.                                                               |
| `representation.false` | `string`           | Required                    | Translatable label for the false value.                                                              |
| `icons.true`           | `string`           | Required for `icon_buttons` | Icon identifier for the true value. See [Available Icons](/api-reference/icons.md#available-icons).  |
| `icons.false`          | `string`           | Required for `icon_buttons` | Icon identifier for the false value. See [Available Icons](/api-reference/icons.md#available-icons). |
| `grades`               | `object` \| `null` | Optional                    | Numeric grades keyed by result value.                                                                |
| `grades.*`             | `mixed`            | Optional                    | Numeric grade for one result value.                                                                  |

### `rich-text` <a href="#form-field-type-rich-text" id="form-field-type-rich-text"></a>

**Default Config**

```json
{}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `73`    | `false` | `true`   |

[Rich Text](/introduction/rich-text.md) input without additional configuration keys.

### `checkbox` <a href="#form-field-type-checkbox" id="form-field-type-checkbox"></a>

**Default Config**

```json
{
  "options": {
    "1": {
      "title": "Option 1",
      "value": null
    }
  },
  "inline": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `74`    | `false` | `true`   |

Multiple-choice input rendered as checkboxes. The default contains `inline`, but the backend does not validate this key.

**Configuration Keys**

| Key               | Type               | Requirement   | Description                                         |
| ----------------- | ------------------ | ------------- | --------------------------------------------------- |
| `options`         | `object`           | Required      | At least one option keyed by its stable option ID.  |
| `options.*.title` | `string`           | Required      | Translatable option label.                          |
| `options.*.value` | `mixed` \| `null`  | Optional      | Optional value associated with the option.          |
| `option_grades`   | `object` \| `null` | Optional      | Numeric grades keyed by an existing option ID.      |
| `option_grades.*` | `mixed`            | Optional      | Numeric grade for one option.                       |
| `inline`          | `boolean`          | Not validated | Source-defined display flag retained in the config. |

### `radio` <a href="#form-field-type-radio" id="form-field-type-radio"></a>

**Default Config**

```json
{
  "options": {
    "1": {
      "title": "Option 1",
      "value": null
    }
  },
  "inline": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `42`    | `false` | `true`   |

Single-choice input rendered as radio buttons. The default contains `inline`, but the backend does not validate this key.

**Configuration Keys**

| Key               | Type               | Requirement   | Description                                         |
| ----------------- | ------------------ | ------------- | --------------------------------------------------- |
| `options`         | `object`           | Required      | At least one option keyed by its stable option ID.  |
| `options.*.title` | `string`           | Required      | Translatable option label.                          |
| `options.*.value` | `mixed` \| `null`  | Optional      | Optional value associated with the option.          |
| `option_grades`   | `object` \| `null` | Optional      | Numeric grades keyed by an existing option ID.      |
| `option_grades.*` | `mixed`            | Optional      | Numeric grade for one option.                       |
| `inline`          | `boolean`          | Not validated | Source-defined display flag retained in the config. |

### `select` <a href="#form-field-type-select" id="form-field-type-select"></a>

**Default Config**

```json
{
  "options": {
    "1": {
      "title": "Option 1",
      "value": null
    }
  },
  "inline": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `71`    | `false` | `true`   |

Single-choice input rendered as a select control. The default contains `inline`, but the backend does not validate this key.

**Configuration Keys**

| Key               | Type               | Requirement   | Description                                         |
| ----------------- | ------------------ | ------------- | --------------------------------------------------- |
| `options`         | `object`           | Required      | At least one option keyed by its stable option ID.  |
| `options.*.title` | `string`           | Required      | Translatable option label.                          |
| `options.*.value` | `mixed` \| `null`  | Optional      | Optional value associated with the option.          |
| `option_grades`   | `object` \| `null` | Optional      | Numeric grades keyed by an existing option ID.      |
| `option_grades.*` | `mixed`            | Optional      | Numeric grade for one option.                       |
| `inline`          | `boolean`          | Not validated | Source-defined display flag retained in the config. |

### `datetime` <a href="#form-field-type-datetime" id="form-field-type-datetime"></a>

**Default Config**

```json
{
  "type": "date",
  "format": "DD.MM.YYYY"
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `3`     | `false` | `true`   |

Date and time input with a type-specific display format.

**Configuration Keys**

| Key      | Type     | Requirement | Description                                                                                                                                                                                   |
| -------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`   | `string` | Required    | Value type: `datetime`, `date`, or `time`.                                                                                                                                                    |
| `format` | `string` | Required    | Format allowed for the selected type: `DD.MM.YYYY HH:mm` or `dddd, Do MMMM YYYY [um] HH:mm` for `datetime`; `DD.MM.YYYY`, `YYYY`, or `dddd, Do MMMM YYYY` for `date`; and `HH:mm` for `time`. |

### `file-upload` <a href="#form-field-type-file-upload" id="form-field-type-file-upload"></a>

**Default Config**

```json
{
  "path": "/Formular-Uploads/",
  "send_as_attachment": false,
  "show_preview": true
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `19`    | `false` | `true`   |

File input with storage, attachment, and preview settings.

**Configuration Keys**

| Key                  | Type      | Requirement | Description                                             |
| -------------------- | --------- | ----------- | ------------------------------------------------------- |
| `path`               | `string`  | Required    | Directory path retained with the upload configuration.  |
| `send_as_attachment` | `boolean` | Required    | Attach uploaded files when distributing a form message. |
| `show_preview`       | `boolean` | Required    | Show a preview for supported uploaded files.            |

### `entity-select` <a href="#form-field-type-entity-select" id="form-field-type-entity-select"></a>

**Default Config**

```json
{
  "entity_type": null,
  "selectable_entities_filters": null,
  "representation": {
    "label_template": null,
    "result_template": null,
    "display": {
      "type": "select-modal",
      "config": null
    }
  }
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `129`   | `false` | `true`   |

Single-entity selection. The default `entity_type: null` is an editor placeholder; a submitted config requires a selectable entity alias.

**Configuration Keys**

| Key                                    | Type               | Requirement                  | Description                                                                                                           |
| -------------------------------------- | ------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `entity_type`                          | `string`           | Required                     | Entity alias for a resource that supports selection.                                                                  |
| `selectable_entities_filters`          | `object` \| `null` | Optional                     | Filters applied when resolving selectable entities.                                                                   |
| `representation`                       | `object`           | Required                     | Representation settings.                                                                                              |
| `representation.label_template`        | `string` \| `null` | Optional                     | Validated [System Variable template](/introduction/system-variables.md#rendered-templates) used for selection labels. |
| `representation.result_template`       | `string` \| `null` | Optional                     | Validated [System Variable template](/introduction/system-variables.md#rendered-templates) used for resolved results. |
| `representation.display`               | `object`           | Required                     | Selection control settings.                                                                                           |
| `representation.display.type`          | `string`           | Required                     | Display type: `radio`, `select`, or `select-modal`.                                                                   |
| `representation.display.config`        | `object` \| `null` | Optional                     | Configuration for the selected display type.                                                                          |
| `representation.display.config.inline` | `boolean`          | Required for `radio` display | Display radio choices inline.                                                                                         |

### `entities-select` <a href="#form-field-type-entities-select" id="form-field-type-entities-select"></a>

**Default Config**

```json
{
  "entity_type": null,
  "selectable_entities_filters": null,
  "representation": {
    "label_template": null,
    "result_template": null,
    "display": {
      "type": "select-modal",
      "config": null
    }
  }
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `163`   | `false` | `true`   |

Multiple-entity selection. The default `entity_type: null` is an editor placeholder; a submitted config requires a selectable entity alias.

**Configuration Keys**

| Key                              | Type               | Requirement | Description                                                                                                           |
| -------------------------------- | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `entity_type`                    | `string`           | Required    | Entity alias for a resource that supports selection.                                                                  |
| `selectable_entities_filters`    | `object` \| `null` | Optional    | Filters applied when resolving selectable entities.                                                                   |
| `representation`                 | `object`           | Required    | Representation settings.                                                                                              |
| `representation.label_template`  | `string` \| `null` | Optional    | Validated [System Variable template](/introduction/system-variables.md#rendered-templates) used for selection labels. |
| `representation.result_template` | `string` \| `null` | Optional    | Validated [System Variable template](/introduction/system-variables.md#rendered-templates) used for resolved results. |
| `representation.display`         | `object`           | Required    | Selection control settings.                                                                                           |
| `representation.display.type`    | `string`           | Required    | Display type: `checkbox` or `select-modal`.                                                                           |
| `representation.display.config`  | `object` \| `null` | Optional    | Configuration for the selected display type.                                                                          |

### `recipient-select` <a href="#form-field-type-recipient-select" id="form-field-type-recipient-select"></a>

**Default Config**

```json
{
  "options": {
    "1": {
      "title": "intratool",
      "value": "noreply@intratool.de"
    }
  },
  "multi_select": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `4`     | `false` | `true`   |

Recipient selection backed by configured email-address options.

**Configuration Keys**

| Key               | Type               | Requirement | Description                                                           |
| ----------------- | ------------------ | ----------- | --------------------------------------------------------------------- |
| `options`         | `object`           | Required    | At least one recipient option keyed by its stable option ID.          |
| `options.*.title` | `string`           | Required    | Translatable recipient label.                                         |
| `options.*.value` | `string`           | Required    | One email address or a comma-separated list of valid email addresses. |
| `option_grades`   | `object` \| `null` | Optional    | Numeric grades keyed by an existing option ID.                        |
| `option_grades.*` | `mixed`            | Optional    | Numeric grade for one option.                                         |
| `multi_select`    | `boolean`          | Required    | Allow more than one recipient option.                                 |

### `description` <a href="#form-field-type-description" id="form-field-type-description"></a>

**Default Config**

```json
{}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `56`    | `false` | `true`   |

Non-input [Rich Text](/introduction/rich-text.md) content without additional configuration keys.

### `privacy-policy` <a href="#form-field-type-privacy-policy" id="form-field-type-privacy-policy"></a>

**Default Config**

```json
{
  "text": "<p>Ja, ich habe die {{Datenschutzbestimmungen}} gelesen und akzeptiere diese.</p>",
  "external": true
}
```

| Icon ID | Unique | Relevant |
| ------- | ------ | -------- |
| `127`   | `true` | `true`   |

Privacy-policy acceptance field. A form can contain only one field of this type.

**Configuration Keys**

| Key        | Type      | Requirement | Description                                                                                                                                    |
| ---------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`     | `string`  | Required    | Translatable [Rich Text](/introduction/rich-text.md) acceptance text. Text inside double curly brackets becomes the privacy-policy link label. |
| `external` | `boolean` | Required    | Link to the external privacy policy when `true`; otherwise link to the internal privacy policy.                                                |

### `signature` <a href="#form-field-type-signature" id="form-field-type-signature"></a>

**Default Config**

```json
{
  "path": "/Formular-Uploads/Signaturen/",
  "send_as_attachment": false
}
```

| Icon ID | Unique  | Relevant |
| ------- | ------- | -------- |
| `128`   | `false` | `true`   |

Signature input with storage and attachment settings.

**Configuration Keys**

| Key                  | Type      | Requirement | Description                                                 |
| -------------------- | --------- | ----------- | ----------------------------------------------------------- |
| `path`               | `string`  | Required    | Directory path retained with the signature configuration.   |
| `send_as_attachment` | `boolean` | Required    | Attach the signature file when distributing a form message. |

## List

List available `FormFieldTypes`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/field-types`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": "text",
    "icon_id": 72,
    "default_config": {
      "scanner": false
    },
    "unique": false,
    "relevant": true,
    "sort_number": 1
  },
  {
    "id": "checkbox",
    "icon_id": 74,
    "default_config": {
      "options": {
        "1": {
          "title": "Option 1",
          "value": null
        }
      },
      "inline": false
    },
    "unique": false,
    "relevant": true,
    "sort_number": 4
  }
]
```

## Show

Show one `FormFieldType`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/field-types/{formFieldType}`

**Route Parameters**

| Parameter       | Type     | Description                                                             |
| --------------- | -------- | ----------------------------------------------------------------------- |
| `formFieldType` | `string` | Type ID from [Available Form Field Types](#available-form-field-types). |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": "text",
  "icon_id": 72,
  "default_config": {
    "scanner": false
  },
  "unique": false,
  "relevant": true,
  "sort_number": 1
}
```