Presence

Presence answers two live questions: who is working right now? and who is in the office and who is remote today? It is not a CRUD over a table of its own — it is a derived read-model composed from three sources: the employee roster, the clock state derived from the time-record ledger, and the schedule in force. The live work state (working, paused, finished, away) and the late-arrival flag are computed on read, never persisted.

Over the v1 API, presence is read-only (presence:read), under https://api.factuarea.com/v1. There is no presence:write scope: declaring office/remote presence is a portal-only task performed by the employee.

The live team panel

GET /v1/presence returns the live panel: one item per active employee with their current work state, since when the current shift has been open, and whether they arrived late against their scheduled start time, plus aggregate counters (working, paused, away, remote).

curl https://api.factuarea.com/v1/presence \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

The work state is derived from the last entry of each employee's open shift in the ledger: clock_in/pause_end → working, pause_start → paused, clock_out → finished, no open shift → away. Late arrival compares the first clock-in of the day against the planned start read from the employee's schedule.

Daily office/remote presence

GET /v1/presence/daily lists daily presence — office vs remote — with filters by employee, date or range and cursor pagination. GET /v1/presence/{employee} returns the presence of a single employee by their id (UUID v7); an employee of another company returns 404.

curl -G https://api.factuarea.com/v1/presence/daily \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "date=2026-02-03"

Daily presence (office or remote) is the one datum presence actually stores: one record per employee and day. Declaring it again for the same day changes the location rather than creating a duplicate. See the schemas in the API Reference.

Typical flow

1. Poll GET /v1/presence for a live dashboard of who is working, paused or away.
2. Read GET /v1/presence/daily to see the office/remote split for a date.
3. Drill into one person with GET /v1/presence/{employee}.

Because presence is derived, the numbers always reflect the current state of the ledger and schedules — you never need to keep a separate presence table in sync.

Next steps

• Time clock — the ledger the live state is derived from.
• Work schedules — the planned start the late-arrival flag uses.