# FormFieldTypes

## Introduction

`FormFieldTypes` associated to `FormFields` by their key describe how inputs are displayed for the end user and which kind of information needs to be submitted and stored in `FormMessageFields` [when sending a Form.](/api-reference/forms/forms.md#send)

Every `FormFieldType` offers a generic default configuration and describes how a concrete configuration is validated when creating a `FormField`.

## List

Get a list of all `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,
    "name": "Eingabefeld",
    "default_config": {},
    "unique": false,
    "relevant": true,
    "sort_number": 1,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 00:00:00"
  },
  {
    "id": "rich-text",
    "icon_id": 73,
    "name": "Freitext",
    "default_config": {},
    "unique": false,
    "relevant": true,
    "sort_number": 2,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 00:00:00"
  },
  {
    "id": "checkbox",
    "icon_id": 74,
    "name": "Mehrfachauswahl",
    "default_config": {
      "options": {
        "option-1": "Option 1"
      },
      "inline": false
    },
    "unique": false,
    "relevant": true,
    "sort_number": 3,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 13:44:14"
  },
  {
    "id": "radio",
    "icon_id": 42,
    "name": "Auswahl",
    "default_config": {
      "options": {
        "option-1": "Option 1"
      },
      "inline": false
    },
    "unique": false,
    "relevant": true,
    "sort_number": 4,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 13:44:14"
  },
  {
    "id": "select",
    "icon_id": 71,
    "name": "Ausklappmen\u00fc",
    "default_config": {
      "options": {
        "option-1": "Option 1"
      }
    },
    "unique": false,
    "relevant": true,
    "sort_number": 5,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 00:00:00"
  },
  {
    "id": "datetime",
    "icon_id": 3,
    "name": "Datum/Zeit",
    "default_config": {
      "type": "date",
      "format": "d.m.Y"
    },
    "unique": false,
    "relevant": true,
    "sort_number": 6,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 00:00:00"
  },
  {
    "id": "file-upload",
    "icon_id": 19,
    "name": "Datei-Upload",
    "default_config": {
      "path": "/Formular-Uploads/",
      "send_as_attachment": false
    },
    "unique": false,
    "relevant": true,
    "sort_number": 7,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 13:44:14"
  },
  {
    "id": "recipient-select",
    "icon_id": 4,
    "name": "Empf\u00e4nger-Auswahl",
    "default_config": {
      "options": {},
      "multi_select": false
    },
    "unique": true,
    "relevant": true,
    "sort_number": 8,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 13:44:14"
  },
  {
    "id": "description",
    "icon_id": 56,
    "name": "Beschreibung",
    "default_config": {},
    "unique": false,
    "relevant": true,
    "sort_number": 9,
    "created_at": "2019-01-21 00:00:00",
    "updated_at": "2019-01-21 13:44:14"
  },
  {
    "id": "entity-select",
    "icon_id": 129,
    "name": "Entit\u00e4t ausw\u00e4hlen",
    "default_config": {
      "entity_type": null,
      "selectable_entities_filters": null,
      "representation": {
        "label_template": null,
        "result_template": null,
        "display": {
          "type": "select-modal",
          "config": null
        }
      }
    },
    "unique": false,
    "relevant": true,
    "sort_number": 10,
    "created_at": "2026-03-02 00:00:00",
    "updated_at": "2026-03-02 00:00:00"
  },
  {
    "id": "entities-select",
    "icon_id": 163,
    "name": "Entit\u00e4ten ausw\u00e4hlen",
    "default_config": {
      "entity_type": null,
      "selectable_entities_filters": null,
      "representation": {
        "label_template": null,
        "result_template": null,
        "display": {
          "type": "select-modal",
          "config": null
        }
      }
    },
    "unique": false,
    "relevant": true,
    "sort_number": 11,
    "created_at": "2026-03-02 00:00:00",
    "updated_at": "2026-03-02 00:00:00"
  }
]
```

## Show

Show a single `FormFieldType` by `id`.

**Definition**

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

**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/rich-text', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[]
```

## Text

The default type for displaying a simple input field.

**Key:** `text`

**Configuration**

No further configuration available.

## RichText

A field that is displayed as an input box and with basic RTE features.

**Key** `rich-text`

**Configuration**

No further configuration available.

## Description

A label field to display text in the form to describe sections. This is not actually and HTML input field and will not be processed in [FormMessages](/api-reference/forms/form-messages.md).

**Key:** `description`

**Configuration**

No further configuration available.

## DateTime

A field that is displayed as DateInput and a DatePicker.

**Key:** `datetime`

**Configuration**

| Key      | Description                                                                | Type   | Default | Example |
| -------- | -------------------------------------------------------------------------- | ------ | ------- | ------- |
| `type`   | The type of the date field. Can be either time or date                     | string | `date`  | `time`  |
| `format` | The date format. Has to be a valid date format for either `time` or `date` | string | `d.m.Y` | `H:i`   |

## FileUpload

A field that is displayed as FileInput to upload a file from form.

**Key** `file-upload`

**Configuration**

| Key                  | Description                                                               | Type    | Default              | Example      |
| -------------------- | ------------------------------------------------------------------------- | ------- | -------------------- | ------------ |
| `path`               | The path the file should be uploaded to on `Filemanager`                  | string  | `/Formular-Uploads/` | `/folder-1/` |
| `send_as_attachment` | Indicates if the file should be attached on sent mails or shown as a Link | boolean | `false`              | `true`       |

## Radio

A field that is displayed as radio input to select one of the configured values.

**Key** `radio`

**Configuration**

| Key       | Description                                                 | Type    | Default                      | Example                                              |
| --------- | ----------------------------------------------------------- | ------- | ---------------------------- | ---------------------------------------------------- |
| `options` | The definition of option-keys and their values              | object  | `{ "option-1": "Option 1" }` | `{ "option-1": "Option 1", "option-2": "Option 2" }` |
| `inline`  | Indicates if the possible values should be displayed inline | boolean | `false`                      | `true`                                               |

## Checkbox

A field that is displayed as checkboxes to select one or more of the configured values.

**Key** `checkbox`

**Configuration**

| Key       | Description                                                 | Type    | Default                      | Example                                              |
| --------- | ----------------------------------------------------------- | ------- | ---------------------------- | ---------------------------------------------------- |
| `options` | The definition of option-keys and their values              | object  | `{ "option-1": "Option 1" }` | `{ "option-1": "Option 1", "option-2": "Option 2" }` |
| `inline`  | Indicates if the possible values should be displayed inline | boolean | `false`                      | `true`                                               |

## Recipient-Select

A field to select recipients of a [Form](/api-reference/forms/forms.md). This field type is unique for every [Form](/api-reference/forms/forms.md) and will have effect on the `recipient` field of a [FormMessage](/api-reference/forms/form-messages.md) when it's created.

While sending [FormMessages](/api-reference/forms/form-messages.md), the values of this field will be used as the receiver(s).

**Key** `recipient-select`

**Configuration**

| Key            | Description                                                  | Type    | Default | Example                                  |
| -------------- | ------------------------------------------------------------ | ------- | ------- | ---------------------------------------- |
| `options`      | The definition of option-keys and their values               | object  | `{}`    | `{ "Example name": "name@example.com" }` |
| `multi_select` | Indicates if it's possible to select more than one recipient | boolean | `false` | `true`                                   |

{% hint style="warning" %}
You can set more than one recipient for one option by separating the email addresses with commas
{% endhint %}

## EntitySelect

A field that allows users to select a single entity from a specified entity type. This field type is useful when a form needs to capture a reference to exactly one existing entity in the system.

**Key:** `entity-select`

**Configuration**

\| Key | Description | Type | Default | Required | Example | | -------------------------------- | ---------------------------------------------------------------------------------- | ------------ | -------------- | -------- | ----------------------------------------------- | ------------------------------------------------- | | `entity_type` | The type of entity that can be selected (e.g., 'user', 'department') | string | `null` | Yes | `user` | | `selectable_entities_filters` | Optional filters to pre-filter available entities (e.g., by department or role) | object|null | `null` | No | `{"department_id": 5}` or `{"role": "manager"}` | | `representation` | Configuration for how entities are displayed and represented | object | (see below) | Yes | (see below) | | `representation.label_template` | Optional template string for field label display | string|null | `null` | No | `"Select a {{entity_type}}"` | | `representation.result_template` | Optional template string for displaying the selected entity in form results/emails | string|null | `null` | No | `"{{selectableEntity | format_user_name}} - {{selectableEntity.email}}"` | | `representation.display` | Display configuration for the selection interface | object | (see below) | Yes | (see below) | | `representation.display.type` | The type of selection interface: `radio`, `select`, or `select-modal` | string | `select-modal` | Yes | `select` | | `representation.display.config` | Optional additional configuration for the display type | object|null | `null` | No | `{"inline": true}` (for radio type) |

**Behavior:**

* Users can select exactly one entity from the available options
* The field value is submitted and stored as a single entity ID
* Available entities can be filtered based on `selectable_entities_filters` configuration
* Available filter keys depend on `entity_type` and can be queried via `.../selectable-entities/filters`
* When the form is sent, the entity is formatted for display in emails/results (either using `result_template` or a backend default label including ID)

**Example Configuration:**

```json
{
  "entity_type": "user",
  "selectable_entities_filters": {
    "role.department.id": {
      "in": "5"
    }
  },
  "representation": {
    "label_template": null,
    "result_template": null,
    "display": {
      "type": "select-modal",
      "config": null
    }
  }
}
```

**Example Submitted Value:**

When a form with an `EntitySelect` field is submitted, the value will be a single entity ID:

```json
{
  "field_id": "entity-field-1",
  "value": 42
}
```

**Example Formatted Output:**

When the form is sent, the entity is formatted for display in emails/results. With the default formatting (no `result_template`), for example:

```
Max Mustermann (Sales, ID: 42)
```

With a custom `result_template`:

```json
{
  "result_template": "{{selectableEntity | format_user_name}} - Email: {{selectableEntity.email}}"
}
```

Output:

```
Max Mustermann - Email: max@example.com
```

## EntitiesSelect

A field that allows users to select multiple entities from a specified entity type. This field type extends the EntitySelect functionality to support multiple selections.

**Key:** `entities-select`

**Configuration**

\| Key | Description | Type | Default | Required | Example | | -------------------------------- | -------------------------------------------------------------------------------------- | ------------ | -------------- | -------- | ------------------------------------------------------------------ | -------------------- | | `entity_type` | The type of entity that can be selected (e.g., 'user', 'department') | string | `null` | Yes | `user` | | `selectable_entities_filters` | Optional filters to pre-filter available entities (result-control style filter object) | object|null | `null` | No | `{"role.department.id": {"in": "5"}}` or `{"id": {"in": "11,12"}}` | | `representation` | Configuration for how entities are displayed and represented | object | (see below) | Yes | (see below) | | `representation.label_template` | Optional template string for field label display | string|null | `null` | No | `"Select users"` | | `representation.result_template` | Optional template string for displaying each selected entity in form results/emails | string|null | `null` | No | `"{{selectableEntity | format_user_name}}"` | | `representation.display` | Display configuration for the selection interface | object | (see below) | Yes | (see below) | | `representation.display.type` | The type of selection interface: `radio`, `select`, or `select-modal` | string | `select-modal` | Yes | `select` | | `representation.display.config` | Optional additional configuration for the display type | object|null | `null` | No | `{"inline": true}` (for radio type) |

**Behavior:**

* Users can select multiple entities from the available options
* The field value is submitted and stored as a comma-separated list of entity IDs
* Available entities can be filtered based on `selectable_entities_filters` configuration
* Available filter keys depend on `entity_type` and can be queried via `.../selectable-entities/filters`
* When the form is sent, each entity is formatted for display in emails/results (either using `result_template` or a backend default label including ID), then joined with line breaks (`<br>`)

**Example Configuration:**

```json
{
  "entity_type": "user",
  "selectable_entities_filters": {
    "role.department.id": {
      "in": "5"
    }
  },
  "representation": {
    "label_template": null,
    "result_template": null,
    "display": {
      "type": "select-modal",
      "config": null
    }
  }
}
```

**Example Submitted Value:**

When a form with an `EntitiesSelect` field is submitted, the value will be a comma-separated list of entity IDs:

```json
{
  "field_id": "entities-field-1",
  "value": "42,43,44"
}
```

**Example Formatted Output:**

When the form is sent, the entities are formatted for display in emails/results. With the default formatting (no `result_template`), for example:

```
Production (ID: 42)
HR (ID: 43)
Finance (ID: 44)
```

With a custom `result_template`:

```json
{
  "result_template": "{{selectableEntity.name}}"
}
```

Output:

```
IT, HR, Finance
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.intratool.de/api-reference/forms/form-field-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.