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

# Reservations

Manage planning reservations in Teamleader Focus.

```php
Teamleader::reservations()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Planning\Reservations`         |
| Create / update / delete | ✓ / ✓ / ✓                                                             |
| Pagination               | `page_size` / `page_number`; no totals — a short page is the last one |

## Endpoints

* `reservations.create`
* `reservations.delete`
* `reservations.list`
* `reservations.update`

## Filters

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

| Filter               | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `assignees`          | Filter by assignees (array of objects with type and id; pass null for unassigned) |
| `end_date`           | Filter reservations up to this date (YYYY-MM-DD)                                  |
| `plannable_item_ids` | Filter by array of plannable item UUIDs                                           |
| `project_ids`        | Filter by array of project UUIDs                                                  |
| `source_types`       | Filter by source types (array of SourceType strings)                              |
| `sources`            | Filter by sources (array of objects with id and type)                             |
| `start_date`         | Filter reservations from this date (YYYY-MM-DD)                                   |
| `term`               | Search term                                                                       |
| `work_type_ids`      | Filter by array of work type UUIDs                                                |

## Accepted values

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

| Constant         | Values                                                                 |
| ---------------- | ---------------------------------------------------------------------- |
| `CREATE_FIELDS`  | `plannable_item_id`, `date`, `duration`, `assignee`                    |
| `DURATION_UNITS` | `minutes`                                                              |
| `SOURCE_TYPES`   | `call`, `closingDay`, `dayOffType`, `externalEvent`, `meeting`, `task` |
| `UPDATE_FIELDS`  | `date`, `duration`, `assignee`                                         |

## Methods

### `list()`

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

List reservations with optional filters and pagination

* `$filters` — Filters to apply (plannable\_item\_ids, start\_date, end\_date, assignees, sources, source\_types)
* `$options` — Pagination options (page\_size, page\_number)

**Throws** `InvalidArgumentException`

### `create()`

```php
create(array $data): array
```

Create a new reservation

* `$data` — Reservation data - plannable\_item\_id (string, required): UUID of the plannable item - date (string, required): Date in YYYY-MM-DD format - duration (array, required): Object with 'value' (number) and 'unit' (string: 'minutes') - assignee (array, required): Object with 'type' ('user' or 'team') and 'id' (UUID)

**Throws** `InvalidArgumentException`

### `update()`

```php
update($id, array $data): array
```

Update an existing reservation

* `$id` — Reservation UUID
* `$data` — Data to update - date (string, optional): Date in YYYY-MM-DD format - duration (array, optional): Object with 'value' (number) and 'unit' (string: 'minutes') - assignee (array, optional): Object with 'type' ('user' or 'team') and 'id' (UUID)

**Throws** `InvalidArgumentException`

### `delete()`

```php
delete($id, ...$additionalParams): array
```

Delete a reservation

* `$id` — Reservation UUID
* `$additionalParams` — Unused — signature-compatible with parent

**Throws** `InvalidArgumentException`

### `forUser()`

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

Convenience method: get reservations for a specific user

* `$userId` — User UUID
* `$options` — Additional filters or pagination

### `forTeam()`

```php
forTeam(string $teamId, array $options = []): array
```

Convenience method: get reservations for a specific team

* `$teamId` — Team UUID
* `$options` — Additional filters or pagination

### `forDateRange()`

```php
forDateRange(string $startDate, string $endDate, array $options = []): array
```

Convenience method: get reservations for a date range

* `$startDate` — Start date in YYYY-MM-DD format
* `$endDate` — End date in YYYY-MM-DD format
* `$options` — Additional filters or pagination

### `unassigned()`

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

Convenience method: get unassigned reservations

* `$options` — Additional filters or pagination

### `getResponseStructure()`

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

Get response structure documentation

## Examples

Get all reservations:

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

Get reservations within a date range:

```php
$reservations = Teamleader::reservations()->list([
    'start_date' => '2024-01-01',
    'end_date'   => '2024-01-31',
]);
```

Get reservations for specific plannable items:

```php
$reservations = Teamleader::reservations()->list([
    'plannable_item_ids' => [
        '46156648-87c6-478d-8aa7-1dc3a00dacab',
    ],
]);
```

Get reservations for a specific user:

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

Get unassigned reservations (pass null in assignees):

```php
$reservations = Teamleader::reservations()->list([
    'assignees' => [null],
]);
```

Create a new reservation:

```php
$reservation = Teamleader::reservations()->create([
    'plannable_item_id' => '46156648-87c6-478d-8aa7-1dc3a00dacab',
    'date'              => '2024-01-12',
    'duration'          => [
        'value' => 60,
        'unit'  => 'minutes',
    ],
    'assignee' => [
        'type' => 'user',
        'id'   => '66abace2-62af-0836-a927-fe3f44b9b47b',
    ],
]);
```

Update an existing reservation:

```php
$result = Teamleader::reservations()->update('01878019-c72c-70dc-b097-7e519c775e35', [
    'date'     => '2024-01-15',
    'duration' => [
        'value' => 120,
        'unit'  => 'minutes',
    ],
]);
```

Delete a reservation:

```php
Teamleader::reservations()->delete('01878019-c72c-70dc-b097-7e519c775e35');
```