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

# User Availability

Retrieve user availability information from Teamleader Focus.

```php
Teamleader::userAvailability()
```

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

## Endpoints

* `userAvailability.daily`
* `userAvailability.total`

## 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) |

## Accepted values

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

| Constant     | Values                                                 |
| ------------ | ------------------------------------------------------ |
| `PARAM_KEYS` | `period`, `filter`, `page`, `page_size`, `page_number` |

## Methods

### `daily()`

```php
daily(array $params): array
```

Returns the daily availability for all users.

Maximum period duration: 100 days.

* `$params` — Request parameters - period (array, required): Period object with start\_date and end\_date (YYYY-MM-DD) - filter (array, optional): Filter object - assignees (array, optional): Array of assignee objects with type ('user'|'team') and id - page (array, optional): Pagination object with size (default: 20) and number (default: 1)

**Throws** `InvalidArgumentException`

### `total()`

```php
total(array $params): array
```

Returns the total availability for all users.

Maximum period duration: 20,000 days.

* `$params` — Request parameters - period (array, required): Period object with start\_date and end\_date (YYYY-MM-DD) - filter (array, optional): Filter object - assignees (array, optional): Array of assignee objects with type ('user'|'team') and id - page (array, optional): Pagination object with size (default: 20) and number (default: 1)

**Throws** `InvalidArgumentException`

### `dailyForUser()`

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

Convenience method: get daily availability for a specific user

* `$userId` — User UUID
* `$startDate` — Start date in YYYY-MM-DD format
* `$endDate` — End date in YYYY-MM-DD format
* `$options` — Additional options (page, etc.)

### `totalForUser()`

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

Convenience method: get total availability for a specific user

* `$userId` — User UUID
* `$startDate` — Start date in YYYY-MM-DD format
* `$endDate` — End date in YYYY-MM-DD format
* `$options` — Additional options (page, etc.)

### `dailyForTeam()`

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

Convenience method: get daily availability for a specific team

* `$teamId` — Team UUID
* `$startDate` — Start date in YYYY-MM-DD format
* `$endDate` — End date in YYYY-MM-DD format
* `$options` — Additional options (page, etc.)

### `totalForTeam()`

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

Convenience method: get total availability for a specific team

* `$teamId` — Team UUID
* `$startDate` — Start date in YYYY-MM-DD format
* `$endDate` — End date in YYYY-MM-DD format
* `$options` — Additional options (page, etc.)

### `list()`

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

Override list() — not supported for this resource

### `getResponseStructure()`

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

Get response structure documentation

## Examples

Get daily availability for all users over a date range:

```php
$availability = Teamleader::userAvailability()->daily([
    'period' => [
        'start_date' => '2024-01-01',
        'end_date'   => '2024-01-07',
    ],
]);
```

Get daily availability for specific users:

```php
$availability = Teamleader::userAvailability()->daily([
    'period' => [
        'start_date' => '2024-01-01',
        'end_date'   => '2024-01-07',
    ],
    'filter' => [
        'assignees' => [
            ['type' => 'user', 'id' => '66abace2-62af-0836-a927-fe3f44b9b47b'],
        ],
    ],
]);
```

Get daily availability with pagination:

```php
$availability = Teamleader::userAvailability()->daily([
    'period' => [
        'start_date' => '2024-01-01',
        'end_date'   => '2024-01-31',
    ],
    'page' => [
        'size'   => 50,
        'number' => 1,
    ],
]);
```

Get total availability for all users over a date range:

```php
$availability = Teamleader::userAvailability()->total([
    'period' => [
        'start_date' => '2024-01-01',
        'end_date'   => '2024-03-31',
    ],
]);
```

Get total availability for a specific team:

```php
$availability = Teamleader::userAvailability()->total([
    'period' => [
        'start_date' => '2024-01-01',
        'end_date'   => '2024-12-31',
    ],
    'filter' => [
        'assignees' => [
            ['type' => 'team', 'id' => 'team-uuid'],
        ],
    ],
]);
```