Examples

Every example uses app.buildingswell.com. Swap in your own host if you are pointed somewhere else.

Reading data

List projects

curl "https://app.buildingswell.com/api/v2/project?page=1&pageSize=20" \
  -H "X-API-Key: <key>"

Find work in progress

curl "https://app.buildingswell.com/api/v2/deliverable?filter=progress.status eq 'wip' and type eq 'stage'" \
  -H "X-API-Key: <key>"

Count what is still open

curl "https://app.buildingswell.com/api/v2/deliverable/count?filter=progress.status ne 'done' and isArchived eq false" \
  -H "X-API-Key: <key>"

Break work down by status

curl -X POST "https://app.buildingswell.com/api/v2/deliverable/group-and-count" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "groupByField": "progress.status" }'

Resolve project names in one request

Rather than a lookup per row, join the project onto the deliverable:

curl "https://app.buildingswell.com/api/v2/deliverable?join:project:id,name=projectId%20eq%20relation.id&type=phase" \
  -H "X-API-Key: <key>"

Send a long filter in the body

Big id lists exceed URL length limits, so use the POST twin:

curl -X POST "https://app.buildingswell.com/api/v2/deliverable/query" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "filter": "type eq '\''phase'\'' and isArchived eq false", "page": 1, "pageSize": 100 }'

Hours and payroll

Pull a pay period

curl "https://app.buildingswell.com/api/v2/timesheet?startDate:ge=2026-03-01&startDate:lt=2026-03-16" \
  -H "X-API-Key: <key>"

Paid time per row is (endDate - startDate) - breakTimeInSec. See break time and how it is carved out.

Attribute hours to an order, station, and phase

curl "https://app.buildingswell.com/api/v2/timesheet?type=deliverable_work_session\
&startDate:ge=2026-03-01&startDate:lt=2026-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>"

Find sessions that need a human to look at them

curl -X POST "https://app.buildingswell.com/api/v2/deliverable/work-sessions/error-ids" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "startDate:ge": "2026-03-01", "startDate:lt": "2026-03-16" }'

Returns the ids of overlapping and over-shift sessions, so you can clean a period up before you run payroll off it.

Check what an external system has not picked up

curl "https://app.buildingswell.com/api/v2/timesheet?type=deliverable_work_session&externalSync:ne=synced" \
  -H "X-API-Key: <key>"

Creating work

Create a project with a jobsite address

curl -X POST "https://app.buildingswell.com/api/v2/project" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{
        "name": "Warehouse A",
        "costCode": "WH-A",
        "jobsiteAddress": { "city": "Toledo", "stateOrProvince": "OH", "country": "US" }
      }'

Start an order from a route

The usual way to begin work that follows a standard process:

curl -X POST "https://app.buildingswell.com/api/v2/concepts/orders/from-route" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "routeId": "<routeId>", "projectId": "<projectId>", "name": "Warehouse A, run 3" }'

Create a node with the rules enforced

curl -X POST "https://app.buildingswell.com/api/v2/concepts/deliverables" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "type": "stage", "name": "Welding", "parentId": "<phaseId>", "data": { "shopId": "<departmentId>" } }'

Leaving data.stageId out finds or creates the Welding station in that department.

Create several deliverables at once

curl -X POST "https://app.buildingswell.com/api/v2/deliverable" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '[{ "type": "phase", "name": "Foundation" }, { "type": "phase", "name": "Framing" }]'

Learn the concept model as data

curl "https://app.buildingswell.com/api/v2/concepts" -H "X-API-Key: <key>"

Validate payloads against this instead of hard-coding the nesting rules.

Updating and removing

Change a few fields

curl -X PATCH "https://app.buildingswell.com/api/v2/project/<id>" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "scheduledEndDate": "2026-12-31" }'

Update many records at once

The filter goes in the query string. A filter in the body is ignored:

curl -X PATCH "https://app.buildingswell.com/api/v2/deliverable/bulk?type=step" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "costCode": "LABOR-001" }'

Archive instead of deleting

curl -X PATCH "https://app.buildingswell.com/api/v2/project/<id>" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "isArchived": true }'

For deliverables, the batch endpoint cascades through the subtree:

curl -X POST "https://app.buildingswell.com/api/v2/deliverable/archive/batch" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "ids": ["<uuid>", "<uuid>"] }'

See archiving and deleting before reaching for DELETE.

Preview a destructive progress action

curl -X POST "https://app.buildingswell.com/api/v2/concepts/root/<orderId>/progress/<nodeId>/plan" \
  -H "X-API-Key: <key>" -H "Content-Type: application/json" \
  -d '{ "type": "rework" }'

Nothing is written, so you can show someone the effect first.

Getting started

Core concepts

Resources

Materials and inventory

Delivery

Organization lists

Domain concepts

Examples

Reading data

List projects

Find work in progress

Count what is still open

Break work down by status

Resolve project names in one request

Send a long filter in the body

Hours and payroll

Pull a pay period

Attribute hours to an order, station, and phase

Find sessions that need a human to look at them

Check what an external system has not picked up

Creating work

Create a project with a jobsite address

Start an order from a route

Create a node with the rules enforced

Create several deliverables at once

Learn the concept model as data

Updating and removing

Change a few fields

Update many records at once

Archive instead of deleting

Preview a destructive progress action

​Reading data

​List projects

​Find work in progress

​Count what is still open

​Break work down by status

​Resolve project names in one request

​Send a long filter in the body

​Hours and payroll

​Pull a pay period

​Attribute hours to an order, station, and phase

​Find sessions that need a human to look at them

​Check what an external system has not picked up

​Creating work

​Create a project with a jobsite address

​Start an order from a route

​Create a node with the rules enforced

​Create several deliverables at once

​Learn the concept model as data

​Updating and removing

​Change a few fields

​Update many records at once

​Archive instead of deleting

​Preview a destructive progress action

Reading data

List projects

Find work in progress

Count what is still open

Break work down by status

Resolve project names in one request

Send a long filter in the body

Hours and payroll

Pull a pay period

Attribute hours to an order, station, and phase

Find sessions that need a human to look at them

Check what an external system has not picked up

Creating work

Create a project with a jobsite address

Start an order from a route

Create a node with the rules enforced

Create several deliverables at once

Learn the concept model as data

Updating and removing

Change a few fields

Update many records at once

Archive instead of deleting

Preview a destructive progress action