> 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/tasks-2/task-assignments.md).

# TaskAssignments

## Introduction

`TaskAssignments` define when and for whom tasks should be executed.

Assignment data and related [TaskTemplates](/api-reference/tasks-2/task-templates.md) are used to create [TaskExecutions](/api-reference/tasks-2/task-executions.md) for users and departments.

The `description` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format.

## Model Definition

**Alias**

`taskAssignment`

**Relations**

| Key                       | Relation                                                                        | Type            | Relation Field(s)                    |
| ------------------------- | ------------------------------------------------------------------------------- | --------------- | ------------------------------------ |
| `taskTemplate`            | [TaskTemplate](/api-reference/tasks-2/task-templates.md)                        | Belongs to      | `task_template_id`                   |
| `taskTemplateComposition` | [TaskTemplateComposition](/api-reference/tasks-2/task-template-compositions.md) | Belongs to      | `task_template_composition_id`       |
| `children`                | [TaskAssignments](/api-reference/tasks-2/task-assignments.md)                   | Has many        | `parent_id`                          |
| `departments`             | [Departments](/api-reference/departments.md)                                    | Belongs to many | Intermediate table                   |
| `users`                   | [Users](/api-reference/users.md)                                                | Belongs to many | Intermediate table                   |
| `creator`                 | [User](/api-reference/users.md)                                                 | Belongs to      | `creator_user_id`                    |
| `taskExecutions`          | [TaskExecutions](/api-reference/tasks-2/task-executions.md)                     | Has many        | `task_executions.task_assignment_id` |

**Capabilities**

* [Targetables](/introduction/resource-capabilities/targetables.md) - `assign_mode`, `user_ids`, and `department_ids` determine who receives executions; child assignments can inherit their parent's targets.
* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Direct grants participate in administration access together with ownership and module permissions.
* [Translations](/introduction/resource-capabilities/translations.md) - The `title` and `description` fields are translatable.

## Admin: List

List all `TaskAssignments` in administration scope.

**Definition**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 80,
    "lang_id": "en-US",
    "title": "Morning Shift",
    "task_template_id": 31,
    "assign_mode": "any_of",
    "active": true
  },
  {
    "id": 81,
    "lang_id": "en-US",
    "title": "Weekly Equipment Review",
    "task_template_composition_id": 12,
    "task_template_id": null,
    "assign_mode": "one_of_user",
    "always_executable": false,
    "active": true
  }
]
```

## List

List assignments relevant to the authenticated user.

**Definition**

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

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 80,
    "lang_id": "en-US",
    "title": "Morning Shift",
    "task_template_id": 31,
    "assign_mode": "any_of",
    "start_date": "2026-08-07 00:00:00",
    "always_executable": false
  },
  {
    "id": 82,
    "lang_id": "en-US",
    "title": "Incident Follow-up",
    "task_template_id": 32,
    "assign_mode": "one_of_user",
    "start_date": null,
    "always_executable": true
  }
]
```

## List Always-Executable Assignments

List assignments the authenticated user may execute without a time window.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/assignments/always-executable`

**Behavior**

* The result is restricted to assignments relevant for the authenticated user and allowed by the always-executable assignment permission strategy.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 82,
    "lang_id": "en-US",
    "title": "Incident Follow-up",
    "task_template_id": 32,
    "assign_mode": "one_of_user",
    "always_executable": true
  },
  {
    "id": 83,
    "lang_id": "en-US",
    "title": "Unscheduled Safety Report",
    "task_template_id": 33,
    "assign_mode": "all_users",
    "always_executable": true
  }
]
```

## Admin: Show

Show one `TaskAssignment` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/assignments/{taskAssignment}`

**Route Parameters**

| Parameter        | Type      | Description       |
| ---------------- | --------- | ----------------- |
| `taskAssignment` | `integer` | TaskAssignment ID |

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 80,
  "lang_id": "en-US",
  "title": "Morning Shift",
  "task_template_id": 31,
  "assign_mode": "any_of",
  "active": true,
  "reset_allowed": true
}
```

## Admin: Create

