> For the complete documentation index, see [llms.txt](https://teamleader-sdk.mcore-services.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://teamleader-sdk.mcore-services.dev/api-reference/planning/plannable-items.md).

# Plannable Items

Retrieve plannable items from Teamleader Focus.

```php
Teamleader::plannableItems()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Planning\PlannableItems`       |
| Also available as        | `plannable_items()`                                                   |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `plannableItems.info`
* `plannableItems.list`

## Filters

Passed as the first argument to `list()`. Any other key throws.

| Filter                  | Description                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `assignees`             | Filter by assignees (list of \[type, id]; a null entry matches unassigned items)         |
| `completion_statuses`   | Filter by completion status: to\_do, done                                                |
| `end_date`              | Filter items up to this date (YYYY-MM-DD)                                                |
| `ids`                   | Filter by array of plannable item UUIDs                                                  |
| `planned_time_statuses` | Filter by planned time status: unplanned, partially\_planned, fully\_planned, overbooked |
| `project_ids`           | Filter by array of project UUIDs                                                         |
| `start_date`            | Filter items from this date (YYYY-MM-DD)                                                 |
| `term`                  | Search term (matches item title/name)                                                    |
| `types`                 | Filter by item type: closingDay, dayOffType, meeting, task, call, externalEvent          |
| `work_type_ids`         | Filter by array of work type UUIDs                                                       |

## Sorting

Pass `sort` (and optionally `sort_order`) in the options. Any other field throws.

| Field            | Description                         |
| ---------------- | ----------------------------------- |
| `end_date`       | Sort by end date                    |
| `id`             | Sort by plannable item ID (default) |
| `total_duration` | Sort by total duration              |

## Accepted values

Public constants on the class. Body fields and enum values outside these lists throw before the request is sent.

| Constant                | Values                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| `COMPLETION_STATUSES`   | `to_do`, `done`                                                        |
| `PLANNED_TIME_STATUSES` | `unplanned`, `partially_planned`, `fully_planned`, `overbooked`        |
| `TYPES`                 | `closingDay`, `dayOffType`, `meeting`, `task`, `call`, `externalEvent` |

## Methods

### `list()`

```php
list(array $filters = [], array $options = []): array
```

List plannable items with optional filters, sorting, and pagination

* `$filters` — Filters to apply
* `$options` — Pagination and sorting options - page\_size (int): Results per page (default: 20) - page\_number (int): Page number (default: 1) - sort (array): Array of sort objects with 'field' and 'order' keys

**Throws** `InvalidArgumentException`

### `info()`

```php
info($id, $includes = null): array
```

Get a single plannable item by its ID or by source

Either `id` or `source` must be provided. If the plannable item ID is unknown, use `source` with the underlying entity's type and ID.

* `$id` — Plannable item UUID, or null when looking up by source
* `$includes` — Unused — retained for base class signature compatibility

**Throws** `InvalidArgumentException`

### `infoBySource()`

```php
infoBySource(string $sourceType, string $sourceId): array
```

Get a single plannable item by its source entity type and ID

Use this when the plannable item's own ID is unknown but you have the underlying source entity (e.g. a task UUID).

* `$sourceType` — Type of the source entity (e.g. 'task')
* `$sourceId` — UUID of the source entity

**Throws** `InvalidArgumentException`

### `active()`

> **Deprecated** since v2.2.16 — plannableItems.list has no status filter. Until now this sent `status: [active]`, which the API ignored, so it returned every item; it still does, without the ignored filter, and raises E\_USER\_DEPRECATED once. Removed in v3.0.

```php
active(array $filters = [], array $options = []): array
```

### `ofTypes()`

```php
ofTypes(array $types, array $filters = [], array $options = []): array
```

Get plannable items of the given types

* `$types` — closingDay, dayOffType, meeting, task, call, externalEvent

### `unassigned()`

```php
unassigned(array $filters = [], array $options = []): array
```

Get plannable items nobody is assigned to

### `unplanned()`

```php
unplanned(array $filters = [], array $options = []): array
```

Convenience method: get unplanned plannable items

* `$filters` — Additional filters
* `$options` — Pagination and sorting options

### `overbooked()`

```php
overbooked(array $filters = [], array $options = []): array
```

Convenience method: get overbooked plannable items

* `$filters` — Additional filters
* `$options` — Pagination and sorting options

### `forProject()`

```php
forProject(string $projectId, array $filters = [], array $options = []): array
```

Convenience method: get plannable items for a specific project

* `$projectId` — Project UUID
* `$filters` — Additional filters
* `$options` — Pagination and sorting options

### `forUser()`

```php
forUser(string $userId, array $filters = [], array $options = []): array
```

Convenience method: get plannable items assigned to a specific user

* `$userId` — User UUID
* `$filters` — Additional filters
* `$options` — Pagination and sorting options

### `getResponseStructure()`

```php
getResponseStructure(): array
```

Get response structure documentation

## Examples

Get all plannable items:

```php
$items = Teamleader::plannableItems()->list();
```

Get only tasks and meetings:

```php
$items = Teamleader::plannableItems()->ofTypes(['task', 'meeting']);
```

Get plannable items for specific projects:

```php
$items = Teamleader::plannableItems()->list([
    'project_ids' => ['project-uuid-1', 'project-uuid-2'],
]);
```

Get items that have no planned time yet:

```php
$items = Teamleader::plannableItems()->list([
    'planned_time_statuses' => ['unplanned'],
]);
```

Get plannable items assigned to a specific user:

```php
$items = Teamleader::plannableItems()->list([
    'assignees' => [
        ['type' => 'user', 'id' => '66abace2-62af-0836-a927-fe3f44b9b47b'],
    ],
]);
```

Get plannable items sorted by end date ascending:

```php
$items = Teamleader::plannableItems()->list([], [
    'sort' => [['field' => 'end_date', 'order' => 'asc']],
]);
```

Get a single plannable item by its ID:

```php
$item = Teamleader::plannableItems()->info('018d79a1-2b99-7fbd-b323-500b01305371');
```

Get a plannable item by its source (when the plannable item ID is unknown):

```php
$item = Teamleader::plannableItems()->infoBySource('task', 'eab232c6-49b2-4b7e-a977-5e1148dad471');
```