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

# Forms

## Introduction

The `Form` is the base component which needs to be configured to provide `Forms` to an [User](/api-reference/users.md).\
It keeps general information about the `Form` behaviour and settings.

Usually there is at least one [FormField](/api-reference/forms/form-fields.md) attached to a `Form`.

## Model Definition

**Alias**

`form`

**Relations**

| Relation                                              | Key            | Type       | Relation Field(s)                                  |
| ----------------------------------------------------- | -------------- | ---------- | -------------------------------------------------- |
| [User](/api-reference/users.md)                       | `user`         | Belongs to | `user_id`                                          |
| [Icon](/api-reference/icons.md)                       | `icon`         | Belongs to | `icon_id`                                          |
| [FormFields](/api-reference/forms/form-fields.md)     | `formFields`   | Has many   | `form_fields.form_id`                              |
| [FormMessages](/api-reference/forms/form-messages.md) | `formMessages` | Has many   | `form_messages.form_id`                            |
| [Layouts](/api-reference/layouts/layouts.md)          | `layouts`      | Has many   | `layouts.layoutable_type`, `layouts.layoutable_id` |

**Computed Properties**

* `hash` - The hashed `id` of the `Form`

**Traits**

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

## List

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

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "user_id": 6,
    "icon_id": 27,
    "folder_id": null,
    "name": "Form-1",
    "slug": "form-1",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": ["info@intratool.de"],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:18",
    "updated_at": "2019-01-24 14:04:48",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 2,
    "user_id": 2,
    "icon_id": 70,
    "folder_id": null,
    "name": "Form-2",
    "slug": "form-2",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": ["info@intratool.de"],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 2,
    "created_at": "2019-01-25 11:30:43",
    "updated_at": "2019-01-25 11:34:42",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## Show

Show a single `Form` by `id`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "user_id": 6,
  "icon_id": 27,
  "folder_id": null,
  "name": "Form-1",
  "slug": "form-1",
  "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
  "recipient": ["info@intratool.de"],
  "always_send_to_recipient": false,
  "has_personal_info": false,
  "user_confirmation_required": true,
  "request_receipt": false,
  "request_confirmation": false,
  "email_template": "{{ formMessage|format_form_field_results }}",
  "active": true,
  "sort_number": 1,
  "created_at": "2019-01-22 10:44:18",
  "updated_at": "2019-01-24 14:04:48",
  "grade_scale": null,
  "send_empty_fields": false,
  "send_description_fields": false,
  "hash": "zn7m24owk63qolxryge8pj05"
}
```

## Send

Send an existing `Form` by `id`.

By sending a `Form`, the [FormFieldValidations](/api-reference/forms/form-field-validations.md) are triggered. These [FormFieldValidations](/api-reference/forms/form-field-validations.md) ensure that the input of the [FormMessageFields](/api-reference/forms/form-message-fields.md) match the expected input for the used [FormFields](/api-reference/forms/form-fields.md).

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/forms/{id}/send`

**Request Keys**

| Key            | Type    | Default | Description        |
| -------------- | ------- | ------- | ------------------ |
| `form_id` \*\* | integer | -       | The related `Form` |

Keys with `*` are required.\
Keys with `**` are normalized to the information given by the route.

***

**Example Request**

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

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

