> 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-fields.md).

# FormFields

## Introduction

`FormFields` are components of a [Form](/api-reference/forms/forms.md). They describe the input fields that are available in a specific [Form](/api-reference/forms/forms.md).

Further information about the `FormFields` behaviour is described by the [FormFieldType](/api-reference/forms/form-field-types.md) and attached [FormFieldValidations](/api-reference/forms/form-field-validations.md).

## Model Definition

**Alias**

`formField`

**Relations**

| Relation                                                               | Key             | Type            | Relation Field(s)                      |
| ---------------------------------------------------------------------- | --------------- | --------------- | -------------------------------------- |
| [Form](/api-reference/forms/forms.md)                                  | `form`          | Belongs to      | `form_id`                              |
| [FormFieldType](/api-reference/forms/form-field-types.md)              | `fieldType`     | Belongs to      | `form_field_type_id`                   |
| [FormFieldValidations](/api-reference/forms/form-field-validations.md) | `validations`   | Has many        | `form_field_validations.form_field_id` |
| [LayoutColumns](/api-reference/layouts/layout-columns.md)              | `layoutColumns` | Belongs to many | Intermediate table                     |

**Traits**

* [Restrictable](/introduction/entity-permissions/restricted-scope.md)
* `Sortable`
* `LayoutElement`

## List

Get a list of all `FormFields` the current authenticated [User](/api-reference/users.md) is allowed to view.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## List by Form

Get a list of all `FormFields` the current authenticated [User](/api-reference/users.md) is allowed to view by [Form](/api-reference/forms/forms.md).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/{formId}/fields`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## Show

Show a single `FormField` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 2,
  "form_id": 1,
  "form_type": "form",
  "form_field_type_id": "text",
  "name": "Field-1",
  "key": "field-1",
  "default_value": "",
  "placeholder": null,
  "description": null,
  "config": {},
  "sort_number": 1,
  "created_at": "2019-01-22 10:44:30",
  "updated_at": "2019-01-24 14:43:41",
  "field_validation_string": "",
  "field_validations": []
}
```

## \[Adm.] List

Get a list of all `FormFields`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/forms/fields`

**Example Request**

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

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

```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## \[Adm.] List referring to Forms

Get a list of all `FormFields` that refer to a [Form](/api-reference/forms/forms.md).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/forms/fields/form`

**Example Request**

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

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


```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 5,
    "form_id": 2,
    "form_type": "form",
    "form_field_type_id": "radio",
    "name": "Field-1",
    "key": "field-1",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {
      "options": {
        "option-1": "Option-1",
        "option-2": "Option-2",
        "option-3": "Option-3",
        "option-4": "Option-4"
      },
      "inline": false
    },
    "sort_number": 1,
    "created_at": "2019-01-25 11:30:43",
    "updated_at": "2019-01-25 11:30:43",
    "field_validation_string": "",
    "field_validations": []
  }
]
```

## \[Adm.] List referring to TaskTemplates

Get a list of all `FormFields` that refer to a [TaskTemplate](/api-reference/tasks-2/task-templates.md).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates/fields/`

**Example Request**

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

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


```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 6,
    "form_id": 3,
    "form_type": "taskTemplate",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2021-05-25 11:14:23",
    "updated_at": "2021-05-25 11:14:23",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 7,
    "form_id": 3,
    "form_type": "taskTemplate",
    "form_field_type_id": "radio",
    "name": "Field-2",
    "key": "field-2",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {
      "options": {
        "option-1": "Option-1",
        "option-2": "Option-2",
        "option-3": "Option-3",
        "option-4": "Option-4"
      },
      "inline": false
    },
    "sort_number": 1,
    "created_at": "2021-05-25 11:15:23",
    "updated_at": "2021-05-25 11:15:23",
    "field_validation_string": "",
    "field_validations": []
  }
]
```

## \[Adm.] Create

Create a new `FormField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields`

**Request Keys**

| Key                  |   Type  |                                  Default                                 | Description                                                                                                   |
| -------------------- | :-----: | :----------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------- |
| `form_id` \*         | integer |                                     -                                    | The related [Form](/api-reference/forms/forms.md) or [TaskTemplate](/api-reference/tasks-2/task-templates.md) |
| `form_type` \*       |  string |                                     -                                    | The `type` of the `Form` relation (either `form` or `task`)                                                   |
| `form_field_type_id` |  string |                                  `text`                                  | The related [FormFieldType](/api-reference/forms/form-field-types.md)                                         |
| `name` \*            |  string |                                     -                                    | The name of the `FormField` (unique by `Form`)                                                                |
| `key`                |  string |                              Slugged `name`                              | The key to identify the `FormField` (unique by `Form`)                                                        |
| `config`             |   json  | Default [FormFieldType](/api-reference/forms/form-field-types.md) config | The config that is used to setup the FormField                                                                |
| `default_value`      |  mixed  |                                  `null`                                  | The default value of the `FormField`                                                                          |
| `placeholder`        |  string |                                  `null`                                  | The placeholder of the `FormField`                                                                            |
| `description`        |  string |                                  `null`                                  | The description of the `FormField`                                                                            |

