Purchase Requests
- GET
/rest/v1.0/projects/{project_id}/purchase_requests - POST
/rest/v1.0/projects/{project_id}/purchase_requests - GET
/rest/v1.0/projects/{project_id}/purchase_requests/{id} - PATCH
/rest/v1.0/projects/{project_id}/purchase_requests/{id} - GET
/rest/v1.0/projects/{project_id}/purchase_requests/{id}/budget_contextRead current budget facts for the request's cost codes - POST
/rest/v1.0/projects/{project_id}/purchase_requests/{id}/transitions
/rest/v1.0/projects/{project_id}/purchase_requestsGET projects/{project_id}/purchase_requests
Parameters
- project_idintegerpathrequired
- pageintegerqueryOne-based page. The computed offset must not exceed 2147483647.
- per_pageintegerquery
- statusstringqueryOne of: draft, submitted, returned, rejected, approved, converted.
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- purchase_order_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].titlestringrequired
- revisions[].justificationstringrequired
- revisions[].vendor_idintegerrequired
- revisions[].needed_bystring (date)required
- revisions[].delivery_locationstringrequired
- revisions[].linesobject[]required
- revisions[].revisionintegerrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequiredOne of: created, revised, submit, return, reject, approve, convert.
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].created_atstring (date-time)required
Errors
403Permission, tenant, tool or independent-review denial404Record not found within project scope409Stale version or invalid lifecycle transition422Invalid request or references
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/purchase_requests" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/purchase_requestsPOST projects/{project_id}/purchase_requests
Parameters
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- titlestringrequired
- justificationstringrequired
- vendor_idintegerrequired
- needed_bystring (date)required
- delivery_locationstringrequired
- linesobject[]required
- lines[].descriptionstringrequired
- lines[].cost_code_idintegerrequired
- lines[].quantitystringrequiredPositive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
- lines[].unit_coststringrequiredPositive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
- lines[].uomstringrequired
Response · 201 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- purchase_order_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].titlestringrequired
- revisions[].justificationstringrequired
- revisions[].vendor_idintegerrequired
- revisions[].needed_bystring (date)required
- revisions[].delivery_locationstringrequired
- revisions[].linesobject[]required
- revisions[].revisionintegerrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequiredOne of: created, revised, submit, return, reject, approve, convert.
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].created_atstring (date-time)required
Errors
403Permission, tenant, tool or independent-review denial404Record not found within project scope409Stale version or invalid lifecycle transition422Invalid request or references
Example request
Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/purchase_requests" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"title": "string",
"justification": "string",
"vendor_id": 1,
"needed_by": "2026-11-01",
"delivery_location": "string",
"lines": [
{
"description": "string",
"cost_code_id": 1,
"quantity": "0.00",
"unit_cost": "0.00",
"uom": "string"
}
]
}'/rest/v1.0/projects/{project_id}/purchase_requests/{id}GET projects/{project_id}/purchase_requests/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- purchase_order_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].titlestringrequired
- revisions[].justificationstringrequired
- revisions[].vendor_idintegerrequired
- revisions[].needed_bystring (date)required
- revisions[].delivery_locationstringrequired
- revisions[].linesobject[]required
- revisions[].revisionintegerrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequiredOne of: created, revised, submit, return, reject, approve, convert.
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].created_atstring (date-time)required
Errors
403Permission, tenant, tool or independent-review denial404Record not found within project scope409Stale version or invalid lifecycle transition422Invalid request or references
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/purchase_requests/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/purchase_requests/{id}PATCH projects/{project_id}/purchase_requests/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- expected_versionintegerrequired
- requestobjectrequiredThe sum of quantity ? unit_cost rounded half-up to cents per line must not exceed 999999999999.99. Each value must be positive. Company, status and reviewer fields are derived server-side and cannot be supplied.
- request.titlestringrequired
- request.justificationstringrequired
- request.vendor_idintegerrequired
- request.needed_bystring (date)required
- request.delivery_locationstringrequired
- request.linesobject[]required
- request.lines[].descriptionstringrequired
- request.lines[].cost_code_idintegerrequired
- request.lines[].quantitystringrequiredPositive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
- request.lines[].unit_coststringrequiredPositive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
- request.lines[].uomstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- purchase_order_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].titlestringrequired
- revisions[].justificationstringrequired
- revisions[].vendor_idintegerrequired
- revisions[].needed_bystring (date)required
- revisions[].delivery_locationstringrequired
- revisions[].linesobject[]required
- revisions[].revisionintegerrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequiredOne of: created, revised, submit, return, reject, approve, convert.
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].created_atstring (date-time)required
Errors
403Permission, tenant, tool or independent-review denial404Record not found within project scope409Stale version or invalid lifecycle transition422Invalid request or references
Example request
Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/purchase_requests/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"request": {
"title": "string",
"justification": "string",
"vendor_id": 1,
"needed_by": "2026-11-01",
"delivery_location": "string",
"lines": [
{
"description": "string",
"cost_code_id": 1,
"quantity": "0.00",
"unit_cost": "0.00",
"uom": "string"
}
]
}
}'/rest/v1.0/projects/{project_id}/purchase_requests/{id}/budget_contextRead current budget facts for the request's cost codes
Requires purchase_requests:read and budget:read plus both live project view grants and tool enablement. Facts are advisory existing Budget aggregates, not reserved funds. No currency or after-request projection is inferred. Converted requests are never added again to budget exposure.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- expected_versionintegerqueryrequired
Response · 200 · object
- request_idintegerrequired
- request_revisionintegerrequired
- request_versionintegerrequired
- request_statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- calculated_atstring (date-time)required
- convertedbooleanrequired
- currencynullrequiredNo currency is inferred from untyped request and budget amounts.
- projectionstringrequired
- basisstringrequired
- rowsobject[]required
- rows[].cost_code_idintegerrequired
- rows[].cost_code_labelstringrequired
- rows[].requested_amountstringrequired
- rows[].availabilitystringrequiredOne of: budgeted, unbudgeted, not_in_budget_model.
- rows[].budget_line_countintegerrequired
- rows[].factsobject | nullrequired
Errors
403Missing live request/budget authority, tool enablement or read scope.404Request not in the authorized project.409Expected version is stale, or the request changed during the budget read.422Invalid or missing version or out-of-range identifier.503Budget source or precision unavailable. No totals returned.
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/purchase_requests/1/budget_context" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/purchase_requests/{id}/transitionsPOST projects/{project_id}/purchase_requests/{id}/transitions
Requires purchase_requests:write scope. Conversion additionally requires commitments:write. Standard users submit their own drafts. Administrators independently approve, return or reject. Conversion requires both module admin and commitment creation authority. A conversion retry returns the original result, regardless of the old version, after rechecking authority.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- expected_versionintegerrequired
- actionstringrequiredOne of: submit, return, reject, approve, convert.
- reasonstringAt least three characters required for return and reject.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- project_idintegerrequired
- statusstringrequiredOne of: draft, submitted, returned, rejected, approved, converted.
- revisionintegerrequired
- versionintegerrequired
- created_by_idintegerrequired
- purchase_order_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- revisionsobject[]required
- revisions[].titlestringrequired
- revisions[].justificationstringrequired
- revisions[].vendor_idintegerrequired
- revisions[].needed_bystring (date)required
- revisions[].delivery_locationstringrequired
- revisions[].linesobject[]required
- revisions[].revisionintegerrequired
- revisions[].created_atstring (date-time)required
- revisions[].totalstringrequired
- decisionsobject[]required
- decisions[].revisionintegerrequired
- decisions[].versionintegerrequired
- decisions[].actionstringrequiredOne of: created, revised, submit, return, reject, approve, convert.
- decisions[].reasonstringrequired
- decisions[].actor_idintegerrequired
- decisions[].created_atstring (date-time)required
Errors
403Permission, tenant, tool or independent-review denial404Record not found within project scope409Stale version or invalid lifecycle transition422Invalid request or references
Example request
Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/purchase_requests/1/transitions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"action": "submit"
}'