```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "form_id": 4,
    "user_id": 2,
    "department_id": 1,
    "body": "",
    "subject": "\"Form-4\" wurde von intratool Service (intratool) übertragen",
    "updated_at": "2019-01-25 13:17:15",
    "created_at": "2019-01-25 13:17:15",
    "id": 2,
    "sent_at": "2019-01-25 13:17:15",
    "hash": "6o8m0kz5yw10x1pr9e4vxj27",
    "form": {
      "id": 4,
      "user_id": 2,
      "icon_id": 70,
      "folder_id": null,
      "name": "Form-4",
      "slug": "form-4",
      "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} übertragen",
      "recipient": ["info@intratool.de"],
      "always_send_to_recipient": false,
      "has_personal_info": false,
      "user_confirmation_required": true,
      "request_receipt": false,
      "request_confirmation": false,
      "email_template": "{{ formMessage|format_form_field_results }}",
      "active": true,
      "sort_number": 3,
      "created_at": "2019-01-25 13:16:09",
      "updated_at": "2019-01-25 13:16:11",
      "grade_scale": null,
      "send_empty_fields": false,
      "send_description_fields": false,
      "hash": "2w54q7xmvk1drl8ygeo96jrd",
      "form_fields": [
        {
          "id": 10,
          "form_id": 4,
          "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-25 13:16:09",
          "updated_at": "2019-01-25 13:16:09",
          "field_validation_string": "",
          "field_type": {
            "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"
          },
          "form": {
            "id": 4,
            "user_id": 2,
            "icon_id": 70,
            "folder_id": null,
            "name": "Form-4",
            "slug": "form-4",
            "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} übertragen",
            "recipient": ["info@intratool.de"],
            "always_send_to_recipient": false,
            "has_personal_info": false,
            "user_confirmation_required": true,
            "request_receipt": false,
            "request_confirmation": false,
            "email_template": "{{ formMessage|format_form_field_results }}",
            "active": true,
            "sort_number": 3,
            "created_at": "2019-01-25 13:16:09",
            "updated_at": "2019-01-25 13:16:11",
            "grade_scale": null,
            "send_empty_fields": false,
            "send_description_fields": false,
            "hash": "2w54q7xmvk1drl8ygeo96jrd"
          },
          "field_validations": []
        }
      ]
    },
    "form_message_fields": [
      {
        "form_message_id": 2,
        "form_field_id": 10,
        "value": "--",
        "request_value": null,
        "updated_at": "2019-01-25 13:17:15",
        "created_at": "2019-01-25 13:17:15",
        "id": 4,
        "form_field": {
          "id": 10,
          "form_id": 4,
          "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-25 13:16:09",
          "updated_at": "2019-01-25 13:16:09",
          "field_validation_string": "",
          "field_type": {
            "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"
          },
          "form": {
            "id": 4,
            "user_id": 2,
            "icon_id": 70,
            "folder_id": null,
            "name": "Form-4",
            "slug": "form-4",
            "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} übertragen",
            "recipient": ["info@intratool.de"],
            "always_send_to_recipient": false,
            "has_personal_info": false,
            "user_confirmation_required": true,
            "request_receipt": false,
            "request_confirmation": false,
            "email_template": "{{ formMessage|format_form_field_results }}",
            "active": true,
            "sort_number": 3,
            "created_at": "2019-01-25 13:16:09",
            "updated_at": "2019-01-25 13:16:11",
            "grade_scale": null,
            "send_empty_fields": false,
            "send_description_fields": false,
            "hash": "2w54q7xmvk1drl8ygeo96jrd"
          },
          "field_validations": []
        }
      }
    ],
    "user": {
      "id": 2,
      "username": "intratool",
      "first_name": "intratool",
      "last_name": "Service",
      "active": 1,
      "group_account": 0,
      "role_id": 1,
      "profile_picture": null,
      "street": null,
      "zipcode": null,
      "city": null,
      "email": null,
      "phone": null,
      "birthdate": null,
      "gender": null,
      "entering_date": null,
      "leaving_date": null,
      "staff_number": null,
      "wants_email_notifications": 1,
      "created_at": "2019-01-21 00:00:00",
      "updated_at": "2019-01-21 00:00:00",
      "deleted_at": null,
      "default_route": null,
      "full_name": "intratool Service"
    }
  }
}
```

## \[Adm.] List

Get a list of all `Forms`.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "user_id": 6,
    "icon_id": 27,
    "folder_id": null,
    "name": "Form-1",
    "slug": "form-1",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": ["info@intratool.de"],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:18",
    "updated_at": "2019-01-24 14:04:48",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "zn7m24owk63qolxryge8pj05"
  },
  {
    "id": 2,
    "user_id": 2,
    "icon_id": 70,
    "folder_id": null,
    "name": "Form-2",
    "slug": "form-2",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": ["info@intratool.de"],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 2,
    "created_at": "2019-01-25 11:30:43",
    "updated_at": "2019-01-25 11:34:42",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "6o8m0kz5yw10x1pr9e4vxj27"
  }
]
```

## \[Adm.] Create

Create a new `Form`.

**Definition**

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

**Request Keys**

| Key                          |   Type  |       Default      | Description                                                                                                                                                                                          |
| ---------------------------- | :-----: | :----------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon_id`                    | integer |        `70`        | The related [Icon](/api-reference/icons.md)                                                                                                                                                          |
| `name` \*                    |  string |          -         | The name of the `Form` (unique by all `Forms`)                                                                                                                                                       |
| `slug`                       |  string |   Slugged `name`   | The slugged `name` of the `Form` (unique by all `Forms`)                                                                                                                                             |
| `recipient` \*               |  email  |          -         | Array of the email address(es) to receive the [FormMessage](/api-reference/forms/form-messages.md) (separated by commas)                                                                             |
| `subject`                    |  string |    Default value   | The subject of the `Form` (supports [system variables](/introduction/system-variables.md))                                                                                                           |
| `email_template`             |  string |    Default value   | The template used to generate the [FormMessage](/api-reference/forms/form-messages.md) `body` (supports [system variables](/introduction/system-variables.md))                                       |
| `always_send_to_recipient`   | boolean |       `false`      | Whether to send the [FormMessage](/api-reference/forms/form-messages.md) also to the `recipient` when a `recipient-select` [FormField](/api-reference/forms/form-fields.md) is present in the `Form` |
| `send_empty_fields`          | boolean |       `false`      | Whether empty [FormMessageFields](/api-reference/forms/form-message-fields.md) should be present in the [FormMessage](/api-reference/forms/form-messages.md) `body`                                  |
| `send_description_fields`    | boolean |       `false`      | Whether `description` [FormFields](/api-reference/forms/form-fields.md) should be present in the [FormMessage](/api-reference/forms/form-messages.md) `body`                                         |
| `has_personal_information`   | boolean |       `false`      | Whether the [FormMessage](/api-reference/forms/form-messages.md) is shown to Group Accounts                                                                                                          |
| `user_confirmation_required` | boolean |       `true`       | Whether a confirmation of a specific [User](/api-reference/users.md) is required in Group Accounts                                                                                                   |
| `request_receipt`            | boolean |       `false`      | Whether the recipients of the [FormMessage](/api-reference/forms/form-messages.md) should confirm the receipt                                                                                        |
| `request_confirmation`       | boolean |       `false`      | Whether the recipients of the [FormMessage](/api-reference/forms/form-messages.md) should accept or decline the content                                                                              |
| `sort_number`                | integer | Current highest +1 | The index of the `Form`                                                                                                                                                                              |

