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.
- GET
/rest/v1.0/companies/{company_id}/accounting/job_cost_entriesList job cost entries - GET
/rest/v1.0/companies/{company_id}/accounting/jobcost/forecastReview a tenant/entity-scoped forecast from dated sources - 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. - 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. - GET
/rest/v1.0/companies/{company_id}/accounting/jobcost/scopeList accessible projects, entities and source assignments - POST
/rest/v1.0/companies/{company_id}/accounting/jobcost/scopeAssign a project's sources to one entity and base currency (unrestricted manageCoa permission) - 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_entriesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- filters[project_id]stringqueryProject ids
- filters[cost_code_id]stringqueryCost code ids
- filters[cost_type]stringquerylabor, material, subcontract, equipment, other, burden
- filters[kind]stringqueryactual, committed, estimate, projection, change, billed
- fromstring (date)queryOn or after
- tostring (date)queryOn or before
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequired
- cost_code_idinteger | nullrequired
- cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden.
- cost_type_idinteger | nullrequired
- kindanyrequiredOne of: actual, committed, estimate, projection, change, billed.
- amountstringrequiredDecimal amount as a string, 2 dp
- hoursstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- quantitystring | nullrequiredDecimal rate or quantity as a string, 6 dp
- datestring (date)required
- period_idinteger | nullrequired
- source_typestringrequired
- source_idinteger | nullrequired
- journal_line_idinteger | nullrequired
- memostring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Unknown filter value
Example request
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/forecastReview a tenant/entity-scoped forecast from dated sources
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
- project_idintegerqueryrequired
- entity_idintegerqueryrequired
- as_ofstring (date)queryrequired
Response · 200 · object
- projectobjectrequired
- project.idintegerrequired
- project.namestringrequired
- entityobjectrequired
- entity.idintegerrequired
- entity.namestringrequired
- asOfstring (date)required
- currencystringrequired
- basisstringrequired
- totalsobjectrequired
- totals.revisedBudgetstringrequired
- totals.actualstringrequired
- totals.committedstring
- totals.openCommitmentsstring
- totals.remainingCommitmentsstringrequired
- totals.exposurestringrequired
- totals.costToCompletestringrequired
- totals.eacstringrequired
- totals.variancestringrequired
- linesobject[]required
- lines[].revisedBudgetstringrequired
- lines[].actualstringrequired
- lines[].committedstring
- lines[].openCommitmentsstring
- lines[].remainingCommitmentsstringrequired
- lines[].exposurestringrequired
- lines[].costToCompletestringrequired
- lines[].eacstringrequired
- lines[].variancestringrequired
- lines[].costCodeIdinteger | nullrequirednull for the Unassigned cost code row (uncoded posted actuals)
- lines[].codestringrequired
- lines[].namestringrequired
- lines[].eacBelowFloorbooleanrequired
- lines[].notBudgetedbooleanrequiredA project cost code with actuals or commitments but no budget line: shown with a budget of 0
- lines[].flagsstring[]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[].sourcesobject[]required
- lines[].explainobject[]required
- lines[].pmobject | nullrequiredLatest PM input dated on or before asOf for this cost code
Errors
403No accounting/entity access409Missing assignment, inconsistent sources, unsupported consumption, or unavailable historical revisions422Invalid project/entity/date
Example request
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/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.
Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
Request body
- project_idintegerrequired
- entity_idintegerrequired
- cost_code_idintegerrequired
- as_ofstring (date)required
- cost_to_completestring | nullrequired
- reasonstringrequired
- revisionintegerrequired
- methodstring | nullProjection 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_completestring | nullPhysical percent complete (percent_complete method).
- units_installedstring | nullUnits installed to date (unit_rate method).
- total_unitsstring | nullTotal units at completion (unit_rate method).
Response · 200
No response body.
Errors
403No write permission or read-only workspace409Stale revision or source coverage failure (reload before retrying), the date is in a soft- or hard-closed period, or WIP is posted through the date422Invalid money, date, code or reason
Example request
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/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.
Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
Request body
- project_idintegerrequired
- entity_idintegerrequired
- cost_code_idintegerrequired
- as_ofstring (date)required
- revisionintegerrequired
Response · 200 · object
- idintegerrequired
- revisionintegerrequired
- approvedAtstring (date-time)required
Errors
403No approval permission, segregation of duties, or read-only workspace404No PM input for that cost code on or before the date409Stale revision or source coverage failure (reload before retrying), the date is in a hard-closed period, or WIP is posted through the date422Invalid input
Example request
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/scopeList accessible projects, entities and source assignments
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
Response · 200
No response body.
Example request
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/scopeAssign a project's sources to one entity and base currency (unrestricted manageCoa permission)
Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
Request body
- project_idintegerrequired
- entity_idintegerrequired
- currencystringrequired
- reasonstringrequired
- confirm_project_sourcesbooleanrequired
Response · 201
No response body.
Errors
403Insufficient permission409Existing assignment, mixed entities or currency mismatch422Invalid input or missing confirmation
Example request
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/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.
Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
Request body
- project_idintegerrequired
- revenue_methodanyOne of: cost_to_cost, as_invoiced.
- retainage_conditionalbooleanRetainage is payable on completion or acceptance, not just time: presented as a contract asset on the WIP row
- reasonstringrequired
Response · 200
No response body.
Errors
403Insufficient permission or entity outside the grant404Project not assigned to an entity422Invalid input
Example request
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"
}'