Esc

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

Job Cost Forecast

Inspect job costs and approve cost-to-complete forecasts. 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 Job Cost Forecast guide for the workflow.

7 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/job_cost_entriesList job cost entries
  2. GET /rest/v1.0/companies/{company_id}/accounting/jobcost/forecastReview a tenant/entity-scoped forecast from dated sources
  3. PUT /rest/v1.0/companies/{company_id}/accounting/jobcost/forecastSave a dated PM forecast input: projection method per cost code (manual cost to complete, physical percent complete, unit rate, budget) and its inputs (jobForecastEdit permission; PM grants only on projects they belong to). With no PM input a cost code's EAC is max(revised budget, actual + remaining commitments) (flag unforecast_budget when the budget is higher); a null cost_to_complete selects actual + remaining commitments explicitly and, like any input, needs approval before WIP reads it. Saving clears any approval; saving on a later date than the carried-forward input adds a new dated input. Frozen forecasts dated on or after the input are superseded (kept, with supersededAt), never deleted; the audit lists their ids. Refused (409) in a soft- or hard-closed job cost period and on or before the latest posted WIP period end for the entity.
  4. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/forecast/approveApprove the PM input shown for a cost code on the worksheet date (approveJournal permission; the last editor cannot approve). Only approved inputs may feed WIP. Approving the last pending input for the date freezes the forecast there, superseding (not deleting) an earlier freeze on the same date. Refused (409) in a hard-closed period or on or before the latest posted WIP period end; allowed in a soft-closed period, so a month-end approval freezes at the period end.
  5. GET /rest/v1.0/companies/{company_id}/accounting/jobcost/scopeList accessible projects, entities and source assignments
  6. POST /rest/v1.0/companies/{company_id}/accounting/jobcost/scopeAssign a project's sources to one entity and base currency (unrestricted manageCoa permission)
  7. PATCH /rest/v1.0/companies/{company_id}/accounting/jobcost/scopeSet a job's WIP contract terms (manageCoa): revenue method (cost_to_cost, or as_invoiced for T&M / cost-plus jobs: revenue equals billings, ASC 606-10-55-18) and/or whether retainage is conditional (WIP presents it as a contract asset, ASC 606-10-45-3). Audited with the reason.

Accounting / Job Cost Forecast

GET /rest/v1.0/companies/{company_id}/accounting/job_cost_entries

List job cost entries

The job cost subledger: one actual row per posted line on a job-cost account with a project (labor, burden, material, subcontract, equipment, other), linked to its GL line. Filter with filters[project_id], filters[cost_code_id], filters[cost_type], filters[kind] and a from/to date range. A project_manager_view grant sees only the projects its user is a member of. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • filters[project_id]
    stringquery
    Project ids
  • filters[cost_code_id]
    stringquery
    Cost code ids
  • filters[cost_type]
    stringquery
    labor, material, subcontract, equipment, other, burden
  • filters[kind]
    stringquery
    actual, committed, estimate, projection, change, billed
  • from
    string (date)query
    On or after
  • to
    string (date)query
    On or before
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
  • cost_code_id
    integer | nullrequired
  • cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden.
  • cost_type_id
    integer | nullrequired
  • kind
    anyrequired
    One of: actual, committed, estimate, projection, change, billed.
  • amount
    stringrequired
    Decimal amount as a string, 2 dp
  • hours
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • quantity
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • date
    string (date)required
  • period_id
    integer | nullrequired
  • source_type
    stringrequired
  • source_id
    integer | nullrequired
  • journal_line_id
    integer | nullrequired
  • memo
    string | nullrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 422Unknown filter value

Example request

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

Accounting / Job Cost Forecast

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

Review a tenant/entity-scoped forecast from dated sources

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • project_id
    integerqueryrequired
  • entity_id
    integerqueryrequired
  • as_of
    string (date)queryrequired

Response · 200 · object

  • project
    objectrequired
  • project.id
    integerrequired
  • project.name
    stringrequired
  • entity
    objectrequired
  • entity.id
    integerrequired
  • entity.name
    stringrequired
  • asOf
    string (date)required
  • currency
    stringrequired
  • basis
    stringrequired
  • totals
    objectrequired
  • totals.revisedBudget
    stringrequired
  • totals.actual
    stringrequired
  • totals.committed
    string
  • totals.openCommitments
    string
  • totals.remainingCommitments
    stringrequired
  • totals.exposure
    stringrequired
  • totals.costToComplete
    stringrequired
  • totals.eac
    stringrequired
  • totals.variance
    stringrequired
  • lines
    object[]required
  • lines[].revisedBudget
    stringrequired
  • lines[].actual
    stringrequired
  • lines[].committed
    string
  • lines[].openCommitments
    string
  • lines[].remainingCommitments
    stringrequired
  • lines[].exposure
    stringrequired
  • lines[].costToComplete
    stringrequired
  • lines[].eac
    stringrequired
  • lines[].variance
    stringrequired
  • lines[].costCodeId
    integer | nullrequired
    null for the Unassigned cost code row (uncoded posted actuals)
  • lines[].code
    stringrequired
  • lines[].name
    stringrequired
  • lines[].eacBelowFloor
    booleanrequired
  • lines[].notBudgeted
    booleanrequired
    A project cost code with actuals or commitments but no budget line: shown with a budget of 0
  • lines[].flags
    string[]
    Line flags: unforecast_budget (no PM input and revised budget exceeds actual + remaining commitments, so EAC uses the budget), commitment_overrun, eac_below_actual_plus_committed, over_budget
  • lines[].sources
    object[]required
  • lines[].explain
    object[]required
  • lines[].pm
    object | nullrequired
    Latest PM input dated on or before asOf for this cost code

