User Schedules

User Schedules

Retrieve per-day working schedules for one or more users in Teamleader Focus.

Overview

The User Schedules resource wraps the userSchedules.list endpoint. It returns the working schedule of one or more users, expanded per day over a date range of at most 7 days. Non-working days are omitted from each user's schedule.

This is the successor to users.getWeekSchedule (still available on the Users resource, but deprecated by Teamleader in favour of this endpoint).

Access via Teamleader::userSchedules().

Only available with the Weekly working schedule feature enabled on the Teamleader account.

Read-only. info(), create(), update() and delete() throw BadMethodCallException.

Date range max 7 days. until must be on or after from, and the inclusive range may span at most 7 days — otherwise InvalidArgumentException is thrown before the request.

Endpoint

userSchedules

Capabilities

Capability	Supported
Pagination	✅ Supported
Filtering	✅ Supported (required: user_ids, from, until)
Sorting	❌ Not supported
Sideloading	❌ Not supported
Creation	❌ Not supported
Update	❌ Not supported
Deletion	❌ Not supported

---

Methods

list(array $filters = [], array $options = [])

Returns the per-day working schedules of the requested users. All three filter keys are required and validated before the request.

Filters:

Filter	Type	Description
user_ids	array	Required. Non-empty array of user UUIDs
from	string	Required. Start date (inclusive), YYYY-MM-DD
until	string	Required. End date (inclusive), YYYY-MM-DD. On or after from; range may span at most 7 days

use McoreServices\TeamleaderSDK\Facades\Teamleader;

$schedules = Teamleader::userSchedules()->list([
    'user_ids' => ['user-uuid-1', 'user-uuid-2'],
    'from'     => '2026-06-01',
    'until'    => '2026-06-07',
]);

// With pagination
$schedules = Teamleader::userSchedules()->list(
    ['user_ids' => ['user-uuid'], 'from' => '2026-06-01', 'until' => '2026-06-07'],
    ['page_size' => 50, 'page_number' => 1]
);

---

Helper Methods

Method	Equivalent
forUser(string $userId, string $from, string $until, array $options = [])	list(['user_ids' => [$userId], ...])
forUsers(array $userIds, string $from, string $until, array $options = [])	list(['user_ids' => $userIds, ...])

$schedule  = Teamleader::userSchedules()->forUser('user-uuid', '2026-06-01', '2026-06-07');
$schedules = Teamleader::userSchedules()->forUsers(['u1', 'u2'], '2026-06-01', '2026-06-07');

---

Response Structure

[
    'data' => [
        [
            'user'     => ['type' => 'user', 'id' => 'user-uuid'],
            'schedule' => [
                [
                    'date'    => '2026-06-01',
                    'periods' => [
                        [
                            'type'  => 'working_hours',   // or 'lunch_break'
                            'start' => ['time' => '09:00'],
                            'end'   => ['time' => '17:00'],
                        ],
                    ],
                ],
                // ... one entry per working day in range (non-working days omitted)
            ],
        ],
    ],
]

Times are reported in the user's own time zone.

---

Error Handling

use InvalidArgumentException;

// Missing required filter
try {
    Teamleader::userSchedules()->list(['from' => '2026-06-01', 'until' => '2026-06-07']);
} catch (InvalidArgumentException $e) {
    // 'userSchedules.list requires a non-empty "user_ids" array.'
}

// Range too long
try {
    Teamleader::userSchedules()->forUser('user-uuid', '2026-06-01', '2026-06-30');
} catch (InvalidArgumentException $e) {
    // 'The date range may span at most 7 days.'
}

---

Related Resources

• Users — getWeekSchedule() (deprecated) and general user data
• User-Availability — planning capacity per user
• Reservations — planning reservations that consume availability