Create a new `TaskAssignment`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/assignments`

**Request Keys**

| Key                            | Type                | Default         | Description                                                                                                                      |
| ------------------------------ | ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `title`\*                      | `string`            | -               | Assignment title.                                                                                                                |
| `description`                  | `string`            | `null`          | Assignment description (HTML).                                                                                                   |
| `lang_id`                      | `string`            | system language | Language key.                                                                                                                    |
| `folder_id`                    | `integer` \| `null` | `null`          | Related [Folder](/api-reference/folders.md) ID.                                                                                  |
| `parent_id`                    | `integer` \| `null` | `null`          | Parent composition assignment ID.                                                                                                |
| `inherit_parent_values`        | `boolean`           | `false`         | Inherit timing and targeting from the parent assignment.                                                                         |
| `task_template_id`             | `integer` \| `null` | `null`          | Related [TaskTemplate](/api-reference/tasks-2/task-templates.md) ID.                                                             |
| `task_template_composition_id` | `integer` \| `null` | `null`          | Related [TaskTemplateComposition](/api-reference/tasks-2/task-template-compositions.md) ID; required without `task_template_id`. |
| `assign_mode`                  | `string` \| `null`  | `all`           | Selects one of the shared [Assignment Modes](/introduction/assignment-and-targeting.md#assignment-modes).                        |
| `start_date`                   | `date`              | `null`          | Start date (`YYYY-MM-DD`).                                                                                                       |
| `start_time`                   | `time`              | `null`          | Start time (`H:i:s`).                                                                                                            |
| `show_before_interval`         | `interval`          | `null`          | Visibility lead interval (ISO 8601 duration).                                                                                    |
| `executable_before_interval`   | `interval`          | `null`          | Executable-before interval (ISO 8601 duration).                                                                                  |
| `executable_after_interval`    | `interval`          | `null`          | Executable-after interval (ISO 8601 duration).                                                                                   |
| `interval`                     | `string`            | `null`          | iCal RRULE.                                                                                                                      |
| `interval_end`                 | `date`              | `null`          | End date for recurrence.                                                                                                         |
| `active`                       | `boolean`           | `true`          | Active state.                                                                                                                    |
| `always_executable`            | `boolean`           | `false`         | Allows execution without time restrictions.                                                                                      |
| `user_confirmation_required`   | `boolean`           | `true`          | Requires real-user confirmation.                                                                                                 |
| `delayed_reason_required`      | `boolean`           | `true`          | Requires delayed reason for delayed finish.                                                                                      |
| `deny_reason_required`         | `boolean`           | `true`          | Requires deny reason on deny action.                                                                                             |
| `reset_allowed`                | `boolean`           | `true`          | Allows reset action for related executions.                                                                                      |
| `sort_number`                  | `integer`           | auto            | Sort number.                                                                                                                     |
| `department_ids`               | `array`             | `[]`            | Target departments.                                                                                                              |
| `user_ids`                     | `array`             | `[]`            | Target users.                                                                                                                    |
| `entity_permissions`           | `object[]`          | `[]`            | Direct [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md).                                          |

Keys with `*` are required. A root assignment must provide either `task_template_id` or `task_template_composition_id`.

**Behavior**

* `creator_user_id`, `revision_id`, `dispatched_by_system`, and the root assignment's `quick_assignment` value are controlled by the backend.
* User targets take precedence over department targets during creation when both arrays are non-empty.
* Timing and recurrence values are cleared when `start_date` is absent or `always_executable` is `true`.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/tasks-2/assignments', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Morning Shift',
        'task_template_id' => 31,
        'lang_id' => 'en-US',
        'assign_mode' => 'any_of',
        'active' => true,
        'reset_allowed' => true,
        'user_ids' => [144]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 80,
    "creator_user_id": 144,
    "lang_id": "en-US",
    "title": "Morning Shift",
    "task_template_id": 31,
    "assign_mode": "any_of",
    "active": true,
    "reset_allowed": true
  }
}
```

## Create Quick Assignment

