> For the complete documentation index, see [llms.txt](https://api-docs.intratool.help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.intratool.help/api-reference/forms/forms.md).

# Forms

## Introduction

`Forms` define configurable questionnaires whose submissions create [FormMessages](/api-reference/forms/form-messages.md).

The `email_template` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format and the email editor's supported subset. Both `subject` and `email_template` accept validated [System Variable templates](/introduction/system-variables.md#rendered-templates).

## Model Definition

**Alias**

`form`

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Restrict who can view and submit a form.
* [Translations](/introduction/resource-capabilities/translations.md) - Localizes `name`, `subject`, and `email_template`; examples use `en-US`.
* [URL Context](/introduction/resource-capabilities/url-context.md) - Returns stable form URLs through URL-context requests.

**Relations**

| Key                 | Relation                                                  | Type       | Relation Field(s)                                  |
| ------------------- | --------------------------------------------------------- | ---------- | -------------------------------------------------- |
| `formFields`        | [FormFields](/api-reference/forms/form-fields.md)         | Has many   | `form_id`, `form_type`                             |
| `user`              | [User](/api-reference/users.md)                           | Belongs to | `user_id`                                          |
| `icon`              | [Icon](/api-reference/icons.md)                           | Belongs to | `icon_id`                                          |
| `folder`            | [Folder](/api-reference/folders.md)                       | Belongs to | `folder_id`                                        |
| `layouts`           | [Layouts](/api-reference/layouts/layouts.md)              | Morph many | `layouts.layoutable_type`, `layouts.layoutable_id` |
| `entityPermissions` | [EntityPermissions](/api-reference/entity-permissions.md) | Morph many | Target entity type and ID                          |

## List

List visible `Forms`.

**Definition**

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

**Request Keys**

| Key         | Type      | Default           | Description                          |
| ----------- | --------- | ----------------- | ------------------------------------ |
| `selects`   | `string`  | All fields        | Comma-separated fields to return.    |
| `relations` | `string`  | Default relations | Pipe-separated relations to include. |
| `limit`     | `integer` | No limit          | Maximum number of 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": 21,
    "user_id": 7,
    "lang_id": "en-US",
    "icon_id": 55,
    "folder_id": 9,
    "name": "Employee Feedback",
    "slug": "employee-feedback",
    "subject": "New employee feedback",
    "recipient": [
      "people@example.com"
    ],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": false,
    "request_receipt": false,
    "request_confirmation": false,
    "active": true,
    "sort_number": 1,
    "grade_mode": null,
    "grade_scale": null,
    "send_constraint_type": null,
    "send_empty_fields": false,
    "send_description_fields": true,
    "message_delete_interval": null,
    "message_hide_interval": null,
    "message_receipt_lifetime": null,
    "message_confirmation_lifetime": null,
    "hash": "jR"
  },
  {
    "id": 22,
    "user_id": 8,
    "lang_id": "en-US",
    "icon_id": 61,
    "folder_id": 12,
    "name": "Equipment Request",
    "slug": "equipment-request",
    "subject": "New equipment request",
    "recipient": [
      "it@example.com",
      "purchasing@example.com"
    ],
    "always_send_to_recipient": true,
    "has_personal_info": true,
    "user_confirmation_required": true,
    "request_receipt": true,
    "request_confirmation": true,
    "active": true,
    "sort_number": 2,
    "grade_mode": "scaled",
    "grade_scale": 100,
    "send_constraint_type": "once",
    "send_empty_fields": true,
    "send_description_fields": false,
    "message_delete_interval": "P2Y",
    "message_hide_interval": "P6M",
    "message_receipt_lifetime": "P5D",
    "message_confirmation_lifetime": "P1D",
    "hash": "kS"
  }
]
```

## Show

Show one visible `Form`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `form`    | `integer` | Form ID.    |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 21,
  "user_id": 7,
  "lang_id": "en-US",
  "icon_id": 55,
  "folder_id": 9,
  "name": "Employee Feedback",
  "slug": "employee-feedback",
  "subject": "New employee feedback",
  "recipient": [
    "people@example.com"
  ],
  "always_send_to_recipient": false,
  "has_personal_info": false,
  "user_confirmation_required": false,
  "request_receipt": false,
  "request_confirmation": false,
  "active": true,
  "sort_number": 1,
  "grade_mode": null,
  "grade_scale": null,
  "send_constraint_type": null,
  "send_empty_fields": false,
  "send_description_fields": true,
  "message_delete_interval": null,
  "message_hide_interval": null,
  "message_receipt_lifetime": null,
  "message_confirmation_lifetime": null,
  "hash": "jR"
}
```

