Lien waivers

Conditional and unconditional, progress and final. Tracked per vendor per pay app so nothing gets paid blind.

Design draftSubject to changeobject: lien_waiverid prefix: lw_

OBJECT The lien_waiver object
GET /v1/lien-waiversList lien waivers
PATCH /v1/lien-waivers/{id}Record a received waiver

The `lien_waiver` object

Every object carries an id, timestamps, and an audit_trail. Money is integer cents. Expand any node in the explorer to see how it links to the rest of the record.

id
string
Unique, stable identifier. Prefixed by object type.
object
string
String naming the object type.
project
string
Project ID.
pay_app
string
Pay app it covers.
vendor
string
Vendor ID.
type
enum
conditional_progress · unconditional_progress · conditional_final · unconditional_final.
amount
integer
Amount waived, cents.
status
enum
requested · missing · received · rejected.
file
string
Signed document file ID.
received_at
timestamp
When it arrived.
created_at
timestamp
ISO 8601, UTC.
updated_at
timestamp
ISO 8601, UTC. Changes on every write.
audit_trail
string
Path to the append-only history of who changed what, and when.

lien_waiver · sample data

object{14}

id"lw_9_volt"id
object"lien_waiver"id
project"prj_24118"id
pay_app"pa_9"id
vendor"vnd_volt_electric"id
vendor_name"Volt Electric"string
type"conditional_progress"string
amount4338000integer$43,380.00
status"received"string
file"file_lw9volt"id
received_at"2026-10-02T17:45:00Z"timestamp
created_at"2026-09-30T22:00:00Z"timestamp
updated_at"2026-10-02T17:45:00Z"timestamp
audit_trail"/v1/lien-waivers/lw_9_volt/audit"string

GET /v1/lien-waivers

List lien waivers

Filter to status=missing before you cut checks.

Parameters

pay_app
stringquery
Pay app ID.
status
enumquery
Status filter.
limit
integerquery
Page size, 1 to 100. Default 25.
cursor
stringquery
Cursor from a previous page’s next_cursor.

Returns

A paginated list of lien_waiver objects. Errors use the standard error shape.

Request

curl https://api.os.construction/v1/lien-waivers \
  -H "Authorization: Bearer $OS_API_KEY"

const res = await fetch("https://api.os.construction/v1/lien-waivers", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.OS_API_KEY}`,
  },
});
const page = await res.json();

import os, uuid, requests

res = requests.get(
    "https://api.os.construction/v1/lien-waivers",
    headers={
        "Authorization": f"Bearer {os.environ['OS_API_KEY']}",
    },
)
res.raise_for_status()
data = res.json()

Response · 200

{
  "object": "list",
  "url": "/v1/lien-waivers",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "lw_9_apex",
      "object": "lien_waiver",
      "project": "prj_24118",
      "pay_app": "pa_9",
      "vendor": "vnd_apex_steel",
      "vendor_name": "Apex Steel",
      "type": "conditional_progress",
      "amount": 4338000,
      "status": "missing",
      "file": null,
      "received_at": null,
      "created_at": "2026-09-30T22:00:00Z",
      "updated_at": "2026-10-02T17:45:00Z",
      "audit_trail": "/v1/lien-waivers/lw_9_apex/audit"
    },
    {
      "id": "lw_9_volt",
      "object": "lien_waiver",
      "project": "prj_24118",
      "pay_app": "pa_9",
      "vendor": "vnd_volt_electric",
      "vendor_name": "Volt Electric",
      "type": "conditional_progress",
      "amount": 4338000,
      "status": "received",
      "file": "file_lw9volt",
      "received_at": "2026-10-02T17:45:00Z",
      "created_at": "2026-09-30T22:00:00Z",
      "updated_at": "2026-10-02T17:45:00Z",
      "audit_trail": "/v1/lien-waivers/lw_9_volt/audit"
    }
  ]
}

PATCH /v1/lien-waivers/{id}

Record a received waiver

Attach the signed file and mark received.

Idempotent. Send an Idempotency-Key; retries within 24 hours return the original result and never write twice.

Parameters

id
stringpathrequired
The lien waiver ID, e.g. lw_9_volt.
Idempotency-Key
stringheaderrequired
Any unique string. Replays return the first result instead of writing twice.
status
enumbodyrequired
New status.
file
stringbody
File ID.

Returns

The lien_waiver object. Errors use the standard error shape.

Request

curl -X PATCH https://api.os.construction/v1/lien-waivers/lw_9_volt \
  -H "Authorization: Bearer $OS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "received",
    "file": "file_lw9volt"
  }'

const res = await fetch("https://api.os.construction/v1/lien-waivers/lw_9_volt", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.OS_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "received",
    "file": "file_lw9volt"
  }),
});
const obj = await res.json();

import os, uuid, requests

res = requests.patch(
    "https://api.os.construction/v1/lien-waivers/lw_9_volt",
    headers={
        "Authorization": f"Bearer {os.environ['OS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "status": "received",
        "file": "file_lw9volt"
    },
)
res.raise_for_status()
data = res.json()

Response · 200

{
  "id": "lw_9_volt",
  "object": "lien_waiver",
  "project": "prj_24118",
  "pay_app": "pa_9",
  "vendor": "vnd_volt_electric",
  "vendor_name": "Volt Electric",
  "type": "conditional_progress",
  "amount": 4338000,
  "status": "received",
  "file": "file_lw9volt",
  "received_at": "2026-10-02T17:45:00Z",
  "created_at": "2026-09-30T22:00:00Z",
  "updated_at": "2026-10-02T17:45:00Z",
  "audit_trail": "/v1/lien-waivers/lw_9_volt/audit"
}

Events

Webhooks fire on every state change of a lien_waiver.

lien_waiver.requested lien_waiver.received

The lien_waiver object

List lien waivers

Parameters

Returns

Record a received waiver

Parameters

Returns

Events

The `lien_waiver` object