Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · People, jobs and assets

Work in Progress (WIP)

Compute, review and post WIP snapshots with supporting evidence. Every operation below is generated from the published OpenAPI contract. Paths are company-scoped; read the Accounting API guide for scopes, step-up and permissions, and the Work in Progress (WIP) guide for the workflow.

8 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wipList WIP snapshots (newest period end and revision first), 100 per page, filtered by entity, period and status.
  2. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wipCompute the next WIP revision for an entity at an ended period (postJournal and viewLedger). Contract = executed prime SOV + approved prime COs; cost = posted job cost; billed = posted AR; EAC = the forecast frozen at the period end (PM approval or soft close) plus job cost posted since the freeze beyond what the freeze already held on each cost code (only cost on a commitment-linked line consumes the open commitment frozen there; a budget_remaining code rises to max(frozen EAC, actual + commitment left)), else the approved live forecast, unless overridden with a reason. Each job uses its revenue method (cost_to_cost or as_invoiced); pending prime COs are the memo column (pendingChangeOrders) and enter the transaction price only through overrides[].change_orders; retainage receivable comes from AR (retainageContractAsset when the job's retainage is conditional); each row records settings.loss_provision_unit; cash position is AR receipts less AP payments on the job (payroll and other direct cash costs are not included). A job whose inputs fail is a compute_failed exception, and an executed contract with no value against a positive EAC a contract_value_missing exception (not on completed_contract jobs; the other jobs still compute); both block approval. Rows are read without the company posting lock; the insert refuses with 409 if job cost or billings were posted, or job forecast inputs changed, meanwhile. Supports Idempotency-Key.
  3. GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}Get a WIP snapshot with its job rows; format=csv returns the rows as CSV
  4. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/approveApprove a draft snapshot (approveJournal; the preparer cannot approve). A snapshot with exceptions needs exceptions_note; compute_failed exceptions cannot be acknowledged. Idempotent; a rejected snapshot is refused.
  5. GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/attachmentsList attachments on a WIP snapshot
  6. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/attachmentsAttach a file to a WIP snapshot
  7. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/postPost an approved snapshot on journal WIP at the period end with autoReverseDate the next day; idempotent on (snapshot, revision). Supersedes an earlier posted revision for the period.
  8. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/rejectReject a draft or approved snapshot (approveJournal; terminal, compute a new revision), or with return_to_draft send an approved one back to draft (approval and acknowledgment cleared). Audited with the reason.

Accounting / Work in Progress (WIP)

GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wip

List WIP snapshots (newest period end and revision first), 100 per page, filtered by entity, period and status.

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • entity_id
    integerquery
  • period_id
    integerquery
  • status
    stringquery
    One of: draft, approved, posted, superseded, rejected.
  • page
    integerquery
    1-based page of 100 snapshots

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Work in Progress (WIP)

POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip

Compute the next WIP revision for an entity at an ended period (postJournal and viewLedger). Contract = executed prime SOV + approved prime COs; cost = posted job cost; billed = posted AR; EAC = the forecast frozen at the period end (PM approval or soft close) plus job cost posted since the freeze beyond what the freeze already held on each cost code (only cost on a commitment-linked line consumes the open commitment frozen there; a budget_remaining code rises to max(frozen EAC, actual + commitment left)), else the approved live forecast, unless overridden with a reason. Each job uses its revenue method (cost_to_cost or as_invoiced); pending prime COs are the memo column (pendingChangeOrders) and enter the transaction price only through overrides[].change_orders; retainage receivable comes from AR (retainageContractAsset when the job's retainage is conditional); each row records settings.loss_provision_unit; cash position is AR receipts less AP payments on the job (payroll and other direct cash costs are not included). A job whose inputs fail is a compute_failed exception, and an executed contract with no value against a positive EAC a contract_value_missing exception (not on completed_contract jobs; the other jobs still compute); both block approval. Rows are read without the company posting lock; the insert refuses with 409 if job cost or billings were posted, or job forecast inputs changed, meanwhile. Supports Idempotency-Key.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • entity_id
    integerrequired
  • period_id
    integerrequired
  • overrides
    object[]
  • overrides[].project_id
    integerrequired
  • overrides[].eac
    string
    Replaces the forecast EAC
  • overrides[].reason
    stringrequired
  • overrides[].uninstalled_materials
    string
    Cost of uninstalled, customer-controlled materials in cost to date; excluded from the measure of progress (ASC 606-10-55-21(b))
  • overrides[].excluded_cost
    string
    Cost in cost to date that does not depict progress (inefficiency, unpriced rework): stays in cost to date, out of the cost-to-cost measure (ASC 606-10-55-21(a)). Cost-to-cost jobs only.
  • overrides[].change_orders
    object[]
    Pending or unpriced prime change orders (PCO ids) included in the transaction price as constrained variable consideration (ASC 606-10-32-11). A CO that is not pending on the job is a compute_failed exception. Stored on the row as variable_consideration.
  • overrides[].change_orders[].change_order_id
    integerrequired
  • overrides[].change_orders[].include_amount
    stringrequired
    Amount included after the constraint; 0 records a full constraint
  • overrides[].change_orders[].rationale
    stringrequired
    Why this amount is highly probable not to reverse

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties
  • 404Entity or period not found
  • 409Job cost or billings were posted through the period end while WIP was computing; compute again
  • 422Invalid input (an override needs an EAC, uninstalled materials, excluded cost or change orders, and a reason; one per project), period not ended, or override for a project outside the entity

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": 1,
  "period_id": 1
}'

Accounting / Work in Progress (WIP)

GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}

Get a WIP snapshot with its job rows; format=csv returns the rows as CSV

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • format
    anyquery
    One of: json, csv.

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties
  • 404Snapshot not found in this company or entity scope

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Work in Progress (WIP)

POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/approve

Approve a draft snapshot (approveJournal; the preparer cannot approve). A snapshot with exceptions needs exceptions_note; compute_failed exceptions cannot be acknowledged. Idempotent; a rejected snapshot is refused.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • exceptions_note
    string
    Acknowledges the jobs listed in exceptions

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties
  • 404Snapshot not found in this company or entity scope
  • 409Stale: job cost or billings were posted through the period end after the snapshot was computed; a job could not compute (compute_failed: fix it or override it, then compute a new revision); or exceptions need an exceptions_note
  • 422The snapshot was rejected

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1/approve" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "exceptions_note": "string"
}'

Accounting / Work in Progress (WIP)

GET /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/attachments

List attachments on a WIP snapshot

Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
  • doc_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Work in Progress (WIP)

POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/attachments

Attach a file to a WIP snapshot

Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs post_journal and the parent's entity scope. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
  • doc_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Idempotency-Key reused for a different request or still in progress
  • 413Request body too large
  • 422Missing file, empty file, too large, or a type that is not allowed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1/attachments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "string"
}'

Accounting / Work in Progress (WIP)

POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/post

Post an approved snapshot on journal WIP at the period end with autoReverseDate the next day; idempotent on (snapshot, revision). Supersedes an earlier posted revision for the period.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties
  • 404Snapshot not found in this company or entity scope
  • 409A later revision exists for the period, or the snapshot is stale (job cost or billings posted through the period end after compute)
  • 422Snapshot not approved, a WIP system account is missing, or the period is closed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1/post" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Work in Progress (WIP)

POST /rest/v1.0/companies/{company_id}/accounting/jobcost/wip/{id}/reject

Reject a draft or approved snapshot (approveJournal; terminal, compute a new revision), or with return_to_draft send an approved one back to draft (approval and acknowledgment cleared). Audited with the reason.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • reason
    stringrequired
  • return_to_draft
    boolean

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • period_end
    string (date)required
  • revision
    integerrequired
  • status
    anyrequired
    One of: draft, approved, posted, superseded, rejected.
  • revised_contract
    string
  • earned_to_date
    string
  • billed_to_date
    string
  • underbillings
    stringrequired
  • overbillings
    stringrequired
  • loss_provision
    stringrequired
  • prepared_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string (date-time) | null
  • journal_entry_id
    integer | null
  • journal_entry_number
    string | null
  • posted_at
    string (date-time) | null
  • exceptions
    object[]
    Exceptions on the snapshot. not_assigned / no_executed_prime_contract: jobs with posted job cost or billings in the entity through the period end that WIP leaves out (inactive or completed jobs excluded). contract_unverified: rows whose contract source changed after the period end with no earlier revision of the period, computed at today's contract value. These three are acknowledged with exceptions_note at approval. contract_value_missing: an executed prime contract with no value (no SOV keyed) against a positive EAC, on a job not on completed_contract; it has no row and blocks approval like compute_failed. compute_failed: a job whose inputs failed (forecast coverage, a pending PM input, negative cost; see message); it has no row and blocks approval until a new revision resolves it. A project-scoped (PM) grant sees only its projects' exceptions.
  • exceptions[].project_id
    integerrequired
  • exceptions[].name
    stringrequired
  • exceptions[].reason
    anyrequired
    One of: not_assigned, no_executed_prime_contract, contract_unverified, contract_value_missing, compute_failed.
  • exceptions[].cost
    stringrequired
  • exceptions[].billed
    stringrequired
  • exceptions[].message
    string
    Why the job could not compute (compute_failed, contract_value_missing)
  • exceptions_acknowledged_by_id
    integer | null
  • exceptions_acknowledged_at
    string (date-time) | null
  • exceptions_note
    string | null
    The approver's acknowledgment of the exceptions; null for a project-scoped (PM) grant, since it may name other jobs.
  • rows
    object[]required
    Job rows. The list (GET .../jobcost/wip) returns only project_id, eac_override and override_reason per row (changed: it returned full rows before; see CHANGELOG); the snapshot (GET .../wip/{id}) returns the full row with its explain trace.
  • rows[].project_id
    integerrequired
  • rows[].name
    string
  • rows[].eac_override
    string | null
  • rows[].override_reason
    string | null
  • rows[].revisedContract
    string
  • rows[].eac
    string
  • rows[].costToDate
    string
  • rows[].percentComplete
    string
  • rows[].earnedToDate
    string
  • rows[].billedToDate
    string
  • rows[].underbillings
    string
  • rows[].overbillings
    string
  • rows[].lossProvision
    string
  • rows[].variableConsideration
    string
  • rows[].pendingChangeOrders
    string
    Memo: pending prime COs, never in the transaction price
  • rows[].excludedFromProgress
    string
  • rows[].costToDatePoc
    string
  • rows[].retainageReceivable
    string
  • rows[].retainageContractAsset
    string
  • rows[].totalAnticipatedLoss
    string
  • rows[].lossProvisionUnit
    any
    One of: contract, performance_obligation.
  • rows[].variable_consideration
    object[]
    Change orders included in the transaction price at compute, with the constraint rationale
  • rows[].flags
    string[]
    Includes contract_frozen when a contract source changed after the period end and an earlier revision's contract value is kept, contract_unverified when no earlier revision exists and today's value is used, or unforecast_budget when the live forecast EAC uses revised budget not yet backed by cost, commitments or a PM input

Errors

  • 403No accounting permission for this action, entity outside the grant, or segregation of duties
  • 404Snapshot not found in this company or entity scope
  • 422Invalid input, or the snapshot is not in a state that allows it (posted, superseded or already rejected)

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/wip/1/reject" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'

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