Financial Reports
Read statements, budgets, aging, job profitability and supporting schedules; plan budgets, scenarios, cash forecasts and margin fade. 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 Financial Reports guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/budgetsList GL budgets - POST
/rest/v1.0/companies/{company_id}/accounting/budgetsImport a GL budget from CSV - GET
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}Show a GL budget with its lines - DELETE
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}Delete a GL budget version - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/approveApprove a budget version - PUT
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/cellsSet budget cells - GET
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/gridBudget grid - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/lockLock a budget version - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/returnReturn a budget version - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/spreadSpread a budget line - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/submitSubmit a budget version - GET
/rest/v1.0/companies/{company_id}/accounting/budgets/varianceBudget vs actual - POST
/rest/v1.0/companies/{company_id}/accounting/budgets/versionsCreate a budget version - POST
/rest/v1.0/companies/{company_id}/accounting/cecl_allowancePost the CECL allowance adjustment - POST
/rest/v1.0/companies/{company_id}/accounting/current_portion_reclassPost the current-portion reclass - GET
/rest/v1.0/companies/{company_id}/accounting/dashboardsMy accounting dashboard - PUT
/rest/v1.0/companies/{company_id}/accounting/dashboardsSave my dashboard layout - DELETE
/rest/v1.0/companies/{company_id}/accounting/dashboardsReset my dashboard - GET
/rest/v1.0/companies/{company_id}/accounting/dashboards/widgetsDashboard widgets and presets - GET
/rest/v1.0/companies/{company_id}/accounting/debt_schedulesList debt and lease schedules - POST
/rest/v1.0/companies/{company_id}/accounting/debt_schedulesCreate a debt or lease schedule - DELETE
/rest/v1.0/companies/{company_id}/accounting/debt_schedules/{id}Deactivate a debt or lease schedule - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecastCash forecast - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsList manual forecast lines - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsAdd a manual forecast line - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustments/{id}/voidVoid a manual forecast line - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/compareCompare cash scenarios - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/days_to_payCustomer days to pay - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsList cash forecast snapshots - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsStore a cash forecast snapshot - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}Show a cash forecast snapshot - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}/accuracyForecast vs actual - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fadeMargin fade portfolio - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/{id}Job margin history - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/captureCapture projected margins - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/scenariosList forecast scenarios - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/scenariosCreate a forecast scenario - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Show a forecast scenario - DELETE
/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Delete a forecast scenario - POST
/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustmentsAdd a scenario adjustment - DELETE
/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustments/{adjustment_id}Remove a scenario adjustment - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/compareCompare budget scenarios - GET
/rest/v1.0/companies/{company_id}/accounting/fpa/settingsFP&A settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/fpa/settingsUpdate FP&A settings - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitionsList report definitions - POST
/rest/v1.0/companies/{company_id}/accounting/report_definitionsSave a report definition - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Show a report definition - PATCH
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Update a report definition - DELETE
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Delete a report definition - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/exportExport a report definition - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/runRun a report definition - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/versionsReport definition versions - POST
/rest/v1.0/companies/{company_id}/accounting/report_definitions/previewPreview an unsaved definition - GET
/rest/v1.0/companies/{company_id}/accounting/report_definitions/sourcesReport builder data sources - GET
/rest/v1.0/companies/{company_id}/accounting/reportsReport library - GET
/rest/v1.0/companies/{company_id}/accounting/reports/{report_key}Run a report - GET
/rest/v1.0/companies/{company_id}/accounting/reports/{report_key}/exportExport a report
Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/budgetsList GL budgets
Every budget version, newest fiscal year first. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyVersion lifecycle (oas-fpa.json): only a draft changes or is deleted; approval needs a user who did not prepare it; a locked version never changes One of: draft, submitted, approved, locked.
- descriptionstring | null
- copy_sourcestring | nullblank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
- submitted_by_idinteger | null
- submitted_atstring | null (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- locked_by_idinteger | null
- locked_atstring | null (date-time)
- returned_reasonstring | null
- totalstringImport response only: sum of the imported amounts
- linesobject[]Show only (entity-scoped grants see their entities' lines)
- lines[].idintegerrequired
- lines[].account_idintegerrequired
- lines[].entity_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].project_idinteger | null
- lines[].cost_code_idinteger | null
- lines[].periodstringrequired
- lines[].amountstringrequiredNormal-balance sign: revenue and expense budgets are both positive; balance-sheet lines are month-end balances
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgetsImport a GL budget from CSV
CSV with a header row account,period,amount and optional entity (entity code) and department (department name, case-insensitive; the company departments journal lines carry). Accounts are postable income-statement accounts by number; period is YYYY-MM inside the fiscal year when it exists; amounts have at most two decimals and are positive for revenue and expense alike. Every bad row is reported at once (422). Importing the same fiscal year and name again creates the next version. Compare on the income statement with compare=budget&budget_id=. Needs close_period and unrestricted entity access; audited. Honors Idempotency-Key. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- budgetobjectrequired
- budget.fiscal_yearintegerrequired
- budget.namestringrequired
- budget.csvstringrequired
Response · 201 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyVersion lifecycle (oas-fpa.json): only a draft changes or is deleted; approval needs a user who did not prepare it; a locked version never changes One of: draft, submitted, approved, locked.
- descriptionstring | null
- copy_sourcestring | nullblank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
- submitted_by_idinteger | null
- submitted_atstring | null (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- locked_by_idinteger | null
- locked_atstring | null (date-time)
- returned_reasonstring | null
- totalstringImport response only: sum of the imported amounts
- linesobject[]Show only (entity-scoped grants see their entities' lines)
- lines[].idintegerrequired
- lines[].account_idintegerrequired
- lines[].entity_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].project_idinteger | null
- lines[].cost_code_idinteger | null
- lines[].periodstringrequired
- lines[].amountstringrequiredNormal-balance sign: revenue and expense budgets are both positive; balance-sheet lines are month-end balances
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"budget": {
"fiscal_year": 1,
"name": "string",
"csv": "string"
}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/budgets/{id}Show a GL budget with its lines
Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyVersion lifecycle (oas-fpa.json): only a draft changes or is deleted; approval needs a user who did not prepare it; a locked version never changes One of: draft, submitted, approved, locked.
- descriptionstring | null
- copy_sourcestring | nullblank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
- submitted_by_idinteger | null
- submitted_atstring | null (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- locked_by_idinteger | null
- locked_atstring | null (date-time)
- returned_reasonstring | null
- totalstringImport response only: sum of the imported amounts
- linesobject[]Show only (entity-scoped grants see their entities' lines)
- lines[].idintegerrequired
- lines[].account_idintegerrequired
- lines[].entity_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].project_idinteger | null
- lines[].cost_code_idinteger | null
- lines[].periodstringrequired
- lines[].amountstringrequiredNormal-balance sign: revenue and expense budgets are both positive; balance-sheet lines are month-end balances
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/budgets/{id}Delete a GL budget version
Needs close_period and unrestricted entity access; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/approveApprove a budget version
Approve a submitted version. Maker-checker: a user who created, edited or submitted the version is refused (403), also by a database trigger. The approved version is the default for budget vs actual and the income statement comparison. Needs approve_journal and unrestricted entity access; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyrequiredOne of: draft, submitted, approved, locked.
- descriptionstring | nullrequired
- copy_sourcestring | nullrequired
- submitted_by_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- locked_by_idinteger | nullrequired
- locked_atstring | null (date-time)required
- returned_reasonstring | nullrequired
- totalstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/approve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
PUT/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/cellsSet budget cells
Set cells of a draft version: each replaces every line on the same account, dimensions and month; amount 0 removes the cell. Accounts are postable accounts of any type (balance-sheet cells are month-end balances), periods are months of the version's fiscal year, a cost code needs its project. A submitted, approved or locked version is refused (409 budget_immutable). Needs close_period and unrestricted entity access; the editor joins the version's makers; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- cellsobject[]required
- cells[].account_idintegerrequired
- cells[].entity_idinteger | null
- cells[].department_idinteger | null
- cells[].project_idinteger | null
- cells[].cost_code_idinteger | null
- cells[].dimension_value_idinteger | null
- cells[].periodstringrequired
- cells[].amountstring | numberrequired
Response · 200 · object
- updatedintegerrequired
- net_changestringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/cells" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"cells": [
{
"account_id": 1,
"period": "string",
"amount": "0.00"
}
]
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/gridBudget grid
The version as rows (account plus entity, department, project and cost code) by fiscal month, with the net income budget per month. editable is true only for a draft. Filters: account_id, project_id, entity_id. An entity-scoped grant sees its entities' lines. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- account_idintegerquery
- project_idintegerquery
- entity_idintegerquery
Response · 200 · object
- budgetobjectrequired
- budget.idintegerrequired
- budget.fiscal_yearintegerrequired
- budget.namestringrequired
- budget.versionintegerrequired
- budget.line_countintegerrequired
- budget.created_by_idinteger | nullrequired
- budget.created_atstring (date-time)required
- budget.statusanyrequiredOne of: draft, submitted, approved, locked.
- budget.descriptionstring | nullrequired
- budget.copy_sourcestring | nullrequired
- budget.submitted_by_idinteger | nullrequired
- budget.submitted_atstring | null (date-time)required
- budget.approved_by_idinteger | nullrequired
- budget.approved_atstring | null (date-time)required
- budget.locked_by_idinteger | nullrequired
- budget.locked_atstring | null (date-time)required
- budget.returned_reasonstring | nullrequired
- budget.totalstring
- monthsstring[]required
- editablebooleanrequired
- rowsobject[]required
- rows[].keystringrequired
- rows[].accountobject | nullrequired
- rows[].kindanyrequiredOne of: income_statement, balance_sheet.
- rows[].entity_idinteger | nullrequired
- rows[].department_idinteger | nullrequired
- rows[].project_idinteger | nullrequired
- rows[].cost_code_idinteger | nullrequired
- rows[].dimension_value_idinteger | nullrequired
- rows[].amountsstring[]required
- rows[].totalstringrequiredIncome statement: the year's sum; balance sheet: the last month's balance
- totalsobjectrequired
- totals.income_statementstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/grid" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/lockLock a budget version
Lock an approved version: it can never change or be deleted (a trigger refuses any write). Needs close_period and unrestricted entity access; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyrequiredOne of: draft, submitted, approved, locked.
- descriptionstring | nullrequired
- copy_sourcestring | nullrequired
- submitted_by_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- locked_by_idinteger | nullrequired
- locked_atstring | null (date-time)required
- returned_reasonstring | nullrequired
- totalstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/lock" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/returnReturn a budget version
Send a submitted version back to draft with a reason. Needs approve_journal and unrestricted entity access; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyrequiredOne of: draft, submitted, approved, locked.
- descriptionstring | nullrequired
- copy_sourcestring | nullrequired
- submitted_by_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- locked_by_idinteger | nullrequired
- locked_atstring | null (date-time)required
- returned_reasonstring | nullrequired
- totalstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/return" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reason": "string"
}'Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/spreadSpread a budget line
Spread annual_amount over the fiscal year's months on one line of a draft: even, prior_year (the prior fiscal year's posted monthly activity on the same account and dimensions as weights; a negative month weighs zero; no activity is 422) or custom (twelve percents summing to 100). Each month takes the amount × weight ÷ Σ weights truncated to cents and the leftover cents go to the largest remainders, earlier months first, so the months add back exactly. Needs close_period; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- spreadobjectrequired
- spread.account_idintegerrequired
- spread.entity_idinteger | null
- spread.department_idinteger | null
- spread.project_idinteger | null
- spread.cost_code_idinteger | null
- spread.dimension_value_idinteger | null
- spread.annual_amountstring | numberrequired
- spread.methodanyrequiredOne of: even, prior_year, custom.
- spread.percents(string | number)[]
Response · 200 · object
- monthsobject[]required
- months[].periodstringrequired
- months[].amountstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/spread" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"spread": {
"account_id": 1,
"annual_amount": "0.00",
"method": "even"
}
}'Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/{id}/submitSubmit a budget version
Submit a draft with lines for approval; the submitter joins the makers. Needs close_period and unrestricted entity access; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyrequiredOne of: draft, submitted, approved, locked.
- descriptionstring | nullrequired
- copy_sourcestring | nullrequired
- submitted_by_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- locked_by_idinteger | nullrequired
- locked_atstring | null (date-time)required
- returned_reasonstring | nullrequired
- totalstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/1/submit" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/budgets/varianceBudget vs actual
Budget vs actual by account over whole months of one version: the approved (or locked) version of the fiscal year by default (latest approval), or budget_id. Income-statement rows compare the months' posted activity (closing entries left out) with the budget months; balance-sheet rows compare the posted balance at the last month's end with that month's budget balance. variance = actual − budget; variance_pct = variance ÷ |budget| × 100; favorable for revenue above budget and cost or expense below it. scenario_id compares against the scenario overlay of the version. An entity-scoped grant sees its entities only. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- budget_idintegerquery
- fiscal_yearintegerquery
- fromstringquery
- tostringquery
- entity_idintegerquery
- project_idintegerquery
- scenario_idintegerquery
Response · 200 · object
- budgetobjectrequired
- budget.idintegerrequired
- budget.fiscal_yearintegerrequired
- budget.namestringrequired
- budget.versionintegerrequired
- budget.line_countintegerrequired
- budget.created_by_idinteger | nullrequired
- budget.created_atstring (date-time)required
- budget.statusanyrequiredOne of: draft, submitted, approved, locked.
- budget.descriptionstring | nullrequired
- budget.copy_sourcestring | nullrequired
- budget.submitted_by_idinteger | nullrequired
- budget.submitted_atstring | null (date-time)required
- budget.approved_by_idinteger | nullrequired
- budget.approved_atstring | null (date-time)required
- budget.locked_by_idinteger | nullrequired
- budget.locked_atstring | null (date-time)required
- budget.returned_reasonstring | nullrequired
- budget.totalstring
- scenarioobject | nullrequired
- scenario.idintegerrequired
- scenario.namestringrequired
- monthsstring[]required
- entity_idinteger | nullrequired
- project_idinteger | nullrequired
- rowsobject[]required
- rows[].accountobjectrequired
- rows[].kindanyrequiredOne of: income_statement, balance_sheet.
- rows[].budgetstringrequired
- rows[].actualstringrequired
- rows[].variancestringrequired
- rows[].variance_pctstring | nullrequired
- rows[].favorableboolean | nullrequired
- rows[].by_monthobject[]required
- net_incomeobjectrequired
- net_income.budgetstringrequired
- net_income.actualstringrequired
- net_income.variancestringrequired
- explainobject[]required
- explain[].labelstringrequired
- explain[].formulastringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/variance" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/budgets/versionsCreate a budget version
A new draft version of the fiscal year and name (the next version number): blank, copied from another version (copy_from.kind version, optionally through a scenario overlay: the source version is not changed), or from a fiscal year's posted actuals (copy_from.kind actuals: income-statement activity by month, closing entries left out, or with accounts=all also balance-sheet month-end balances; factor_pct uplifts every amount). Month k of the source year lands on month k of the new year. Needs close_period and unrestricted entity access; audited. Honors Idempotency-Key. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- budgetobjectrequired
- budget.fiscal_yearintegerrequired
- budget.namestringrequired
- budget.descriptionstring | null
- budget.copy_fromobject
- budget.copy_from.kindanyrequired
Response · 201 · object
- idintegerrequired
- fiscal_yearintegerrequired
- namestringrequired
- versionintegerrequired
- line_countintegerrequired
- created_by_idinteger | nullrequired
- created_atstring (date-time)required
- statusanyrequiredOne of: draft, submitted, approved, locked.
- descriptionstring | nullrequired
- copy_sourcestring | nullrequired
- submitted_by_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- locked_by_idinteger | nullrequired
- locked_atstring | null (date-time)required
- returned_reasonstring | nullrequired
- totalstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/budgets/versions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"budget": {
"fiscal_year": 1,
"name": "string"
}
}'Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/cecl_allowancePost the CECL allowance adjustment
Computes expected credit losses (ASC 326-20) from settings.cecl_policy loss rates on aged AR, disputed AR, retainage receivable and contract assets for one entity, and posts the difference to the allowance (ALLOWANCE_DOUBTFUL) against credit loss expense (BAD_DEBT_EXPENSE). Idempotent per entity and date; 422 when no policy or role account is set. Needs post_journal. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- entity_idintegerrequired
- as_ofstring (date)required
Response · 200 · object
- entryobject | nullrequiredThe posted journal entry (JournalEntry fields), or null when nothing needed posting
- adjustmentstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace422Validation failed or refused
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/cecl_allowance" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity_id": 1,
"as_of": "2026-11-01"
}'Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/current_portion_reclassPost the current-portion reclass
Moves principal due within one year after as_of from each active schedule's long-term account to the current portion (ASC 210-10-45), on journal GJ, auto-reversing the next day. Idempotent per entity and date. 422 when no schedule exists, no current-portion account is mapped, the period is closed, or a schedule's current portion exceeds its account balance. Needs post_journal. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- entity_idintegerrequired
- as_ofstring (date)required
Response · 200 · object
- entryobject | nullrequiredThe posted journal entry (JournalEntry fields), or null when nothing needed posting
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].namestringrequired
- items[].currentstringrequired
- items[].noncurrentstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace422Validation failed or refused
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/current_portion_reclass" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"entity_id": 1,
"as_of": "2026-11-01"
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/dashboardsMy accounting dashboard
The caller's saved layout, else their role's preset (owner: CFO; controller, accountant, auditor, AR and payroll: controller; AP clerk; project manager), with each widget's data read with the caller's grant. Widgets the grant cannot read are left out and listed in hidden. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- presetanyqueryShow another preset's default layout instead of the saved one One of: cfo, controller, project_manager, ap_clerk.
- as_ofstring (date)queryDate the widgets read (default the company's today)
Response · 200 · object
- presetanyrequiredOne of: cfo, controller, project_manager, ap_clerk.
- customizedbooleanrequired
- as_ofstring | null (date)required
- hiddenstring[]requiredSaved widgets the caller's grant can no longer read (not shown)
- widgetsobject[]required
- widgets[].keystringrequired
- widgets[].sizeanyrequiredOne of: s, m, l.
- widgets[].titlestringrequired
- widgets[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- widgets[].dataobject | nullrequiredWidget data by kind: kpi {value, fmt, sub, tone, href}; trend {points}; bar {bars, fmt}; table {columns, rows}; aging {buckets, retainage, total}; list {items, empty}. Money is a 2-dp string; every href is the source page.
- widgets[].errorstring | nullrequired
- availableobject[]required
- available[].keystringrequired
- available[].titlestringrequired
- available[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- available[].descriptionstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope422Unknown preset or malformed as_of
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/dashboards" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
PUT/rest/v1.0/companies/{company_id}/accounting/dashboardsSave my dashboard layout
A preset plus up to 16 widgets in display order with their size. Every widget must be readable with the caller's grant. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- dashboardobjectrequired
- dashboard.presetanyrequiredOne of: cfo, controller, project_manager, ap_clerk.
- dashboard.widgetsobject[]required
- dashboard.widgets[].keystringrequired
- dashboard.widgets[].sizeanyOne of: s, m, l.
Response · 200 · object
- presetanyrequiredOne of: cfo, controller, project_manager, ap_clerk.
- customizedbooleanrequired
- as_ofstring | null (date)required
- hiddenstring[]requiredSaved widgets the caller's grant can no longer read (not shown)
- widgetsobject[]required
- widgets[].keystringrequired
- widgets[].sizeanyrequiredOne of: s, m, l.
- widgets[].titlestringrequired
- widgets[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- widgets[].dataobject | nullrequiredWidget data by kind: kpi {value, fmt, sub, tone, href}; trend {points}; bar {bars, fmt}; table {columns, rows}; aging {buckets, retainage, total}; list {items, empty}. Money is a 2-dp string; every href is the source page.
- widgets[].errorstring | nullrequired
- availableobject[]required
- available[].keystringrequired
- available[].titlestringrequired
- available[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- available[].descriptionstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope422Unknown widget, a widget the grant cannot read, or an unknown preset
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/dashboards" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"dashboard": {
"preset": "cfo",
"widgets": [
{
"key": "string"
}
]
}
}'Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/dashboardsReset my dashboard
Removes the saved layout (back to the role preset), or with preset saves that preset's default widgets. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- presetanyqueryPreset to reset to (default the role's) One of: cfo, controller, project_manager, ap_clerk.
Response · 200 · object
- presetanyrequiredOne of: cfo, controller, project_manager, ap_clerk.
- customizedbooleanrequired
- as_ofstring | null (date)required
- hiddenstring[]requiredSaved widgets the caller's grant can no longer read (not shown)
- widgetsobject[]required
- widgets[].keystringrequired
- widgets[].sizeanyrequiredOne of: s, m, l.
- widgets[].titlestringrequired
- widgets[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- widgets[].dataobject | nullrequiredWidget data by kind: kpi {value, fmt, sub, tone, href}; trend {points}; bar {bars, fmt}; table {columns, rows}; aging {buckets, retainage, total}; list {items, empty}. Money is a 2-dp string; every href is the source page.
- widgets[].errorstring | nullrequired
- availableobject[]required
- available[].keystringrequired
- available[].titlestringrequired
- available[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- available[].descriptionstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope422Unknown preset
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/dashboards" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/dashboards/widgetsDashboard widgets and presets
Widgets the caller's grant can read, and each role preset's widgets. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- widgetsobject[]required
- widgets[].keystringrequired
- widgets[].titlestringrequired
- widgets[].kindanyrequiredOne of: kpi, trend, bar, table, aging, list.
- widgets[].descriptionstringrequired
- presetsobject[]required
- presets[].keystringrequired
- presets[].titlestringrequired
- presets[].widgetsstring[]required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/dashboards/widgets" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/debt_schedulesList debt and lease schedules
Active principal maturity schedules, optionally for one entity. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- entity_idintegerquery
Response · 200 · object
- debt_schedulesobject[]required
- debt_schedules[].idintegerrequired
- debt_schedules[].entity_idintegerrequired
- debt_schedules[].namestringrequired
- debt_schedules[].kindanyrequiredOne of: note, lease.
- debt_schedules[].account_idintegerrequiredLong-term liability holding the principal
- debt_schedules[].current_account_idinteger | nullrequiredCurrent liability credited by the reclass; null = the CURRENT_PORTION_LTD role account
- debt_schedules[].paymentsobject[]required
- debt_schedules[].is_activebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace422Validation failed or refused
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/debt_schedules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/debt_schedulesCreate a debt or lease schedule
Principal maturities of a long-term note or lease liability, the source of the current-portion reclass. The account must be a postable long-term liability. Needs post_journal; audited. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- debt_scheduleobjectrequired
- debt_schedule.entity_idintegerrequired
- debt_schedule.namestringrequired
- debt_schedule.kindanyOne of: note, lease.
- debt_schedule.account_idintegerrequired
- debt_schedule.current_account_idinteger | null
- debt_schedule.paymentsobject[]required
- debt_schedule.payments[].due_datestring (date)required
- debt_schedule.payments[].principalstringrequiredPositive amount, at most 2 dp
Response · 201 · object
- debt_scheduleobjectrequired
- debt_schedule.idintegerrequired
- debt_schedule.entity_idintegerrequired
- debt_schedule.namestringrequired
- debt_schedule.kindanyrequiredOne of: note, lease.
- debt_schedule.account_idintegerrequiredLong-term liability holding the principal
- debt_schedule.current_account_idinteger | nullrequiredCurrent liability credited by the reclass; null = the CURRENT_PORTION_LTD role account
- debt_schedule.paymentsobject[]required
- debt_schedule.is_activebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace422Validation failed or refused
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/debt_schedules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"debt_schedule": {
"entity_id": 1,
"name": "string",
"account_id": 1,
"payments": [
{
"due_date": "2026-11-01",
"principal": "string"
}
]
}
}'Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/debt_schedules/{id}Deactivate a debt or lease schedule
Stops it feeding later reclasses (kept for the audit trail). Needs post_journal. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- deletedbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace404Not found422Validation failed or refused
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/debt_schedules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecastCash forecast
The job-aware rolling cash forecast: 13 weeks (granularity week) or 12 months (month) after as_of (default today). Opening = book balance of the non-card bank accounts in scope. Lines (each with its source document and basis): open AR on due date + the customer's days past due at payment; AR retainage at job completion + release days; pay apps not yet invoiced and the remaining prime contract spread to completion; open AP on due date or on the discount date at the discounted amount (policy); draft payment runs; AP retainage at completion; open commitments spread to completion on vendor terms; payroll (unposted runs, then the pay calendar at the recent average; payroll_view only); recurring journals; debt principal; lease payments; manual lines. scenario_id applies a scenario overlay. ties reconcile each source to its open items (in the horizon, beyond it, excluded). Banking-wide: an entity-scoped grant sees its entities. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- granularityanyqueryOne of: week, month.
- bucketsintegerquery
- scenario_idintegerquery
- entity_idintegerqueryOne entity of the grant's scope. The forecast is single-currency: a scope whose entities keep different functional currencies is refused (422) unless narrowed to one entity.
Response · 200 · object
- as_ofstring (date)required
- granularityanyrequiredOne of: week, month.
- horizon_endstring (date)required
- openingstringrequired
- inflowsstringrequired
- outflowsstringrequired
- closingstringrequired
- floorstring | nullrequired
- low_pointobject | nullrequired
- low_point.endstring (date)required
- low_point.balancestringrequired
- scenarioobject | nullrequired
- scenario.idintegerrequired
- scenario.namestringrequired
- scenario.kindstringrequired
- scenario.adjustmentsintegerrequired
- payroll_includedbooleanrequired
- entity_idsinteger[] | nullrequired
- accountsobject[]required
- accounts[].idintegerrequired
- accounts[].namestringrequired
- accounts[].gl_account_idintegerrequired
- accounts[].balancestringrequired
- bucketsobject[]required
- buckets[].indexintegerrequired
- buckets[].startstring (date)required
- buckets[].endstring (date)required
- buckets[].openingstringrequired
- buckets[].inflowsstringrequired
- buckets[].outflowsstringrequired
- buckets[].netstringrequired
- buckets[].closingstringrequired
- buckets[].below_floorbooleanrequired
- buckets[].by_sourceobjectrequired
- buckets[].linesobject[]required
- excludedobject[]required
- excluded[].sourceanyrequiredOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
- excluded[].reasonanyrequiredOne of: beyond_horizon, disputed, no_completion_date, unapplied_credit, vendor_credit, foreign_currency.
- excluded[].labelstringrequired
- excluded[].ref_typestring | nullrequired
- excluded[].ref_idinteger | nullrequired
- excluded[].amountstringrequired
- excluded[].datestring | null (date)required
- tiesobjectrequiredPer source: open items, the part inside the horizon and what is beyond it or excluded
- settingsobjectrequired
- settings.dtp_methodanyrequiredOne of: median, mean.
- settings.dtp_lookback_daysintegerrequired
- settings.honor_discountsbooleanrequired
- settings.customer_terms_daysintegerrequired
- settings.vendor_pay_daysintegerrequired
- settings.default_duration_monthsintegerrequired
- settings.retainage_release_daysintegerrequired
- settings.payroll_average_runsintegerrequired
- settings.fade_threshold_pctstringrequired
- settings.fade_threshold_amountstringrequired
- settings.savedbooleanrequiredFalse while the defaults apply
- explainobject[]required
- explain[].labelstringrequired
- explain[].formulastringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsList manual forecast lines
Manual cash forecast lines, voided ones included. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- datestring (date)required
- amountstringrequired
- reasonstringrequired
- entity_idinteger | nullrequired
- project_idinteger | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- voided_atstring | null (date-time)required
- voided_by_idinteger | nullrequired
- void_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/adjustments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsAdd a manual forecast line
A known receipt (positive) or payment (negative) dated after today with a reason. An entity-scoped grant must name one of its entities. Needs bank_reconcile; audited. Honors Idempotency-Key. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- adjustmentobjectrequired
- adjustment.datestring (date)required
- adjustment.amountstring | numberrequired
- adjustment.reasonstringrequired
- adjustment.entity_idinteger | null
- adjustment.project_idinteger | null
Response · 201 · object
- idintegerrequired
- datestring (date)required
- amountstringrequired
- reasonstringrequired
- entity_idinteger | nullrequired
- project_idinteger | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- voided_atstring | null (date-time)required
- voided_by_idinteger | nullrequired
- void_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/adjustments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"adjustment": {
"date": "2026-11-01",
"amount": "0.00",
"reason": "string"
}
}'Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustments/{id}/voidVoid a manual forecast line
Manual lines are never edited or deleted: a correction voids one with a reason. Needs bank_reconcile; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- datestring (date)required
- amountstringrequired
- reasonstringrequired
- entity_idinteger | nullrequired
- project_idinteger | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- voided_atstring | null (date-time)required
- voided_by_idinteger | nullrequired
- void_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/adjustments/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reason": "string"
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/compareCompare cash scenarios
The base forecast and each scenario overlay of the same lines (scenario_ids, comma-separated, at most 5): net and closing per bucket, totals and low points. A scenario never changes the base column. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- granularityanyqueryOne of: week, month.
- bucketsintegerquery
- scenario_idsstringqueryrequired
- entity_idintegerqueryOne entity of the grant's scope. The forecast is single-currency: a scope whose entities keep different functional currencies is refused (422) unless narrowed to one entity.
Response · 200 · object
- as_ofstring (date)required
- granularityanyrequiredOne of: week, month.
- openingstringrequired
- scenariosobject[]required
- scenarios[].idintegerrequired
- scenarios[].namestringrequired
- scenarios[].kindstringrequired
- bucketsobject[]required
- buckets[].indexintegerrequired
- buckets[].startstring (date)required
- buckets[].endstring (date)required
- buckets[].baseobjectrequired
- buckets[].scenariosobject[]required
- totalsobjectrequired
- totals.baseobjectrequired
- totals.scenariosobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/compare" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/days_to_payCustomer days to pay
Per customer (and all customers, customer_id null) from posted, unreversed receipt applications: invoices fully paid within the lookback window; days to pay = paid date − invoice date, days late = paid date − due date; mean and median rounded half up to whole days; lag_days is the configured statistic of days late, which shifts open invoices in the forecast. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- customer_idintegerquery
Response · 200 · object
- as_ofstring (date)required
- methodanyrequiredOne of: median, mean.
- lookback_daysintegerrequired
- customersobject[]required
- customers[].customer_idinteger | nullrequired
- customers[].customer_namestring | nullrequired
- customers[].countintegerrequired
- customers[].mean_days_to_payintegerrequired
- customers[].median_days_to_payintegerrequired
- customers[].mean_days_lateintegerrequired
- customers[].median_days_lateintegerrequired
- customers[].lag_daysintegerrequired
- customers[].samplesobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/days_to_pay" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsList cash forecast snapshots
Stored forecasts, newest first; an entity-scoped grant sees snapshots within its entities. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- as_ofstring (date)required
- granularityanyrequiredOne of: week, month.
- bucket_countintegerrequired
- scenario_idinteger | nullrequired
- entity_idsinteger[]required
- bank_gl_account_idsinteger[]required
- openingstringrequired
- inflowsstringrequired
- outflowsstringrequired
- closingstringrequired
- content_hashstringrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- paramsobjectrequired
- linesobject[]
- lines[].bucketintegerrequired
- lines[].datestring (date)required
- lines[].amountstringrequired
- lines[].sourceanyrequiredOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
- lines[].labelstringrequired
- lines[].ref_typestring | nullrequired
- lines[].ref_idinteger | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].party_idinteger | nullrequired
- lines[].basisstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/snapshots" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsStore a cash forecast snapshot
Stores today's forecast (as of the company's today) with every line, its basis and a content hash. Append-only: a database trigger refuses any update or delete. Needs bank_reconcile; audited. Honors Idempotency-Key. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- snapshotobjectrequired
- snapshot.namestring
- snapshot.granularityanyOne of: week, month.
- snapshot.bucketsinteger
- snapshot.scenario_idinteger | null
Response · 201 · object
- idintegerrequired
- namestringrequired
- as_ofstring (date)required
- granularityanyrequiredOne of: week, month.
- bucket_countintegerrequired
- scenario_idinteger | nullrequired
- entity_idsinteger[]required
- bank_gl_account_idsinteger[]required
- openingstringrequired
- inflowsstringrequired
- outflowsstringrequired
- closingstringrequired
- content_hashstringrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- paramsobjectrequired
- linesobject[]
- lines[].bucketintegerrequired
- lines[].datestring (date)required
- lines[].amountstringrequired
- lines[].sourceanyrequiredOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
- lines[].labelstringrequired
- lines[].ref_typestring | nullrequired
- lines[].ref_idinteger | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].party_idinteger | nullrequired
- lines[].basisstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/snapshots" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"snapshot": {}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}Show a cash forecast snapshot
With its stored lines. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- as_ofstring (date)required
- granularityanyrequiredOne of: week, month.
- bucket_countintegerrequired
- scenario_idinteger | nullrequired
- entity_idsinteger[]required
- bank_gl_account_idsinteger[]required
- openingstringrequired
- inflowsstringrequired
- outflowsstringrequired
- closingstringrequired
- content_hashstringrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- paramsobjectrequired
- linesobject[]
- lines[].bucketintegerrequired
- lines[].datestring (date)required
- lines[].amountstringrequired
- lines[].sourceanyrequiredOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
- lines[].labelstringrequired
- lines[].ref_typestring | nullrequired
- lines[].ref_idinteger | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].party_idinteger | nullrequired
- lines[].basisstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/snapshots/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}/accuracyForecast vs actual
For every bucket of the snapshot that has ended by as_of (default today): forecast in/out from the stored lines vs actual posted debits/credits to the snapshot's cash accounts in its entity scope (entries that only move cash between those accounts left out); error = actual net − forecast net, absolute percent error, forecast vs actual closing balance; summary bias, MAE and MAPE. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- as_ofstring (date)query
Response · 200 · object
- snapshotobjectrequired
- snapshot.idintegerrequired
- snapshot.namestringrequired
- snapshot.as_ofstring (date)required
- snapshot.granularityanyrequiredOne of: week, month.
- snapshot.bucket_countintegerrequired
- snapshot.scenario_idinteger | nullrequired
- snapshot.entity_idsinteger[]required
- snapshot.bank_gl_account_idsinteger[]required
- snapshot.openingstringrequired
- snapshot.inflowsstringrequired
- snapshot.outflowsstringrequired
- snapshot.closingstringrequired
- snapshot.content_hashstringrequired
- snapshot.created_by_idintegerrequired
- snapshot.created_atstring (date-time)required
- snapshot.paramsobjectrequired
- snapshot.linesobject[]
- as_ofstring (date)required
- pending_bucketsintegerrequired
- bucketsobject[]required
- buckets[].indexintegerrequired
- buckets[].startstring (date)required
- buckets[].endstring (date)required
- buckets[].forecast_instringrequired
- buckets[].forecast_outstringrequired
- buckets[].forecast_netstringrequired
- buckets[].actual_instringrequired
- buckets[].actual_outstringrequired
- buckets[].actual_netstringrequired
- buckets[].errorstringrequired
- buckets[].abs_errorstringrequired
- buckets[].abs_pct_errorstring | nullrequired
- buckets[].forecast_closingstringrequired
- buckets[].actual_closingstring | nullrequired
- summaryobjectrequired
- summary.bucketsintegerrequired
- summary.forecast_netstringrequired
- summary.actual_netstringrequired
- summary.biasstringrequired
- summary.maestring | nullrequired
- summary.mapestring | nullrequired
- explainobject[]required
- explain[].labelstringrequired
- explain[].formulastringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/cash_forecast/snapshots/1/accuracy" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fadeMargin fade portfolio
Every job with projected margin snapshots in scope (a project_manager_view grant: its own jobs): the latest margin, the change since the prior and the first snapshot, and fade flags against the FP&A thresholds (a fall of more than the percentage points or the amount). Faded jobs first. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- flaggedanyqueryOne of: true, false.
Response · 200 · object
- thresholdsobjectrequired
- thresholds.pctstringrequired
- thresholds.amountstringrequired
- summaryobjectrequired
- summary.jobsintegerrequired
- summary.fadedintegerrequired
- jobsobject[]required
- jobs[].project_idintegerrequired
- jobs[].namestringrequired
- jobs[].snapshotsintegerrequired
- jobs[].latestobject | nullrequired
- jobs[].vs_priorobject | nullrequired
- jobs[].vs_baselineobject | nullrequired
- jobs[].flagsany[]requiredOne of: fade_vs_prior, fade_vs_baseline.
- jobs[].fadedbooleanrequired
- jobs[].eventsintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/margin_fade" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/{id}Job margin history
One job's projected margin snapshots, the change since the prior and first snapshot, its fade flags and every threshold crossing (events). A project_manager_view grant reads its own jobs only. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequiredProject id
Response · 200 · object
- projectobjectrequired
- project.idintegerrequired
- project.namestringrequired
- thresholdsobjectrequired
- thresholds.pctstringrequired
- thresholds.amountstringrequired
- historyobject[]required
- history[].period_endstring (date)required
- history[].contract_valuestringrequired
- history[].eacstringrequired
- history[].projected_marginstringrequired
- history[].margin_pctstringrequired
- history[].sourceanyrequiredOne of: wip, forecast, import.
- history[].source_idinteger | nullrequired
- history[].captured_by_idintegerrequired
- vs_priorobject | nullrequired
- vs_prior.from_periodstring (date)required
- vs_prior.to_periodstring (date)required
- vs_prior.pct_pointsstringrequired
- vs_prior.amountstringrequired
- vs_prior.exceedsbooleanrequired
- vs_baselineobject | nullrequired
- vs_baseline.from_periodstring (date)required
- vs_baseline.to_periodstring (date)required
- vs_baseline.pct_pointsstringrequired
- vs_baseline.amountstringrequired
- vs_baseline.exceedsbooleanrequired
- flagsany[]requiredOne of: fade_vs_prior, fade_vs_baseline.
- fadedbooleanrequired
- eventsobject[]required
- events[].from_periodstring (date)required
- events[].to_periodstring (date)required
- events[].pct_pointsstringrequired
- events[].amountstringrequired
- events[].exceedsbooleanrequired
- explainobject[]required
- explain[].labelstringrequired
- explain[].formulastringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/margin_fade/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/captureCapture projected margins
Captures each job's projected margin at a past period end: the job's latest approved or posted WIP row for that period end (its EAC override when set), else its latest unsuperseded frozen PM forecast in that month with a known contract value. Append-only: a job already captured for the period keeps its snapshot. Needs close_period; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- period_endstring (date)required
Response · 200 · object
- period_endstring (date)required
- capturedobject[]required
- captured[].project_idintegerrequired
- captured[].sourceanyrequiredOne of: wip, forecast.
- skipped_project_idsinteger[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/margin_fade/capture" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"period_end": "2026-11-01"
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/scenariosList forecast scenarios
Named scenarios (base, upside, downside, custom) with their overlay adjustments. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- kindanyrequiredOne of: base, upside, downside, custom.
- descriptionstring | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- adjustmentsobject[]
- adjustments[].idintegerrequired
- adjustments[].scenario_idintegerrequired
- adjustments[].targetanyrequiredOne of: budget, cash.
- adjustments[].methodanyrequiredOne of: percent, amount, shift_days.
- adjustments[].valuestringrequired
- adjustments[].account_idinteger | nullrequired
- adjustments[].project_idinteger | nullrequired
- adjustments[].driverstring | nullrequired
- adjustments[].from_datestring | null (date)required
- adjustments[].to_datestring | null (date)required
- adjustments[].memostring | nullrequired
- adjustments[].created_by_idintegerrequired
- adjustments[].created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/scenariosCreate a forecast scenario
A scenario is a set of overlay adjustments, never a copy: target budget (by account and/or project: percent, or amount per month) or cash (by driver and/or project: percent, amount per bucket, or shift_days). Needs close_period and unrestricted entity access; audited. Honors Idempotency-Key. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- scenarioobjectrequired
- scenario.namestringrequired
- scenario.kindanyOne of: base, upside, downside, custom.
- scenario.descriptionstring | null
- scenario.adjustmentsobject[]
- scenario.adjustments[].targetanyrequiredOne of: budget, cash.
- scenario.adjustments[].methodanyrequiredOne of: percent, amount, shift_days.
- scenario.adjustments[].valuestring | numberrequiredPercent, amount or whole days
- scenario.adjustments[].account_idinteger | null
- scenario.adjustments[].project_idinteger | null
- scenario.adjustments[].driverstring | nullOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, null.
- scenario.adjustments[].from_datestring | null (date)
- scenario.adjustments[].to_datestring | null (date)
- scenario.adjustments[].memostring | null
Response · 201 · object
- idintegerrequired
- namestringrequired
- kindanyrequiredOne of: base, upside, downside, custom.
- descriptionstring | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- adjustmentsobject[]
- adjustments[].idintegerrequired
- adjustments[].scenario_idintegerrequired
- adjustments[].targetanyrequiredOne of: budget, cash.
- adjustments[].methodanyrequiredOne of: percent, amount, shift_days.
- adjustments[].valuestringrequired
- adjustments[].account_idinteger | nullrequired
- adjustments[].project_idinteger | nullrequired
- adjustments[].driverstring | nullrequired
- adjustments[].from_datestring | null (date)required
- adjustments[].to_datestring | null (date)required
- adjustments[].memostring | nullrequired
- adjustments[].created_by_idintegerrequired
- adjustments[].created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace409Conflict with the record's state422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"scenario": {
"name": "string"
}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Show a forecast scenario
Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- kindanyrequiredOne of: base, upside, downside, custom.
- descriptionstring | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- adjustmentsobject[]
- adjustments[].idintegerrequired
- adjustments[].scenario_idintegerrequired
- adjustments[].targetanyrequiredOne of: budget, cash.
- adjustments[].methodanyrequiredOne of: percent, amount, shift_days.
- adjustments[].valuestringrequired
- adjustments[].account_idinteger | nullrequired
- adjustments[].project_idinteger | nullrequired
- adjustments[].driverstring | nullrequired
- adjustments[].from_datestring | null (date)required
- adjustments[].to_datestring | null (date)required
- adjustments[].memostring | nullrequired
- adjustments[].created_by_idintegerrequired
- adjustments[].created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Delete a forecast scenario
Refused (409) while a stored cash forecast snapshot names it. Needs close_period; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409Conflict with the record's state
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustmentsAdd a scenario adjustment
Needs close_period; audited. Honors Idempotency-Key. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient 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
- adjustmentobjectrequired
- adjustment.targetanyrequiredOne of: budget, cash.
- adjustment.methodanyrequiredOne of: percent, amount, shift_days.
- adjustment.valuestring | numberrequiredPercent, amount or whole days
- adjustment.account_idinteger | null
- adjustment.project_idinteger | null
- adjustment.driverstring | nullOne of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, null.
- adjustment.from_datestring | null (date)
- adjustment.to_datestring | null (date)
- adjustment.memostring | null
Response · 201 · object
- idintegerrequired
- scenario_idintegerrequired
- targetanyrequiredOne of: budget, cash.
- methodanyrequiredOne of: percent, amount, shift_days.
- valuestringrequired
- account_idinteger | nullrequired
- project_idinteger | nullrequired
- driverstring | nullrequired
- from_datestring | null (date)required
- to_datestring | null (date)required
- memostring | nullrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios/1/adjustments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"adjustment": {
"target": "budget",
"method": "percent",
"value": "string"
}
}'Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustments/{adjustment_id}Remove a scenario adjustment
Needs close_period; audited. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- adjustment_idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios/1/adjustments/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/compareCompare budget scenarios
A budget version's fiscal-year totals per account against the overlay of each scenario (scenario_ids, comma-separated, at most 5), with net income per column. The version is read, never changed. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- budget_idintegerqueryrequired
- scenario_idsstringqueryrequired
Response · 200 · object
- budgetobjectrequired
- budget.idintegerrequired
- budget.fiscal_yearintegerrequired
- budget.namestringrequired
- budget.versionintegerrequired
- budget.line_countintegerrequired
- budget.created_by_idinteger | nullrequired
- budget.created_atstring (date-time)required
- budget.statusanyrequiredOne of: draft, submitted, approved, locked.
- budget.descriptionstring | nullrequired
- budget.copy_sourcestring | nullrequired
- budget.submitted_by_idinteger | nullrequired
- budget.submitted_atstring | null (date-time)required
- budget.approved_by_idinteger | nullrequired
- budget.approved_atstring | null (date-time)required
- budget.locked_by_idinteger | nullrequired
- budget.locked_atstring | null (date-time)required
- budget.returned_reasonstring | nullrequired
- budget.totalstring
- scenariosobject[]required
- scenarios[].idintegerrequired
- scenarios[].namestringrequired
- scenarios[].kindstringrequired
- rowsobject[]required
- rows[].accountobjectrequired
- rows[].basestringrequired
- rows[].scenariosobject[]required
- net_incomeobjectrequired
- net_income.basestringrequired
- net_income.scenariosobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/scenarios/compare" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/fpa/settingsFP&A settings
Cash forecast timing policy and margin fade thresholds (defaults until saved: saved false). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- dtp_methodanyrequiredOne of: median, mean.
- dtp_lookback_daysintegerrequired
- honor_discountsbooleanrequired
- customer_terms_daysintegerrequired
- vendor_pay_daysintegerrequired
- default_duration_monthsintegerrequired
- retainage_release_daysintegerrequired
- payroll_average_runsintegerrequired
- fade_threshold_pctstringrequired
- fade_threshold_amountstringrequired
- savedbooleanrequiredFalse while the defaults apply
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
PATCH/rest/v1.0/companies/{company_id}/accounting/fpa/settingsUpdate FP&A settings
Needs close_period and unrestricted entity access; audited with the diff. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- settingsobjectrequired
- settings.dtp_methodanyOne of: median, mean.
- settings.dtp_lookback_daysinteger
- settings.honor_discountsboolean
- settings.customer_terms_daysinteger
- settings.vendor_pay_daysinteger
- settings.default_duration_monthsinteger
- settings.retainage_release_daysinteger
- settings.payroll_average_runsinteger
- settings.fade_threshold_pctstring | number
- settings.fade_threshold_amountstring | number
Response · 200 · object
- dtp_methodanyrequiredOne of: median, mean.
- dtp_lookback_daysintegerrequired
- honor_discountsbooleanrequired
- customer_terms_daysintegerrequired
- vendor_pay_daysintegerrequired
- default_duration_monthsintegerrequired
- retainage_release_daysintegerrequired
- payroll_average_runsintegerrequired
- fade_threshold_pctstringrequired
- fade_threshold_amountstringrequired
- savedbooleanrequiredFalse while the defaults apply
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/fpa/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"settings": {}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitionsList report definitions
Definitions the caller may see: their own, shared with the company, and shared with their grant role. Paginated (Total, Per-Page, Link). Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- sourcestringqueryOnly this data source
- pageintegerqueryPage
- per_pageintegerqueryPage size
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- sourcestringrequired
- visibilityanyrequiredOne of: private, role, company.
- shared_rolesstring[]required
- versionintegerrequired
- owner_idintegerrequired
- owner_namestring | nullrequired
- can_editbooleanrequired
- specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- spec.base_reportstringsource=catalog: the report library key
- spec.columnsstring[]required
- spec.group_bystring[]
- spec.filtersobject[]
- spec.sortobject[]
- spec.compareanyOne of: none, prior_period, prior_year, budget.
- spec.subtotalsboolean
- spec.limitinteger | null
- spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/report_definitionsSave a report definition
Saves version 1, owned by the caller, private or shared with roles or the whole company. The spec is checked against the source's columns; data access is checked whenever it runs. Honors Idempotency-Key. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient 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
- report_definitionobjectrequired
- report_definition.namestringrequired
- report_definition.descriptionstring | null
- report_definition.visibilityanyOne of: private, role, company.
- report_definition.shared_rolesany[]One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- report_definition.specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- report_definition.spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- report_definition.spec.base_reportstringsource=catalog: the report library key
- report_definition.spec.columnsstring[]required
- report_definition.spec.group_bystring[]
- report_definition.spec.filtersobject[]
- report_definition.spec.filters[].fieldstringrequired
- report_definition.spec.filters[].opanyrequiredOne of: eq, in, not_in, gte, lte, contains.
- report_definition.spec.filters[].valuestring | string[]required
- report_definition.spec.sortobject[]
- report_definition.spec.sort[].fieldstringrequired
- report_definition.spec.sort[].diranyOne of: asc, desc.
- report_definition.spec.compareanyOne of: none, prior_period, prior_year, budget.
- report_definition.spec.subtotalsboolean
- report_definition.spec.limitinteger | null
- report_definition.spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
Response · 201 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- sourcestringrequired
- visibilityanyrequiredOne of: private, role, company.
- shared_rolesstring[]required
- versionintegerrequired
- owner_idintegerrequired
- owner_namestring | nullrequired
- can_editbooleanrequired
- specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- spec.base_reportstringsource=catalog: the report library key
- spec.columnsstring[]required
- spec.group_bystring[]
- spec.filtersobject[]
- spec.sortobject[]
- spec.compareanyOne of: none, prior_period, prior_year, budget.
- spec.subtotalsboolean
- spec.limitinteger | null
- spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Unknown library report or budget422Invalid spec (unknown column, grouping or comparison), name or sharing
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"report_definition": {
"name": "string",
"spec": {
"source": "gl_detail",
"columns": []
}
}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Show a report definition
A definition the caller may see (404 otherwise). Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- sourcestringrequired
- visibilityanyrequiredOne of: private, role, company.
- shared_rolesstring[]required
- versionintegerrequired
- owner_idintegerrequired
- owner_namestring | nullrequired
- can_editbooleanrequired
- specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- spec.base_reportstringsource=catalog: the report library key
- spec.columnsstring[]required
- spec.group_bystring[]
- spec.filtersobject[]
- spec.sortobject[]
- spec.compareanyOne of: none, prior_period, prior_year, budget.
- spec.subtotalsboolean
- spec.limitinteger | null
- spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Not found or not shared with the caller
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
PATCH/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Update a report definition
Owner or company administrator only. Every save is a new version (the previous one stays in versions). Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- report_definitionobjectrequired
- report_definition.namestring
- report_definition.descriptionstring | null
- report_definition.visibilityanyOne of: private, role, company.
- report_definition.shared_rolesany[]One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- report_definition.specobjectColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- report_definition.spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- report_definition.spec.base_reportstringsource=catalog: the report library key
- report_definition.spec.columnsstring[]required
- report_definition.spec.group_bystring[]
- report_definition.spec.filtersobject[]
- report_definition.spec.filters[].fieldstringrequired
- report_definition.spec.filters[].opanyrequiredOne of: eq, in, not_in, gte, lte, contains.
- report_definition.spec.filters[].valuestring | string[]required
- report_definition.spec.sortobject[]
- report_definition.spec.sort[].fieldstringrequired
- report_definition.spec.sort[].diranyOne of: asc, desc.
- report_definition.spec.compareanyOne of: none, prior_period, prior_year, budget.
- report_definition.spec.subtotalsboolean
- report_definition.spec.limitinteger | null
- report_definition.spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- sourcestringrequired
- visibilityanyrequiredOne of: private, role, company.
- shared_rolesstring[]required
- versionintegerrequired
- owner_idintegerrequired
- owner_namestring | nullrequired
- can_editbooleanrequired
- specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- spec.base_reportstringsource=catalog: the report library key
- spec.columnsstring[]required
- spec.group_bystring[]
- spec.filtersobject[]
- spec.sortobject[]
- spec.compareanyOne of: none, prior_period, prior_year, budget.
- spec.subtotalsboolean
- spec.limitinteger | null
- spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403Not the owner, or no accounting access404Not found or not shared with the caller422Invalid spec, name or sharing
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"report_definition": {}
}'Accounting / Financial Reports
DELETE/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Delete a report definition
Owner or company administrator only; its versions go with it. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403Not the owner, or no accounting access404Not found or not shared with the caller
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/exportExport a report definition
The run's output as CSV, XLSX or PDF, with the report library's encoders, per-user rate limit and export audit. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- formatanyqueryFile format (default csv) One of: csv, xlsx, pdf.
- as_ofstring (date)queryBalance date (as-of sources); overrides the saved parameter
- fromstring (date)queryStart of the activity range; overrides the saved parameter
- tostring (date)queryEnd of the activity range; overrides the saved parameter
- entity_idintegerqueryEntity (must be inside the caller's grant)
- project_idintegerqueryJob (must be inside the caller's grant)
- department_idintegerqueryDepartment
- budget_idintegerqueryGL budget for compare=budget
- basisanyqueryAging basis for open-item sources One of: due, document.
- versionintegerqueryRun an earlier saved version
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Not found or not shared with the caller422Unknown format or invalid parameter429Export rate limit reached (Retry-After)
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1/export" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/runRun a report definition
Runs the definition as the caller: their grant's entities and projects scope every row, whoever owns or shared it. Query parameters override the saved ones. checks prove the grouped rows add back to the base total (and the comparison column to its own base). Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- as_ofstring (date)queryBalance date (as-of sources); overrides the saved parameter
- fromstring (date)queryStart of the activity range; overrides the saved parameter
- tostring (date)queryEnd of the activity range; overrides the saved parameter
- entity_idintegerqueryEntity (must be inside the caller's grant)
- project_idintegerqueryJob (must be inside the caller's grant)
- department_idintegerqueryDepartment
- budget_idintegerqueryGL budget for compare=budget
- basisanyqueryAging basis for open-item sources One of: due, document.
- versionintegerqueryRun an earlier saved version
Response · 200 · object
- keystringrequired
- titlestringrequired
- subtitlestringrequiredDates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
- paramsobjectrequired
- columnsobject[]required
- columns[].keystringrequired
- columns[].labelstringrequired
- columns[].fmtanyrequiredOne of: text, money, pct, int, date.
- rowsobject[]required
- rows[].idstringrequired
- rows[].kindanyrequiredOne of: header, line, account, subtotal, total, detail, note.
- rows[].depthintegerrequired
- rows[].cellsobjectrequired
- rows[].hrefstring | nullIn-app drill-down link
- rows[].cellHrefsobjectPer-cell drill-down links (column key to in-app link) for pivot and comparison columns
- rows[].toneanyOne of: ok, warn, risk, null.
- checksobject[]required
- checks[].labelstringrequired
- checks[].okbooleanrequired
- checks[].differencestringrequiredA money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
- checks[].detailstring | null
- notesstring[]required
- explainobject[]required
- explain[].labelstringrequired
- explain[].valuestringrequired
- explain[].formulastring
- explain[].citestring
- generatedAtstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a source the grant cannot read (AP/AR, cash or budget for a project-scoped grant)404Not found, not shared with the caller, or an entity, job or budget outside the grant422Invalid parameter, or too many detail lines
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1/run" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/versionsReport definition versions
Every saved version, newest first. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- versionintegerrequired
- namestringrequired
- sourcestringrequired
- specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- spec.base_reportstringsource=catalog: the report library key
- spec.columnsstring[]required
- spec.group_bystring[]
- spec.filtersobject[]
- spec.sortobject[]
- spec.compareanyOne of: none, prior_period, prior_year, budget.
- spec.subtotalsboolean
- spec.limitinteger | null
- spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
- created_by_idintegerrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Not found or not shared with the caller
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/1/versions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
POST/rest/v1.0/companies/{company_id}/accounting/report_definitions/previewPreview an unsaved definition
Runs a spec without saving it (the builder's live preview), scoped by the caller's grant. Reads only: accounting:read is enough. Query parameters override the spec's saved parameters.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)queryBalance date (as-of sources); overrides the saved parameter
- fromstring (date)queryStart of the activity range; overrides the saved parameter
- tostring (date)queryEnd of the activity range; overrides the saved parameter
- entity_idintegerqueryEntity (must be inside the caller's grant)
- project_idintegerqueryJob (must be inside the caller's grant)
- department_idintegerqueryDepartment
- budget_idintegerqueryGL budget for compare=budget
- basisanyqueryAging basis for open-item sources One of: due, document.
Request body
- report_definitionobjectrequired
- report_definition.specobjectrequiredColumns, groupings (nested, at most three), filters, sort, comparison, subtotals, row limit and saved report parameters. Field keys are the source's column keys (GET report_definitions/sources); a `dimension:<id>` key is a registered user-defined dimension.
- report_definition.spec.sourceanyrequiredOne of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
- report_definition.spec.base_reportstringsource=catalog: the report library key
- report_definition.spec.columnsstring[]required
- report_definition.spec.group_bystring[]
- report_definition.spec.filtersobject[]
- report_definition.spec.filters[].fieldstringrequired
- report_definition.spec.filters[].opanyrequiredOne of: eq, in, not_in, gte, lte, contains.
- report_definition.spec.filters[].valuestring | string[]required
- report_definition.spec.sortobject[]
- report_definition.spec.sort[].fieldstringrequired
- report_definition.spec.sort[].diranyOne of: asc, desc.
- report_definition.spec.compareanyOne of: none, prior_period, prior_year, budget.
- report_definition.spec.subtotalsboolean
- report_definition.spec.limitinteger | null
- report_definition.spec.paramsobjectSaved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
Response · 200 · object
- keystringrequired
- titlestringrequired
- subtitlestringrequiredDates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
- paramsobjectrequired
- columnsobject[]required
- columns[].keystringrequired
- columns[].labelstringrequired
- columns[].fmtanyrequiredOne of: text, money, pct, int, date.
- rowsobject[]required
- rows[].idstringrequired
- rows[].kindanyrequiredOne of: header, line, account, subtotal, total, detail, note.
- rows[].depthintegerrequired
- rows[].cellsobjectrequired
- rows[].hrefstring | nullIn-app drill-down link
- rows[].cellHrefsobjectPer-cell drill-down links (column key to in-app link) for pivot and comparison columns
- rows[].toneanyOne of: ok, warn, risk, null.
- checksobject[]required
- checks[].labelstringrequired
- checks[].okbooleanrequired
- checks[].differencestringrequiredA money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
- checks[].detailstring | null
- notesstring[]required
- explainobject[]required
- explain[].labelstringrequired
- explain[].valuestringrequired
- explain[].formulastring
- explain[].citestring
- generatedAtstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a source the grant cannot read (AP/AR, cash or budget for a project-scoped grant)404Entity, job, budget or report outside the grant or company422Invalid spec or parameter, or too many detail lines
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/preview" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"report_definition": {
"spec": {
"source": "gl_detail",
"columns": []
}
}
}'Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/report_definitions/sourcesReport builder data sources
The whitelisted sources (GL lines, trial balance, cash, AP/AR open items, job cost, job cost entries, library reports) with their columns, groupable dimensions, amounts and comparisons. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- keystringrequired
- titlestringrequired
- descriptionstringrequired
- paramsstring[]required
- columnsobject[]required
- columns[].keystringrequired
- columns[].labelstringrequired
- columns[].roleanyrequiredOne of: dim, attr, measure.
- columns[].fmtanyrequiredOne of: text, money, pct, int, date.
- columns[].groupableboolean
- columns[].compareany[]One of: prior_period, prior_year, budget.
- default_columnsstring[]required
- default_group_bystring[]required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/report_definitions/sources" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/reportsReport library
Every report with its group and accepted parameters. Requires the accounting:read scope and an accounting grant.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- keyanyrequiredOne of: balance_sheet, income_statement, cash_flow, equity_roll_forward, trial_balance, general_ledger, journal, ar_aging, ar_overview, cash_receipts, ar_collection_effectiveness, ar_dso, ar_promise_kept_rate, ar_dispute_aging, sales_tax_liability, ap_aging, check_register, cash_requirements, match_exception_aging, job_cost_status, job_cost_detail, committed_cost, retainage_by_job, job_profitability, payroll_register, subledger_reconciliation, integrity_check, manual_je_review, sod_conflicts, access_sod, vendor_changes, pii_reveals, audit_log, fixed_asset_roll_forward, reconciliation_status, close_progress, flux_analysis, cutover_reconciliation, wip_schedule, completed_contracts, wip_gl_reconciliation, backlog_roll_forward, cecl_allowance.
- titlestringrequired
- groupstringrequired
- descriptionstringrequired
- paramsany[]requiredOne of: as_of, from, to, adj_from, compare, budget_id, columns, entity_id, project_id, department_id, account_id, journal, basis, include_zero, jtd, rollup, actor_id, item_type, action.
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a project-scoped (project_manager_view) grant on an entity-wide report (AR/AP aging, AR overview, subledger reconciliation, ledger integrity, CECL allowance, asset roll-forward, audit log)404Unknown report, or an entity or account outside this company422Malformed parameter
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/reports" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/reports/{report_key}Run a report
Balance sheet, income statement (comparative or by month, quarter, entity, department or job), indirect cash flow, trial balance worksheet (unadjusted, adjustments, adjusted, closing, post-closing), GL detail, journal, AR/AP aging as of a date, job profitability, subledger reconciliation, the integrity check, the surety package (completed contracts, WIP to GL reconciliation, backlog roll-forward) and the CECL allowance. The cash flow statement ends with supplemental interest and income taxes paid and the noncash schedule (entries tagged noncash); the balance sheet presents receivables net of the allowance, and the loss provision and the current portion of long-term debt on their own lines. checks are the report's own proofs (assets = liabilities + equity, debits = credits, cash flow ties to cash). Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- report_keyanypathrequiredReport key One of: balance_sheet, income_statement, cash_flow, equity_roll_forward, trial_balance, general_ledger, journal, ar_aging, ar_overview, cash_receipts, ar_collection_effectiveness, ar_dso, ar_promise_kept_rate, ar_dispute_aging, sales_tax_liability, ap_aging, check_register, cash_requirements, match_exception_aging, job_cost_status, job_cost_detail, committed_cost, retainage_by_job, job_profitability, payroll_register, subledger_reconciliation, integrity_check, manual_je_review, sod_conflicts, access_sod, vendor_changes, pii_reveals, audit_log, fixed_asset_roll_forward, reconciliation_status, close_progress, flux_analysis, cutover_reconciliation, wip_schedule, completed_contracts, wip_gl_reconciliation, backlog_roll_forward, cecl_allowance.
- as_ofstring (date)queryBalance date (default `to`, else today)
- fromstring (date)queryStart of the activity range (default the start of the fiscal year holding `to`)
- tostring (date)queryEnd of the activity range (default today)
- adj_fromstring (date)queryTrial balance worksheet: start of the adjustments and closing window (default the start of the fiscal period holding `as_of`); income and expense adjustments before the fiscal year start roll into retained earnings. For trial_balance a `from` sent without `adj_from` is read as `adj_from` (deprecated alias)
- compareanyqueryComparative column (balance sheet, income statement, cash flow; the cash flow's prior column has its own opening balances). `budget` (income statement only) adds Budget and Variance (actual - budget, per account and row) columns for `budget_id`. One of: none, prior_period, prior_year, budget.
- budget_idintegerqueryWith compare=budget: the GL budget version to compare with
- columnsanyqueryIncome statement columns; the balance sheet takes total or entity. Entity columns end with Eliminations (the elimination entity) and Consolidated. Month and quarter views allow at most 36 periods; narrow the date range or choose total columns for longer ranges. Entity, department and job views show at most 50 columns: past that, the values with the least revenue are combined in an All other column. One of: total, month, quarter, entity, department, project, dimension.
- entity_idintegerqueryOne entity (within the grant entities)
- project_idintegerqueryOne job
- department_idintegerqueryOne department
- dimensionstringqueryUser-defined dimension code (or id) to group by: trial_balance becomes one net column per value plus No <dimension> and Total (checked against the ungrouped trial balance), general_ledger adds the line's value as a column, and income_statement with columns=dimension pivots by value.
- dimension_levelintegerqueryRoll grouped values up to this hierarchy level (1 = top-level values); omitted = the posted value.
- dimension_value_idsstringqueryComma-separated dimension value ids: lines carrying one of them or a child value (values of one dimension OR, dimensions AND).
- account_idintegerqueryOne account (general ledger)
- journalanyqueryOne journal (journal report) One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- basisanyqueryAging basis One of: due, document.
- include_zeroanyqueryAlso show rows with no balance One of: true, false.
- jtdstringqueryJob profitability: job to date through `to` (ignores `from`) One of: true, false.
- actor_idintegerqueryAudit log: only events by this user
- item_typestringqueryAudit log: only events on this accounting record type (e.g. AcctAccount)
- actionstringqueryAudit log: only events with this action (e.g. updated)
- rollupstringqueryBalance sheet and income statement: group account rows under their parent account with a subtotal row One of: true, false.
Response · 200 · object
- keyanyrequiredOne of: balance_sheet, income_statement, cash_flow, equity_roll_forward, trial_balance, general_ledger, journal, ar_aging, ar_overview, cash_receipts, ar_collection_effectiveness, ar_dso, ar_promise_kept_rate, ar_dispute_aging, sales_tax_liability, ap_aging, check_register, cash_requirements, match_exception_aging, job_cost_status, job_cost_detail, committed_cost, retainage_by_job, job_profitability, payroll_register, subledger_reconciliation, integrity_check, manual_je_review, sod_conflicts, access_sod, vendor_changes, pii_reveals, audit_log, fixed_asset_roll_forward, reconciliation_status, close_progress, flux_analysis, cutover_reconciliation, wip_schedule, completed_contracts, wip_gl_reconciliation, backlog_roll_forward, cecl_allowance.
- titlestringrequired
- subtitlestringrequiredDates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
- paramsobjectrequired
- columnsobject[]required
- columns[].keystringrequired
- columns[].labelstringrequired
- columns[].fmtanyrequiredOne of: text, money, pct, int, date.
- rowsobject[]required
- rows[].idstringrequired
- rows[].kindanyrequiredOne of: header, line, account, subtotal, total, detail, note.
- rows[].depthintegerrequired
- rows[].cellsobjectrequired
- rows[].hrefstring | nullIn-app drill-down link
- rows[].cellHrefsobjectPer-cell drill-down links (column key to in-app link) for pivot and comparison columns
- rows[].toneanyOne of: ok, warn, risk, null.
- checksobject[]required
- checks[].labelstringrequired
- checks[].okbooleanrequired
- checks[].differencestringrequiredA money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
- checks[].detailstring | null
- notesstring[]required
- explainobject[]required
- explain[].labelstringrequired
- explain[].valuestringrequired
- explain[].formulastring
- explain[].citestring
- generatedAtstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a project-scoped (project_manager_view) grant on an entity-wide report (AR/AP aging, AR overview, subledger reconciliation, ledger integrity, CECL allowance, asset roll-forward, audit log)404Unknown report, or an entity or account outside this company422Malformed parameter429Company heavy-read budget spent (ACCT_HEAVY_BUDGET units per minute); retry after the Retry-After seconds
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/reports/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Financial Reports
GET/rest/v1.0/companies/{company_id}/accounting/reports/{report_key}/exportExport a report
The same report as a CSV, XLSX or PDF download. Rate-limited per user (429 with Retry-After) and recorded in the audit log. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- report_keyanypathrequiredReport key One of: balance_sheet, income_statement, cash_flow, equity_roll_forward, trial_balance, general_ledger, journal, ar_aging, ar_overview, cash_receipts, ar_collection_effectiveness, ar_dso, ar_promise_kept_rate, ar_dispute_aging, sales_tax_liability, ap_aging, check_register, cash_requirements, match_exception_aging, job_cost_status, job_cost_detail, committed_cost, retainage_by_job, job_profitability, payroll_register, subledger_reconciliation, integrity_check, manual_je_review, sod_conflicts, access_sod, vendor_changes, pii_reveals, audit_log, fixed_asset_roll_forward, reconciliation_status, close_progress, flux_analysis, cutover_reconciliation, wip_schedule, completed_contracts, wip_gl_reconciliation, backlog_roll_forward, cecl_allowance.
- formatanyqueryFile format (default csv) One of: csv, xlsx, pdf.
- as_ofstring (date)queryBalance date (default `to`, else today)
- fromstring (date)queryStart of the activity range (default the start of the fiscal year holding `to`)
- tostring (date)queryEnd of the activity range (default today)
- adj_fromstring (date)queryTrial balance worksheet: start of the adjustments and closing window (default the start of the fiscal period holding `as_of`); income and expense adjustments before the fiscal year start roll into retained earnings. For trial_balance a `from` sent without `adj_from` is read as `adj_from` (deprecated alias)
- compareanyqueryComparative column (balance sheet, income statement, cash flow; the cash flow's prior column has its own opening balances). `budget` (income statement only) adds Budget and Variance (actual - budget, per account and row) columns for `budget_id`. One of: none, prior_period, prior_year, budget.
- budget_idintegerqueryWith compare=budget: the GL budget version to compare with
- columnsanyqueryIncome statement columns; the balance sheet takes total or entity. Entity columns end with Eliminations (the elimination entity) and Consolidated. Month and quarter views allow at most 36 periods; narrow the date range or choose total columns for longer ranges. Entity, department and job views show at most 50 columns: past that, the values with the least revenue are combined in an All other column. One of: total, month, quarter, entity, department, project, dimension.
- entity_idintegerqueryOne entity (within the grant entities)
- project_idintegerqueryOne job
- department_idintegerqueryOne department
- dimensionstringqueryUser-defined dimension code (or id) to group by: trial_balance becomes one net column per value plus No <dimension> and Total (checked against the ungrouped trial balance), general_ledger adds the line's value as a column, and income_statement with columns=dimension pivots by value.
- dimension_levelintegerqueryRoll grouped values up to this hierarchy level (1 = top-level values); omitted = the posted value.
- dimension_value_idsstringqueryComma-separated dimension value ids: lines carrying one of them or a child value (values of one dimension OR, dimensions AND).
- account_idintegerqueryOne account (general ledger)
- journalanyqueryOne journal (journal report) One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- basisanyqueryAging basis One of: due, document.
- include_zeroanyqueryAlso show rows with no balance One of: true, false.
- jtdstringqueryJob profitability: job to date through `to` (ignores `from`) One of: true, false.
- actor_idintegerqueryAudit log: only events by this user
- item_typestringqueryAudit log: only events on this accounting record type (e.g. AcctAccount)
- actionstringqueryAudit log: only events with this action (e.g. updated)
- rollupstringqueryBalance sheet and income statement: group account rows under their parent account with a subtotal row One of: true, false.
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a project-scoped (project_manager_view) grant on an entity-wide report (AR/AP aging, AR overview, subledger reconciliation, ledger integrity, CECL allowance, asset roll-forward, audit log)404Unknown report, or an entity or account outside this company422Malformed parameter429Export limit reached, or the company heavy-read budget is spent; retry after the Retry-After seconds
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/reports/1/export" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"