Create a quick `TaskAssignment` for the current authenticated user.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/assignments/quick-assignment`

**Request Keys**

| Key                  | Type       | Default         | Description                                                                             |
| -------------------- | ---------- | --------------- | --------------------------------------------------------------------------------------- |
| `title`\*            | `string`   | -               | Assignment title.                                                                       |
| `task_template_id`\* | `integer`  | -               | Related quick-assignable [TaskTemplate](/api-reference/tasks-2/task-templates.md).      |
| `lang_id`            | `string`   | system language | Language key.                                                                           |
| `start_date`\*       | `date`     | -               | Start date.                                                                             |
| `start_time`\*       | `time`     | -               | Start time in `H:i:s` format.                                                           |
| `department_ids`     | `array`    | `[]`            | Target departments.                                                                     |
| `user_ids`           | `array`    | `[]`            | Target users.                                                                           |
| `entity_permissions` | `object[]` | `[]`            | Direct [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md). |

Keys with `*` are required.

**Behavior**

* The endpoint forces `quick_assignment` and `active` to `true`, disables recurrence, and derives `assign_mode` from the retained user or department targets.
* Target IDs the authenticated user may not quick-assign are removed before validation.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/assignments/quick-assignment', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Quick Safety Check',
        'task_template_id' => 31,
        'lang_id' => 'en-US',
        'start_date' => '2026-08-07',
        'start_time' => '09:00:00',
        'user_ids' => [144]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 81,
    "creator_user_id": 144,
    "lang_id": "en-US",
    "title": "Quick Safety Check",
    "task_template_id": 31,
    "quick_assignment": true,
    "start_date": "2026-08-07 00:00:00",
    "start_time": "09:00:00",
    "assign_mode": "one_of"
  }
}
```

## Admin: Update

Update an existing `TaskAssignment`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/tasks-2/assignments/{taskAssignment}`

**Route Parameters**

| Parameter        | Type      | Description        |
| ---------------- | --------- | ------------------ |
| `taskAssignment` | `integer` | TaskAssignment ID. |

**Request Keys**

| Key                            | Type                 | Description                                              |
| ------------------------------ | -------------------- | -------------------------------------------------------- |
| `title`                        | `string` \| `null`   | New assignment title.                                    |
| `description`                  | `string` \| `null`   | New HTML description.                                    |
| `lang_id`                      | `string`             | New language key.                                        |
| `folder_id`                    | `integer` \| `null`  | New related Folder ID.                                   |
| `parent_id`                    | `integer` \| `null`  | New parent composition assignment ID.                    |
| `inherit_parent_values`        | `boolean`            | Whether values are inherited from the parent assignment. |
| `task_template_id`             | `integer` \| `null`  | New TaskTemplate ID.                                     |
| `task_template_composition_id` | `integer` \| `null`  | New TaskTemplateComposition ID.                          |
| `assign_mode`                  | `string` \| `null`   | New assignment mode.                                     |
| `start_date`                   | `date` \| `null`     | New start date.                                          |
| `start_time`                   | `time` \| `null`     | New start time.                                          |
| `show_before_interval`         | `interval` \| `null` | New visibility interval.                                 |
| `executable_before_interval`   | `interval` \| `null` | New executable-before interval.                          |
| `executable_after_interval`    | `interval` \| `null` | New executable-after interval.                           |
| `interval`                     | `string` \| `null`   | New RRULE.                                               |
| `interval_end`                 | `date` \| `null`     | New recurrence end date.                                 |
| `active`                       | `boolean`            | New active state.                                        |
| `always_executable`            | `boolean` \| `null`  | New always-executable state.                             |
| `user_confirmation_required`   | `boolean` \| `null`  | New confirmation requirement.                            |
| `delayed_reason_required`      | `boolean` \| `null`  | New delayed-reason requirement.                          |
| `deny_reason_required`         | `boolean` \| `null`  | New deny-reason requirement.                             |
| `reset_allowed`                | `boolean` \| `null`  | New reset-allowed state.                                 |
| `sort_number`                  | `integer`            | New sort number.                                         |
| `department_ids`               | `array`              | Updated target departments.                              |
| `user_ids`                     | `array`              | Updated target users.                                    |
| `entity_permissions`           | `object[]`           | Updated direct Entity Permissions.                       |

**Behavior**

* `revision_id`, `creator_user_id`, `dispatched_by_system`, and `quick_assignment` cannot be set by the client.
* A changed template, composition, timing, recurrence, active state, assignment mode, inheritance setting, or removed target creates a new assignment revision and soft-deletes the previous record. Adding targets alone does not create a revision.
* An assignment cannot be activated beneath an inactive parent. Timing and recurrence values are cleared when `start_date` is cleared or `always_executable` becomes `true`.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/tasks-2/assignments/80', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Morning Shift (updated)',
        'reset_allowed' => false
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 80,
    "lang_id": "en-US",
    "title": "Morning Shift (updated)",
    "reset_allowed": false
  }
}
```

## Admin: Delete

Delete an existing `TaskAssignment`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/tasks-2/assignments/{taskAssignment}`

**Route Parameters**

| Parameter        | Type      | Description       |
| ---------------- | --------- | ----------------- |
| `taskAssignment` | `integer` | TaskAssignment ID |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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