Keys with `*` are required.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/forms/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'form_id' => 2,
        'form_type' => 'form',
        'name' => 'Field-4'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "form_id": 2,
    "form_field_type_id": "text",
    "name": "Field-4",
    "key": "field-4",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 4,
    "form_type": "form",
    "updated_at": "2019-01-25 12:32:46",
    "created_at": "2019-01-25 12:32:46",
    "id": 9,
    "field_validation_string": "",
    "field_validations": []
  }
}
```

## \[Adm.] Update

Update an existing `FormField` by `id`.

**Definition**

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

**Request Keys**

| Key                  |  Type  | Description                                                           |
| -------------------- | :----: | --------------------------------------------------------------------- |
| `form_field_type_id` | string | The related [FormFieldType](/api-reference/forms/form-field-types.md) |
| `name`               | string | The name of the `FormField` (unique by `Form`)                        |
| `key`                | string | The key to identify the `FormField` (unique by `Form`)                |
| `config`             |  json  | The config that is used to setup the FormField                        |
| `default_value`      |  mixed | The default value of the `FormField`                                  |
| `placeholder`        | string | The placeholder of the `FormField`                                    |
| `description`        | string | The description of the `FormField`                                    |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/forms/fields/9', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'form_field_type_id' => 'rich-text'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 9,
    "form_id": 2,
    "form_type": "form",
    "form_field_type_id": "rich-text",
    "name": "Field-4",
    "key": "field-4",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 4,
    "created_at": "2019-01-25 12:32:46",
    "updated_at": "2019-01-25 12:45:49",
    "field_validation_string": "",
    "field_validations": []
  }
}
```

## \[Adm.] Delete

Delete an existing `FormField` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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

## Field entity select

These endpoints provide selectable and preselected entity data for `entity-select` and `entities-select` fields.

For field configuration details, see:

* [FormFieldTypes - EntitySelect](/api-reference/forms/form-field-types.md#entityselect)
* [FormFieldTypes - EntitiesSelect](/api-reference/forms/form-field-types.md#entitiesselect)

### Currently available filters by entity type

The available filters are resolved from backend `entity-preview` filter configuration and returned by `.../selectable-entities/filters`.

#### `user`

| Filter key           | Type           | Operators | Option filters           |
| -------------------- | -------------- | --------- | ------------------------ |
| `user_text_search`   | `text`         | `[]`      | -                        |
| `role.department.id` | `multi-select` | `[]`      | `department_text_search` |

#### `department`

| Filter key | Type           | Operators | Option filters               |
| ---------- | -------------- | --------- | ---------------------------- |
| `name`     | `text`         | `value`   | -                            |
| `tags.id`  | `multi-select` | `[]`      | `department_tag_text_search` |

### 1) Preselected entities

Returns preselected entities based on `default_value` of the field.

**User definition**

<mark style="color:yellow;">`POST`</mark> `/api/forms/fields/{formField}/preselected-entities`

**Administration definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields/{formField}/preselected-entities`

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/forms/fields/123/preselected-entities?per_page=10&page=1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "data": [
    {
      "id": 42,
      "title": "Max Mustermann",
      "url": "/users/42",
      "meta": {},
      "resolved_label_template": null,
      "sub_title": "max.mustermann",
      "description": null,
      "avatar": null,
      "tags": [],
      "filter_values": {},
      "additional_data": {}
    }
  ],
  "current_page": 1,
  "total": 1,
  "per_page": 10
}
```

### 2) Selectable entities

Returns selectable entities based on field config filters and optional request filters.

**User definition**

<mark style="color:yellow;">`POST`</mark> `/api/forms/fields/{formField}/selectable-entities`

**Administration definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields/{formField}/selectable-entities`

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/forms/fields/123/selectable-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'filter' => [
            'id' => [
                'in' => '11,12'
            ]
        ]
    ]
]);
```

**Example Response**

```json
{
  "data": [
    {
      "id": 11,
      "title": "Production",
      "url": null,
      "meta": {},
      "resolved_label_template": null,
      "sub_title": null,
      "description": null,
      "avatar": null,
      "tags": [],
      "filter_values": {},
      "additional_data": {}
    },
    {
      "id": 12,
      "title": "Sales",
      "url": null,
      "meta": {},
      "resolved_label_template": null,
      "sub_title": null,
      "description": null,
      "avatar": null,
      "tags": [],
      "filter_values": {},
      "additional_data": {}
    }
  ],
  "current_page": 1,
  "total": 2,
  "per_page": 15
}
```

### 3) Selectable-entity filters

Returns available filter definitions for selectable entities.

**User definition**

<mark style="color:yellow;">`POST`</mark> `/api/forms/fields/{formField}/selectable-entities/filters`

**Administration definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields/{formField}/selectable-entities/filters`

**Example Request**

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

**Example Response**

```json
{
  "data": [
    {
      "key": "user_text_search",
      "label": "Text search",
      "type": "text",
      "operators": []
    },
    {
      "key": "role.department.id",
      "label": "Department",
      "type": "multi-select",
      "operators": [],
      "options": {
        "values": [
          {
            "value": 3,
            "label": "Production",
            "additionalData": {}
          }
        ],
        "endpoint": "/api/forms/fields/123/selectable-entities/role.department.id/options",
        "filters": [
          {
            "key": "department_text_search",
            "label": "Text search",
            "type": "text",
            "operators": []
          }
        ],
        "meta": {
          "total": 1,
          "hasMore": false
        }
      }
    }
  ]
}
```

### 4) Selectable-entity filter options

Returns paginated options for one multi-select filter key.

**User definition**

<mark style="color:yellow;">`POST`</mark> `/api/forms/fields/{formField}/selectable-entities/{filterKey}/options`

**Administration definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields/{formField}/selectable-entities/{filterKey}/options`

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request(
    'POST',
    '/api/forms/fields/123/selectable-entities/role.department.id/options?per_page=5&page=2',
    ['headers' => ['Authorization' => "Bearer {accessToken}"]]
);
```

**Example Response**

```json
{
  "data": [
    {
      "value": 7,
      "label": "Production",
      "additionalData": {}
    },
    {
      "value": 8,
      "label": "Sales",
      "additionalData": {}
    }
  ],
  "total": 10,
  "per_page": 5,
  "current_page": 2,
  "last_page": 2
}
```