API preview · design draft

API reference · Job cost

Commitments

Subcontracts and purchase orders. Invoices draw them down; anything over the remaining balance raises an exception.

Design draftSubject to changeobject: commitmentid prefix: cmt_

OBJECT The commitment object
GET /v1/commitmentsList commitments
GET /v1/commitments/{id}Retrieve a commitment
POST /v1/commitmentsCreate a commitment

The `commitment` 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.
number
string
Your PO or subcontract number.
type
enum
subcontract · purchase_order.
vendor
string
Vendor ID.
cost_code
string
Primary cost code.
status
enum
draft · executed · closed · void.
revised_amount
integer
original_amount + approved_changes.
billed_to_date
integer
Approved invoices against it.
remaining
integer
revised_amount − billed_to_date.
retainage_pct
number
Retainage withheld on each invoice.
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.

commitment · sample data

object{18}

id"cmt_po118"id
object"commitment"string
project"prj_24118"id
number"PO-118"string
type"purchase_order"string
vendor"vnd_volt_electric"id
vendor_name"Volt Electric"string
cost_code"cc_260500"id
status"executed"string
original_amount54000000integer$540,000.00
approved_changes0integer$0.00
revised_amount54000000integer$540,000.00
billed_to_date49795000integer$497,950.00
remaining4205000integer$42,050.00
retainage_pct10integer
created_at"2026-02-03T18:22:00Z"timestamp
updated_at"2026-09-28T14:02:11Z"timestamp
audit_trail"/v1/commitments/cmt_po118/audit"string

GET /v1/commitments

List commitments

Filter by project or vendor.

Parameters

project
stringquery
ID of the project, e.g. prj_24118.
vendor
stringquery
Vendor ID.
limit
integerquery
Page size, 1 to 100. Default 25.
cursor
stringquery
Cursor from a previous page’s next_cursor.

Returns

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

Request

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

const res = await fetch("https://api.os.construction/v1/commitments", {
  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/commitments",
    headers={
        "Authorization": f"Bearer {os.environ['OS_API_KEY']}",
    },
)
res.raise_for_status()
data = res.json()

Response · 200

{
  "object": "list",
  "url": "/v1/commitments",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "cmt_po118",
      "object": "commitment",
      "project": "prj_24118",
      "number": "PO-118",
      "type": "purchase_order",
      "vendor": "vnd_volt_electric",
      "vendor_name": "Volt Electric",
      "cost_code": "cc_260500",
      "status": "executed",
      "original_amount": 54000000,
      "approved_changes": 0,
      "revised_amount": 54000000,
      "billed_to_date": 49795000,
      "remaining": 4205000,
      "retainage_pct": 10,
      "created_at": "2026-02-03T18:22:00Z",
      "updated_at": "2026-09-28T14:02:11Z",
      "audit_trail": "/v1/commitments/cmt_po118/audit"
    }
  ]
}

GET /v1/commitments/{id}

Retrieve a commitment

Includes live billed and remaining balances.

Parameters

id
stringpathrequired
The commitment ID, e.g. cmt_po118.

Returns

The commitment object. Errors use the standard error shape.

Request

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

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

import os, uuid, requests

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

Response · 200

{
  "id": "cmt_po118",
  "object": "commitment",
  "project": "prj_24118",
  "number": "PO-118",
  "type": "purchase_order",
  "vendor": "vnd_volt_electric",
  "vendor_name": "Volt Electric",
  "cost_code": "cc_260500",
  "status": "executed",
  "original_amount": 54000000,
  "approved_changes": 0,
  "revised_amount": 54000000,
  "billed_to_date": 49795000,
  "remaining": 4205000,
  "retainage_pct": 10,
  "created_at": "2026-02-03T18:22:00Z",
  "updated_at": "2026-09-28T14:02:11Z",
  "audit_trail": "/v1/commitments/cmt_po118/audit"
}

POST /v1/commitments

Create a commitment

Creates a draft PO or subcontract.

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

Parameters

Idempotency-Key
stringheaderrequired
Any unique string. Replays return the first result instead of writing twice.
project
stringbodyrequired
Project ID.
vendor
stringbodyrequired
Vendor ID.
type
enumbodyrequired
Type.
original_amount
integerbodyrequired
Cents.

Returns

The commitment object. Errors use the standard error shape.

Request

curl -X POST https://api.os.construction/v1/commitments \
  -H "Authorization: Bearer $OS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "prj_24118",
    "vendor": "vnd_volt_electric",
    "type": "purchase_order",
    "number": "PO-118",
    "cost_code": "cc_260500",
    "original_amount": 54000000
  }'

const res = await fetch("https://api.os.construction/v1/commitments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OS_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "project": "prj_24118",
    "vendor": "vnd_volt_electric",
    "type": "purchase_order",
    "number": "PO-118",
    "cost_code": "cc_260500",
    "original_amount": 54000000
  }),
});
const obj = await res.json();

import os, uuid, requests

res = requests.post(
    "https://api.os.construction/v1/commitments",
    headers={
        "Authorization": f"Bearer {os.environ['OS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "project": "prj_24118",
        "vendor": "vnd_volt_electric",
        "type": "purchase_order",
        "number": "PO-118",
        "cost_code": "cc_260500",
        "original_amount": 54000000
    },
)
res.raise_for_status()
data = res.json()

Response · 201

{
  "id": "cmt_po118",
  "object": "commitment",
  "project": "prj_24118",
  "number": "PO-118",
  "type": "purchase_order",
  "vendor": "vnd_volt_electric",
  "vendor_name": "Volt Electric",
  "cost_code": "cc_260500",
  "status": "draft",
  "original_amount": 54000000,
  "approved_changes": 0,
  "revised_amount": 54000000,
  "billed_to_date": 0,
  "remaining": 54000000,
  "retainage_pct": 10,
  "created_at": "2026-02-03T18:22:00Z",
  "updated_at": "2026-09-28T14:02:11Z",
  "audit_trail": "/v1/commitments/cmt_po118/audit"
}

Events

Webhooks fire on every state change of a commitment.

commitment.created commitment.updated

The commitment object

List commitments

Parameters

Returns

Retrieve a commitment

Parameters

Returns

Create a commitment

Parameters

Returns

Events

The `commitment` object