Keys with `*` are required.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
```

## \[Adm.] Update

Update an existing `Form` by `id`.

**Definition**

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

**Request Keys**

| Key                          |   Type  | Description                                                                                                                                                                                          |
| ---------------------------- | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon_id`                    | integer | The related [Icon](/api-reference/icons.md)                                                                                                                                                          |
| `name` \*                    |  string | The name of the `Form` (unique by all `Forms`)                                                                                                                                                       |
| `slug`                       |  string | The slugged `name` of the `Form` (unique by all `Forms`)                                                                                                                                             |
| `recipient` \*               |  email  | Array of the email address(es) to receive the [FormMessage](/api-reference/forms/form-messages.md) (separated by commas)                                                                             |
| `subject`                    |  string | The subject of the `Form` (supports [system variables](/introduction/system-variables.md))                                                                                                           |
| `email_template`             |  string | The template used to generate the [FormMessage](/api-reference/forms/form-messages.md) `body` (supports [system variables](/introduction/system-variables.md))                                       |
| `always_send_to_recipient`   | boolean | Whether to send the [FormMessage](/api-reference/forms/form-messages.md) also to the `recipient` when a `recipient-select` [FormField](/api-reference/forms/form-fields.md) is present in the `Form` |
| `send_empty_fields`          | boolean | Whether empty [FormMessageFields](/api-reference/forms/form-message-fields.md) should be present in the [FormMessage](/api-reference/forms/form-messages.md) `body`                                  |
| `send_description_fields`    | boolean | Whether `description` [FormFields](/api-reference/forms/form-fields.md) should be present in the [FormMessage](/api-reference/forms/form-messages.md) `body`                                         |
| `has_personal_information`   | boolean | Whether the [FormMessage](/api-reference/forms/form-messages.md) is shown to Group Accounts                                                                                                          |
| `user_confirmation_required` | boolean | Whether a confirmation of a specific [User](/api-reference/users.md) is required in Group Accounts                                                                                                   |
| `request_receipt`            | boolean | Whether the recipients of the [FormMessage](/api-reference/forms/form-messages.md) should confirm the receipt                                                                                        |
| `request_confirmation`       | boolean | Whether the recipients of the [FormMessage](/api-reference/forms/form-messages.md) should accept or decline the content                                                                              |
| `sort_number`                | integer | The index of the `Form`                                                                                                                                                                              |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/forms/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'user_id' => '3',
        'name' => 'Form-1-changed',
        'recipient' => ['service@intratool.de']
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 6,
    "icon_id": 27,
    "folder_id": null,
    "name": "Form-1-changed",
    "slug": "form-1-changed",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": "service@intratool.de",
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:18",
    "updated_at": "2019-01-25 11:52:43",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "zn7m24owk63qolxryge8pj05",
    "icon": {
      "id": 27,
      "identifier": "nc-box",
      "title": "Box"
    }
  }
}
```

## \[Adm.] Delete

Delete an existing `Form` by `id`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/forms/{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/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 2,
    "icon_id": 70,
    "folder_id": null,
    "name": "Form-3",
    "slug": "form-3",
    "subject": "\"{{ form.name }}\" wurde von {{ formMessage.user|format_user_name }} \u00fcbertragen",
    "recipient": ["info@intratool.de"],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": true,
    "request_receipt": false,
    "request_confirmation": false,
    "email_template": "{{ formMessage|format_form_field_results }}",
    "active": true,
    "sort_number": 3,
    "created_at": "2019-01-25 11:53:56",
    "updated_at": "2019-01-25 11:54:00",
    "grade_scale": null,
    "send_empty_fields": false,
    "send_description_fields": false,
    "hash": "d54q7g6wnj1eylm8k9e0xpz2",
    "icon": {
      "id": 70,
      "identifier": "nc-list",
      "title": "Liste"
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/forms.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.