Timesheet

Unified view of all time-tracking records. Aggregates attendance check-ins and deliverable work sessions.

Read-only. Only GET /, GET /:id, GET /count, POST /count, POST /query, and POST /group-and-count are available.

Search columns: type, externalSync, externalSource

Fields

Field	Type	Notes
`id`	UUID	Auto-generated
`organizationId`	UUID	From API key
`startDate`	date	Session start (UTC)
`endDate`	date \| null	Session end; `null` = still open
`workerId`	UUID	Worker who performed the work; resolve via `worker`
`type`	string	See types below
`shopId`	UUID	Shop the session belongs to
`isEdited`	boolean	Whether manually edited
`lastUpdatedBy`	UUID \| null	User who last modified
`buildOrderId`	UUID \| null	Always `null` — retained in the schema but no longer populated by any row type
`overheadId`	UUID \| null	Always `null` — retained in the schema but no longer populated by any row type
`stageId`	UUID \| null	Always `null` — retained in the schema but no longer populated by any row type
`deliverableId`	UUID \| null	Populated only for `deliverable_work_session` records
`shiftWorkHours`	object \| null	Shift schedule (see below)
`externalSource`	string \| null	Source system, e.g. `"quickbase"`
`externalSync`	string	`"synced"` \| `"not synced"` \| `"none"`
`metadata`	object	Flexible key-value store (e.g. `costCode`, `unionCode`)
`createdAt`	date	Auto-generated
`updatedAt`	date	Auto-generated

`type` values

Only two row types exist today:

Value	Description	Populated FK
`attendance`	Attendance check-in/out record	(none)
`deliverable_work_session`	Time logged against a specific deliverable node	`deliverableId`

build_order_work_session and overhead_work_session row types (and the buildOrderId / overheadId / stageId foreign keys they used) have been removed server-side. buildOrderId, overheadId, and stageId remain in the response shape for backward compatibility but are always null. Order/stage/phase attribution for deliverable_work_session rows now goes exclusively through deliverableId — see the join example below.

`shiftWorkHours` shape

{
  "startTime": "08:00",
  "endTime": "17:00",
  "breaks": [{ "startTime": "12:00", "durationInSec": 1800 }]
}

Times are in HH:mm format. breaks is optional.

Example queries

# All open sessions (endDate is null)
GET /timesheet?endDate:isn=true

# Sessions for a specific worker in a date range
GET /timesheet?workerId=<uuid>&startDate:ge=2024-03-01&startDate:lt=2024-04-01

# Count by type
POST /timesheet/group-and-count
{ "groupByField": "type" }

# Unsynced deliverable sessions
GET /timesheet?type=deliverable_work_session&externalSync:ne=synced

Loading hours with Order / Stage / Phase attribution

For deliverable_work_session rows, the time is logged against a stage/phase/component node, and the only link to the build tree is deliverableId (buildOrderId and stageId are always null). To attribute each row to its Order, Stage and Phase, join the deliverable node and then chain further joins off it:

a join’s condition may reference another join’s alias (not just the base table), so you can hop timesheet → deliverable → order in a single request;
declare the joins in dependency order — the join you reference (here d) must come before the joins that depend on it (o, s).

curl "https://app.buildingswell.com/api/v2/timesheet?type=deliverable_work_session\
&startDate:ge=2024-03-01&startDate:lt=2024-04-01\
&join:deliverable%20as%20d:id,name,type,rootParentId,data,computed=deliverableId%20eq%20d.id\
&join:deliverable%20as%20o:id,name,identifier=o.id%20eq%20d.rootParentId\
&join:stage%20as%20s:id,name=s.id%20eq%20d.data.stageId" \
  -H "X-API-Key: <key>"

Each row comes back with:

o.name, o.identifier → the Order (joined via the node’s rootParentId)
s.name → the stage (joined via the node’s data.stageId)
d.computed.phase → the Phase name (read straight off the joined node)

The s join matches stage.id against data->>'stageId'; the engine casts both sides to uuid automatically. Phase/component nodes won’t have a linked stage, so s is null for those rows — read computed.phase for the phase regardless.

Alternative (no chaining): join only the deliverable node, read d.computed.phase directly, collect the distinct d.rootParentId / d.data.stageId values, and resolve their names with bulk POST /deliverable/query and POST /stage/query calls. Same result, more round-trips.

attendance rows have no build-tree attribution — deliverableId, buildOrderId, overheadId, and stageId are all null for them.

Getting started

Core concepts

Resources

Domain concepts

Examples

Fields

`type` values

`shiftWorkHours` shape

Example queries

Loading hours with Order / Stage / Phase attribution

​Fields

​type values

​shiftWorkHours shape

​Example queries

​Loading hours with Order / Stage / Phase attribution

Fields

`type` values

`shiftWorkHours` shape

Example queries

Loading hours with Order / Stage / Phase attribution