Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Financial Management

Purchase Requests

6 endpoints6 implementedAll modules →
  1. GET /rest/v1.0/projects/{project_id}/purchase_requests
  2. POST /rest/v1.0/projects/{project_id}/purchase_requests
  3. GET /rest/v1.0/projects/{project_id}/purchase_requests/{id}
  4. PATCH /rest/v1.0/projects/{project_id}/purchase_requests/{id}
  5. GET /rest/v1.0/projects/{project_id}/purchase_requests/{id}/budget_contextRead current budget facts for the request's cost codes
  6. POST /rest/v1.0/projects/{project_id}/purchase_requests/{id}/transitions
GET /rest/v1.0/projects/{project_id}/purchase_requests

GET projects/{project_id}/purchase_requests

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • page
    integerquery
    One-based page. The computed offset must not exceed 2147483647.
  • per_page
    integerquery
  • status
    stringquery
    One of: draft, submitted, returned, rejected, approved, converted.

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • purchase_order_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].title
    stringrequired
  • revisions[].justification
    stringrequired
  • revisions[].vendor_id
    integerrequired
  • revisions[].needed_by
    string (date)required
  • revisions[].delivery_location
    stringrequired
  • revisions[].lines
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
    One of: created, revised, submit, return, reject, approve, convert.
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].created_at
    string (date-time)required

Errors

  • 403Permission, tenant, tool or independent-review denial
  • 404Record not found within project scope
  • 409Stale version or invalid lifecycle transition
  • 422Invalid 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"
POST /rest/v1.0/projects/{project_id}/purchase_requests

POST projects/{project_id}/purchase_requests

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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

  • title
    stringrequired
  • justification
    stringrequired
  • vendor_id
    integerrequired
  • needed_by
    string (date)required
  • delivery_location
    stringrequired
  • lines
    object[]required
  • lines[].description
    stringrequired
  • lines[].cost_code_id
    integerrequired
  • lines[].quantity
    stringrequired
    Positive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
  • lines[].unit_cost
    stringrequired
    Positive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
  • lines[].uom
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • purchase_order_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].title
    stringrequired
  • revisions[].justification
    stringrequired
  • revisions[].vendor_id
    integerrequired
  • revisions[].needed_by
    string (date)required
  • revisions[].delivery_location
    stringrequired
  • revisions[].lines
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
    One of: created, revised, submit, return, reject, approve, convert.
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].created_at
    string (date-time)required

Errors

  • 403Permission, tenant, tool or independent-review denial
  • 404Record not found within project scope
  • 409Stale version or invalid lifecycle transition
  • 422Invalid 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"
    }
  ]
}'
GET /rest/v1.0/projects/{project_id}/purchase_requests/{id}

GET projects/{project_id}/purchase_requests/{id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • purchase_order_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].title
    stringrequired
  • revisions[].justification
    stringrequired
  • revisions[].vendor_id
    integerrequired
  • revisions[].needed_by
    string (date)required
  • revisions[].delivery_location
    stringrequired
  • revisions[].lines
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
    One of: created, revised, submit, return, reject, approve, convert.
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].created_at
    string (date-time)required

Errors

  • 403Permission, tenant, tool or independent-review denial
  • 404Record not found within project scope
  • 409Stale version or invalid lifecycle transition
  • 422Invalid 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"
PATCH /rest/v1.0/projects/{project_id}/purchase_requests/{id}

PATCH projects/{project_id}/purchase_requests/{id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_version
    integerrequired
  • request
    objectrequired
    The 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.title
    stringrequired
  • request.justification
    stringrequired
  • request.vendor_id
    integerrequired
  • request.needed_by
    string (date)required
  • request.delivery_location
    stringrequired
  • request.lines
    object[]required
  • request.lines[].description
    stringrequired
  • request.lines[].cost_code_id
    integerrequired
  • request.lines[].quantity
    stringrequired
    Positive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
  • request.lines[].unit_cost
    stringrequired
    Positive decimal string, at most eight integer digits and four decimal places; zero is not allowed.
  • request.lines[].uom
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • purchase_order_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].title
    stringrequired
  • revisions[].justification
    stringrequired
  • revisions[].vendor_id
    integerrequired
  • revisions[].needed_by
    string (date)required
  • revisions[].delivery_location
    stringrequired
  • revisions[].lines
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
    One of: created, revised, submit, return, reject, approve, convert.
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].created_at
    string (date-time)required

Errors

  • 403Permission, tenant, tool or independent-review denial
  • 404Record not found within project scope
  • 409Stale version or invalid lifecycle transition
  • 422Invalid 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"
      }
    ]
  }
}'
GET /rest/v1.0/projects/{project_id}/purchase_requests/{id}/budget_context

Read 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • expected_version
    integerqueryrequired

Response · 200 · object

  • request_id
    integerrequired
  • request_revision
    integerrequired
  • request_version
    integerrequired
  • request_status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • calculated_at
    string (date-time)required
  • converted
    booleanrequired
  • currency
    nullrequired
    No currency is inferred from untyped request and budget amounts.
  • projection
    stringrequired
  • basis
    stringrequired
  • rows
    object[]required
  • rows[].cost_code_id
    integerrequired
  • rows[].cost_code_label
    stringrequired
  • rows[].requested_amount
    stringrequired
  • rows[].availability
    stringrequired
    One of: budgeted, unbudgeted, not_in_budget_model.
  • rows[].budget_line_count
    integerrequired
  • rows[].facts
    object | 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"
POST /rest/v1.0/projects/{project_id}/purchase_requests/{id}/transitions

POST 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. 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_version
    integerrequired
  • action
    stringrequired
    One of: submit, return, reject, approve, convert.
  • reason
    string
    At least three characters required for return and reject.

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • project_id
    integerrequired
  • status
    stringrequired
    One of: draft, submitted, returned, rejected, approved, converted.
  • revision
    integerrequired
  • version
    integerrequired
  • created_by_id
    integerrequired
  • purchase_order_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • revisions
    object[]required
  • revisions[].title
    stringrequired
  • revisions[].justification
    stringrequired
  • revisions[].vendor_id
    integerrequired
  • revisions[].needed_by
    string (date)required
  • revisions[].delivery_location
    stringrequired
  • revisions[].lines
    object[]required
  • revisions[].revision
    integerrequired
  • revisions[].created_at
    string (date-time)required
  • revisions[].total
    stringrequired
  • decisions
    object[]required
  • decisions[].revision
    integerrequired
  • decisions[].version
    integerrequired
  • decisions[].action
    stringrequired
    One of: created, revised, submit, return, reject, approve, convert.
  • decisions[].reason
    stringrequired
  • decisions[].actor_id
    integerrequired
  • decisions[].created_at
    string (date-time)required

Errors

  • 403Permission, tenant, tool or independent-review denial
  • 404Record not found within project scope
  • 409Stale version or invalid lifecycle transition
  • 422Invalid 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"
}'

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file