## Send

Submit one `Form`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `form`    | `integer` | Form ID.    |

**Request Keys**

| Key               | Type     | Default         | Description                                    |
| ----------------- | -------- | --------------- | ---------------------------------------------- |
| `lang_id`         | `string` | System language | Language key. Use `en-US` for this example.    |
| `full-name`\*     | `string` | -               | Value for the required `full-name` text field. |
| `email-address`\* | `string` | -               | Value for the required email field.            |
| `message`\*       | `string` | -               | Value for the required message field.          |

Keys with `*` are required by the configured fields in this example form.

**Behavior**

Request keys for field values are the fields' `key` values. The example supplies every value used to generate the returned message body.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/forms/21/send', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'lang_id' => 'en-US',
        'full-name' => 'Ada Lovelace',
        'email-address' => 'ada@example.com',
        'message' => 'I would like more mentoring sessions.'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 140,
    "user_id": 7,
    "group_account_user_id": null,
    "department_id": 6,
    "form_id": 21,
    "lang_id": "en-US",
    "subject": "New employee feedback",
    "body": "<p><strong>Full name:</strong> Ada Lovelace</p><p><strong>Email address:</strong> ada@example.com</p><p><strong>Message:</strong> I would like more mentoring sessions.</p>",
    "sent_from_public": false,
    "distribution_success": true,
    "hash": "mN"
  }
}
```

## Admin: List

List all `Forms` in administration scope.

**Definition**

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

**Request Keys**

| Key         | Type      | Default           | Description                          |
| ----------- | --------- | ----------------- | ------------------------------------ |
| `selects`   | `string`  | All fields        | Comma-separated fields to return.    |
| `relations` | `string`  | Default relations | Pipe-separated relations to include. |
| `limit`     | `integer` | No limit          | Maximum number of forms.             |

**Behavior**

Administration results include inactive and soft-deleted forms when permitted.

**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": 21,
    "user_id": 7,
    "lang_id": "en-US",
    "icon_id": 55,
    "folder_id": 9,
    "name": "Employee Feedback",
    "slug": "employee-feedback",
    "subject": "New employee feedback",
    "recipient": [
      "people@example.com"
    ],
    "always_send_to_recipient": false,
    "has_personal_info": false,
    "user_confirmation_required": false,
    "request_receipt": false,
    "request_confirmation": false,
    "active": true,
    "sort_number": 1,
    "grade_mode": null,
    "grade_scale": null,
    "send_constraint_type": null,
    "send_empty_fields": false,
    "send_description_fields": true,
    "message_delete_interval": null,
    "message_hide_interval": null,
    "message_receipt_lifetime": null,
    "message_confirmation_lifetime": null,
    "hash": "jR"
  },
  {
    "id": 22,
    "user_id": 8,
    "lang_id": "en-US",
    "icon_id": 61,
    "folder_id": 12,
    "name": "Equipment Request",
    "slug": "equipment-request",
    "subject": "New equipment request",
    "recipient": [
      "it@example.com",
      "purchasing@example.com"
    ],
    "always_send_to_recipient": true,
    "has_personal_info": true,
    "user_confirmation_required": true,
    "request_receipt": true,
    "request_confirmation": true,
    "active": false,
    "sort_number": 2,
    "grade_mode": "scaled",
    "grade_scale": 100,
    "send_constraint_type": "once",
    "send_empty_fields": true,
    "send_description_fields": false,
    "message_delete_interval": "P2Y",
    "message_hide_interval": "P6M",
    "message_receipt_lifetime": "P5D",
    "message_confirmation_lifetime": "P1D",
    "hash": "kS",
    "deleted_at": "2026-08-01 08:00:00"
  }
]
```

## Admin: Show

