Work schedules
Define weekly work patterns, their compliance mode, and effective-dated assignments to employees over the v1 API.
A work schedule models the hours a company expects from an employee: how
many hours per day and at what time the day starts. It feeds two downstream
calculations — the expected hours used for balances, and the planned start
time used to flag late arrivals in presence. Schedules are
scoped by work_schedules:read / work_schedules:write under
https://api.factuarea.com/v1.
The weekly schedule
A weekly schedule carries a name, a week pattern of seven days — each day
a list of non-overlapping HH:MM–HH:MM ranges — a mode, and a status
(active / archived). The expected weekly hours and the planned start are
derived from the pattern.
The mode sets how compliance is measured:
| Mode | Meaning |
|---|---|
validated | The expected hours are taken as worked once validated — the schedule is the source of truth. |
real_clocking | Compliance is measured against the actual clock entries in the ledger. |
The default mode is validated.
| Operation | Endpoint |
|---|---|
| List / show | GET /v1/work-schedules, GET /v1/work-schedules/{schedule} |
| Create / update | POST /v1/work-schedules, PATCH /v1/work-schedules/{schedule} |
| Archive / unarchive | POST /v1/work-schedules/{schedule}/archive, .../unarchive |
| Stats | GET /v1/work-schedules/stats |
curl -X POST https://api.factuarea.com/v1/work-schedules \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Full-time 9 to 5",
"mode": "validated",
"week_pattern": {
"monday": [{ "start": "09:00", "end": "17:00" }],
"tuesday": [{ "start": "09:00", "end": "17:00" }],
"wednesday": [{ "start": "09:00", "end": "17:00" }],
"thursday": [{ "start": "09:00", "end": "17:00" }],
"friday": [{ "start": "09:00", "end": "17:00" }],
"saturday": [],
"sunday": []
}
}'A day with an empty list is a rest day. See the schemas in the API Reference.
Assignments
A schedule applies to an employee through an effective-dated assignment: an
effective_from (inclusive) and an optional effective_to (exclusive). Assigning
a new schedule to an employee closes the previous open assignment, so an
employee has one effective schedule at any date without gaps or overlaps.
| Operation | Endpoint | Effect |
|---|---|---|
| Assign | POST /v1/work-schedules/{schedule}/assign | Opens an assignment from effective_from, closing the previous one. |
| Unassign | POST /v1/work-schedules/{schedule}/unassign | Closes the employee's open assignment to this schedule. |
| List assignments | GET /v1/work-schedules/{schedule}/assignments | The employees currently assigned. |
| Resolve employee schedule | GET /v1/work-schedules/employee/{employee} | The schedule effective for an employee on a given date. |
curl -X POST https://api.factuarea.com/v1/work-schedules/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/assign \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
"effective_from": "2026-01-07"
}'GET /v1/work-schedules/employee/{employee} is the contract that balances and
presence consume: it returns the schedule in force for the employee on the
requested date, from which the expected hours and the planned start are read.
Assignments are date-ranged, not a single field on the employee. Reassigning a
schedule never rewrites history — the previous assignment is closed with an
effective_to, and the new one opens from its effective_from.
Typical flow
- Create a weekly schedule with its week pattern and mode.
- Assign it to employees from an
effective_fromdate. - Downstream, the schedule feeds the expected hours for balances and the planned start that presence uses to flag late arrivals.
- Unassign or reassign as contracts change; archive schedules you no longer use.
Next steps
- Presence — how the planned start powers late-arrival detection.
- Monthly close — where expected vs worked hours are reported.