Errors

  • 403No accounting/entity access
  • 409Missing assignment, inconsistent sources, unsupported consumption, or unavailable historical revisions
  • 422Invalid project/entity/date

Example request

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

Accounting / Job Cost Forecast

PUT /rest/v1.0/companies/{company_id}/accounting/jobcost/forecast

Save a dated PM forecast input: projection method per cost code (manual cost to complete, physical percent complete, unit rate, budget) and its inputs (jobForecastEdit permission; PM grants only on projects they belong to). With no PM input a cost code's EAC is max(revised budget, actual + remaining commitments) (flag unforecast_budget when the budget is higher); a null cost_to_complete selects actual + remaining commitments explicitly and, like any input, needs approval before WIP reads it. Saving clears any approval; saving on a later date than the carried-forward input adds a new dated input. Frozen forecasts dated on or after the input are superseded (kept, with supersededAt), never deleted; the audit lists their ids. Refused (409) in a soft- or hard-closed job cost period and on or before the latest posted WIP period end for the entity.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • project_id
    integerrequired
  • entity_id
    integerrequired
  • cost_code_id
    integerrequired
  • as_of
    string (date)required
  • cost_to_complete
    string | nullrequired
  • reason
    stringrequired
  • revision
    integerrequired
  • method
    string | null
    Projection method for the cost code. Omitted or null: manual when cost_to_complete is set, else actual plus remaining commitments. percent_complete needs percent_complete in (0, 100]; unit_rate needs units_installed > 0 and total_units >= units_installed; manual_cost_to_complete needs cost_to_complete. One of: manual_cost_to_complete, percent_complete, unit_rate, budget, budget_remaining, actual_plus_committed, null.
  • percent_complete
    string | null
    Physical percent complete (percent_complete method).
  • units_installed
    string | null
    Units installed to date (unit_rate method).
  • total_units
    string | null
    Total units at completion (unit_rate method).

Response · 200

No response body.

Errors

  • 403No write permission or read-only workspace
  • 409Stale revision or source coverage failure (reload before retrying), the date is in a soft- or hard-closed period, or WIP is posted through the date
  • 422Invalid money, date, code or reason

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/forecast" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 1,
  "entity_id": 1,
  "cost_code_id": 1,
  "as_of": "2026-11-01",
  "cost_to_complete": "0.00",
  "reason": "string",
  "revision": 1
}'

Accounting / Job Cost Forecast

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

Approve the PM input shown for a cost code on the worksheet date (approveJournal permission; the last editor cannot approve). Only approved inputs may feed WIP. Approving the last pending input for the date freezes the forecast there, superseding (not deleting) an earlier freeze on the same date. Refused (409) in a hard-closed period or on or before the latest posted WIP period end; allowed in a soft-closed period, so a month-end approval freezes at the period end.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • project_id
    integerrequired
  • entity_id
    integerrequired
  • cost_code_id
    integerrequired
  • as_of
    string (date)required
  • revision
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • revision
    integerrequired
  • approvedAt
    string (date-time)required

Errors

  • 403No approval permission, segregation of duties, or read-only workspace
  • 404No PM input for that cost code on or before the date
  • 409Stale revision or source coverage failure (reload before retrying), the date is in a hard-closed period, or WIP is posted through the date
  • 422Invalid input

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/forecast/approve" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 1,
  "entity_id": 1,
  "cost_code_id": 1,
  "as_of": "2026-11-01",
  "revision": 1
}'

Accounting / Job Cost Forecast

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

List accessible projects, entities and source assignments

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200

No response body.

Example request

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

Accounting / Job Cost Forecast

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

Assign a project's sources to one entity and base currency (unrestricted manageCoa permission)

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • project_id
    integerrequired
  • entity_id
    integerrequired
  • currency
    stringrequired
  • reason
    stringrequired
  • confirm_project_sources
    booleanrequired

Response · 201

No response body.

Errors

  • 403Insufficient permission
  • 409Existing assignment, mixed entities or currency mismatch
  • 422Invalid input or missing confirmation

Example request

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

Accounting / Job Cost Forecast

PATCH /rest/v1.0/companies/{company_id}/accounting/jobcost/scope

Set a job's WIP contract terms (manageCoa): revenue method (cost_to_cost, or as_invoiced for T&M / cost-plus jobs: revenue equals billings, ASC 606-10-55-18) and/or whether retainage is conditional (WIP presents it as a contract asset, ASC 606-10-45-3). Audited with the reason.

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • project_id
    integerrequired
  • revenue_method
    any
    One of: cost_to_cost, as_invoiced.
  • retainage_conditional
    boolean
    Retainage is payable on completion or acceptance, not just time: presented as a contract asset on the WIP row
  • reason
    stringrequired

Response · 200

No response body.

Errors

  • 403Insufficient permission or entity outside the grant
  • 404Project not assigned to an entity
  • 422Invalid input

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/jobcost/scope" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 1,
  "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