Show one `Form` in administration scope.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `form`    | `integer` | Form ID.    |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 22,
  "user_id": 8,
  "lang_id": "en-US",
  "icon_id": 61,
  "folder_id": 12,
  "name": "Equipment Request",
  "slug": "equipment-request",
  "subject": "New equipment request",
  "recipient": [
    "it@example.com",
    "purchasing@example.com"
  ],
  "always_send_to_recipient": true,
  "has_personal_info": true,
  "user_confirmation_required": true,
  "request_receipt": true,
  "request_confirmation": true,
  "active": true,
  "sort_number": 2,
  "grade_mode": "scaled",
  "grade_scale": 100,
  "send_constraint_type": "once",
  "send_empty_fields": true,
  "send_description_fields": false,
  "message_delete_interval": "P2Y",
  "message_hide_interval": "P6M",
  "message_receipt_lifetime": "P5D",
  "message_confirmation_lifetime": "P1D",
  "hash": "kS"
}
```

## Admin: Create

Create a new `Form`.

**Definition**

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

**Request Keys**

| Key                             | Type                          | Default                          | Description                                                                                                         |
| ------------------------------- | ----------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`\*                        | `string`                      | -                                | Unique form name.                                                                                                   |
| `slug`\*                        | `string`                      | Generated from name when omitted | Unique URL slug.                                                                                                    |
| `subject`\*                     | `string`                      | Localized default                | Message subject using a validated [System Variable template](/introduction/system-variables.md#rendered-templates). |
| `email_template`\*              | `string`                      | Localized default                | HTML email using a validated [System Variable template](/introduction/system-variables.md#rendered-templates).      |
| `lang_id`                       | `string`                      | System language                  | Language key. Use `en-US` for this example.                                                                         |
| `icon_id`                       | `integer` \| `null`           | Form icon                        | Icon ID.                                                                                                            |
| `recipient`                     | `array` \| `null`             | `null`                           | One address per element, following the shared [Email Addresses](/introduction/validation.md#email-addresses) rules. |
| `always_send_to_recipient`      | `boolean`                     | `false`                          | Send to configured recipients in addition to field recipients.                                                      |
| `has_personal_info`             | `boolean`                     | `false`                          | Whether the form collects personal information.                                                                     |
| `user_confirmation_required`    | `boolean`                     | `false`                          | Require the user to confirm before submission.                                                                      |
| `request_receipt`               | `boolean`                     | `false`                          | Request receipt confirmation.                                                                                       |
| `request_confirmation`          | `boolean`                     | `false`                          | Request an approval decision.                                                                                       |
| `message_receipt_lifetime`      | `ISO 8601 duration` \| `null` | `P1M` when enabled               | Receipt token lifetime.                                                                                             |
| `message_confirmation_lifetime` | `ISO 8601 duration` \| `null` | `P1D` when enabled               | Approval token lifetime.                                                                                            |
| `grade_mode`                    | `string` \| `null`            | `null`                           | Grade mode; scaled mode requires `grade_scale`.                                                                     |
| `grade_scale`                   | `integer` \| `null`           | `null`                           | Scale used by scaled grading.                                                                                       |
| `send_constraint_type`          | `string` \| `null`            | `null`                           | Optional send constraint.                                                                                           |
| `send_empty_fields`             | `boolean`                     | `false`                          | Include empty fields in output.                                                                                     |
| `send_description_fields`       | `boolean`                     | `false`                          | Include description fields in output.                                                                               |
| `active`                        | `boolean`                     | `true`                           | Whether users may submit the form.                                                                                  |
| `sort_number`                   | `integer`                     | Auto                             | Display order.                                                                                                      |
| `entity_permissions`            | `object`                      | Unrestricted                     | [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md).                                    |

Keys with `*` are required after server defaults are applied.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/forms', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Equipment Request',
        'slug' => 'equipment-request',
        'subject' => 'New equipment request',
        'email_template' => '<p>A new equipment request was submitted.</p>',
        'lang_id' => 'en-US',
        'recipient' => ['it@example.com', 'purchasing@example.com'],
        'always_send_to_recipient' => true,
        'has_personal_info' => true,
        'user_confirmation_required' => true,
        'request_receipt' => true,
        'request_confirmation' => true,
        'message_receipt_lifetime' => 'P5D',
        'message_confirmation_lifetime' => 'P1D',
        'grade_mode' => 'scaled',
        'grade_scale' => 100,
        'send_constraint_type' => 'once',
        'send_empty_fields' => true,
        'send_description_fields' => false,
        'active' => true,
        'sort_number' => 2
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 22,
    "user_id": 8,
    "lang_id": "en-US",
    "icon_id": 61,
    "folder_id": 12,
    "name": "Equipment Request",
    "slug": "equipment-request",
    "subject": "New equipment request",
    "recipient": [
      "it@example.com",
      "purchasing@example.com"
    ],
    "always_send_to_recipient": true,
    "has_personal_info": true,
    "user_confirmation_required": true,
    "request_receipt": true,
    "request_confirmation": true,
    "active": true,
    "sort_number": 2,
    "grade_mode": "scaled",
    "grade_scale": 100,
    "send_constraint_type": "once",
    "send_empty_fields": true,
    "send_description_fields": false,
    "message_delete_interval": "P2Y",
    "message_hide_interval": "P6M",
    "message_receipt_lifetime": "P5D",
    "message_confirmation_lifetime": "P1D",
    "hash": "kS"
  }
}
```

## Admin: Update

Update an existing `Form`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `form`    | `integer` | Form ID.    |

**Request Keys**

| Key                             | Type                          | Default                     | Description                                                                                                         |
| ------------------------------- | ----------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`                          | `string`                      | Current value               | Unique form name.                                                                                                   |
| `slug`                          | `string`                      | Generated from changed name | Unique URL slug.                                                                                                    |
| `subject`                       | `string`                      | Current value               | Message subject using a validated [System Variable template](/introduction/system-variables.md#rendered-templates). |
| `email_template`                | `string`                      | Current value               | HTML email using a validated [System Variable template](/introduction/system-variables.md#rendered-templates).      |
| `lang_id`                       | `string`                      | Current value               | Language key.                                                                                                       |
| `recipient`                     | `array` \| `null`             | Current value               | One address per element, following the shared [Email Addresses](/introduction/validation.md#email-addresses) rules. |
| `request_receipt`               | `boolean`                     | Current value               | Request receipt confirmation.                                                                                       |
| `request_confirmation`          | `boolean`                     | Current value               | Request an approval decision.                                                                                       |
| `message_receipt_lifetime`      | `ISO 8601 duration` \| `null` | `P5D` when enabled          | Receipt token lifetime.                                                                                             |
| `message_confirmation_lifetime` | `ISO 8601 duration` \| `null` | `P1D` when enabled          | Approval token lifetime.                                                                                            |
| `active`                        | `boolean`                     | Current value               | Whether users may submit the form.                                                                                  |
| `entity_permissions`            | `object`                      | Current value               | Updated [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md).                            |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/forms/22', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'IT Equipment Request',
        'slug' => 'it-equipment-request',
        'lang_id' => 'en-US',
        'recipient' => ['it@example.com'],
        'request_receipt' => true,
        'message_receipt_lifetime' => 'P7D',
        'active' => true
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 22,
    "user_id": 8,
    "lang_id": "en-US",
    "icon_id": 61,
    "folder_id": 12,
    "name": "IT Equipment Request",
    "slug": "it-equipment-request",
    "subject": "New equipment request",
    "recipient": [
      "it@example.com"
    ],
    "always_send_to_recipient": true,
    "has_personal_info": true,
    "user_confirmation_required": true,
    "request_receipt": true,
    "request_confirmation": true,
    "active": true,
    "sort_number": 2,
    "grade_mode": "scaled",
    "grade_scale": 100,
    "send_constraint_type": "once",
    "send_empty_fields": true,
    "send_description_fields": false,
    "message_delete_interval": "P2Y",
    "message_hide_interval": "P6M",
    "message_receipt_lifetime": "P7D",
    "message_confirmation_lifetime": "P1D",
    "hash": "kS"
  }
}
```

## Admin: Delete

Delete an existing `Form`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `form`    | `integer` | Form 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/22', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

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