Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · Reporting and close

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.

57 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/budgetsList GL budgets
  2. POST /rest/v1.0/companies/{company_id}/accounting/budgetsImport a GL budget from CSV
  3. GET /rest/v1.0/companies/{company_id}/accounting/budgets/{id}Show a GL budget with its lines
  4. DELETE /rest/v1.0/companies/{company_id}/accounting/budgets/{id}Delete a GL budget version
  5. POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/approveApprove a budget version
  6. PUT /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/cellsSet budget cells
  7. GET /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/gridBudget grid
  8. POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/lockLock a budget version
  9. POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/returnReturn a budget version
  10. POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/spreadSpread a budget line
  11. POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/submitSubmit a budget version
  12. GET /rest/v1.0/companies/{company_id}/accounting/budgets/varianceBudget vs actual
  13. POST /rest/v1.0/companies/{company_id}/accounting/budgets/versionsCreate a budget version
  14. POST /rest/v1.0/companies/{company_id}/accounting/cecl_allowancePost the CECL allowance adjustment
  15. POST /rest/v1.0/companies/{company_id}/accounting/current_portion_reclassPost the current-portion reclass
  16. GET /rest/v1.0/companies/{company_id}/accounting/dashboardsMy accounting dashboard
  17. PUT /rest/v1.0/companies/{company_id}/accounting/dashboardsSave my dashboard layout
  18. DELETE /rest/v1.0/companies/{company_id}/accounting/dashboardsReset my dashboard
  19. GET /rest/v1.0/companies/{company_id}/accounting/dashboards/widgetsDashboard widgets and presets
  20. GET /rest/v1.0/companies/{company_id}/accounting/debt_schedulesList debt and lease schedules
  21. POST /rest/v1.0/companies/{company_id}/accounting/debt_schedulesCreate a debt or lease schedule
  22. DELETE /rest/v1.0/companies/{company_id}/accounting/debt_schedules/{id}Deactivate a debt or lease schedule
  23. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecastCash forecast
  24. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsList manual forecast lines
  25. POST /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustmentsAdd a manual forecast line
  26. POST /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/adjustments/{id}/voidVoid a manual forecast line
  27. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/compareCompare cash scenarios
  28. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/days_to_payCustomer days to pay
  29. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsList cash forecast snapshots
  30. POST /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshotsStore a cash forecast snapshot
  31. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}Show a cash forecast snapshot
  32. GET /rest/v1.0/companies/{company_id}/accounting/fpa/cash_forecast/snapshots/{id}/accuracyForecast vs actual
  33. GET /rest/v1.0/companies/{company_id}/accounting/fpa/margin_fadeMargin fade portfolio
  34. GET /rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/{id}Job margin history
  35. POST /rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/captureCapture projected margins
  36. GET /rest/v1.0/companies/{company_id}/accounting/fpa/scenariosList forecast scenarios
  37. POST /rest/v1.0/companies/{company_id}/accounting/fpa/scenariosCreate a forecast scenario
  38. GET /rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Show a forecast scenario
  39. DELETE /rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}Delete a forecast scenario
  40. POST /rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustmentsAdd a scenario adjustment
  41. DELETE /rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/{id}/adjustments/{adjustment_id}Remove a scenario adjustment
  42. GET /rest/v1.0/companies/{company_id}/accounting/fpa/scenarios/compareCompare budget scenarios
  43. GET /rest/v1.0/companies/{company_id}/accounting/fpa/settingsFP&A settings
  44. PATCH /rest/v1.0/companies/{company_id}/accounting/fpa/settingsUpdate FP&A settings
  45. GET /rest/v1.0/companies/{company_id}/accounting/report_definitionsList report definitions
  46. POST /rest/v1.0/companies/{company_id}/accounting/report_definitionsSave a report definition
  47. GET /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Show a report definition
  48. PATCH /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Update a report definition
  49. DELETE /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}Delete a report definition
  50. GET /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/exportExport a report definition
  51. GET /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/runRun a report definition
  52. GET /rest/v1.0/companies/{company_id}/accounting/report_definitions/{id}/versionsReport definition versions
  53. POST /rest/v1.0/companies/{company_id}/accounting/report_definitions/previewPreview an unsaved definition
  54. GET /rest/v1.0/companies/{company_id}/accounting/report_definitions/sourcesReport builder data sources
  55. GET /rest/v1.0/companies/{company_id}/accounting/reportsReport library
  56. GET /rest/v1.0/companies/{company_id}/accounting/reports/{report_key}Run a report
  57. 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/budgets

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    any
    Version 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.
  • description
    string | null
  • copy_source
    string | null
    blank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
  • submitted_by_id
    integer | null
  • submitted_at
    string | null (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • locked_by_id
    integer | null
  • locked_at
    string | null (date-time)
  • returned_reason
    string | null
  • total
    string
    Import response only: sum of the imported amounts
  • lines
    object[]
    Show only (entity-scoped grants see their entities' lines)
  • lines[].id
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].entity_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].project_id
    integer | null
  • lines[].cost_code_id
    integer | null
  • lines[].period
    stringrequired
  • lines[].amount
    stringrequired
    Normal-balance sign: revenue and expense budgets are both positive; balance-sheet lines are month-end balances

Errors

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

Example request

Generated from the contractcurl
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/budgets

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

v1.0Implemented

Parameters

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

Request body

  • budget
    objectrequired
  • budget.fiscal_year
    integerrequired
  • budget.name
    stringrequired
  • budget.csv
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    any
    Version 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.
  • description
    string | null
  • copy_source
    string | null
    blank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
  • submitted_by_id
    integer | null
  • submitted_at
    string | null (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • locked_by_id
    integer | null
  • locked_at
    string | null (date-time)
  • returned_reason
    string | null
  • total
    string
    Import response only: sum of the imported amounts
  • lines
    object[]
    Show only (entity-scoped grants see their entities' lines)
  • lines[].id
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].entity_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].project_id
    integer | null
  • lines[].cost_code_id
    integer | null
  • lines[].period
    stringrequired
  • lines[].amount
    stringrequired
    Normal-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 token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed (field errors) or the ledger refused the change (message list)

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    any
    Version 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.
  • description
    string | null
  • copy_source
    string | null
    blank, csv, version:<id>[+scenario:<id>] or actuals:<fiscal year>[x<pct>%]
  • submitted_by_id
    integer | null
  • submitted_at
    string | null (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • locked_by_id
    integer | null
  • locked_at
    string | null (date-time)
  • returned_reason
    string | null
  • total
    string
    Import response only: sum of the imported amounts
  • lines
    object[]
    Show only (entity-scoped grants see their entities' lines)
  • lines[].id
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].entity_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].project_id
    integer | null
  • lines[].cost_code_id
    integer | null
  • lines[].period
    stringrequired
  • lines[].amount
    stringrequired
    Normal-balance sign: revenue and expense budgets are both positive; balance-sheet lines are month-end balances

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 400Malformed JSON body, or the request was refused by a business rule (message list)
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed (field errors) or the ledger refused the change (message list)

Example request

Generated from the contractcurl
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}/approve

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    anyrequired
    One of: draft, submitted, approved, locked.
  • description
    string | nullrequired
  • copy_source
    string | nullrequired
  • submitted_by_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • locked_by_id
    integer | nullrequired
  • locked_at
    string | null (date-time)required
  • returned_reason
    string | nullrequired
  • total
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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}/cells

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

v1.0Implemented

Parameters

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

Request body

  • cells
    object[]required
  • cells[].account_id
    integerrequired
  • cells[].entity_id
    integer | null
  • cells[].department_id
    integer | null
  • cells[].project_id
    integer | null
  • cells[].cost_code_id
    integer | null
  • cells[].dimension_value_id
    integer | null
  • cells[].period
    stringrequired
  • cells[].amount
    string | numberrequired

Response · 200 · object

  • updated
    integerrequired
  • net_change
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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}/grid

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • account_id
    integerquery
  • project_id
    integerquery
  • entity_id
    integerquery

Response · 200 · object

  • budget
    objectrequired
  • budget.id
    integerrequired
  • budget.fiscal_year
    integerrequired
  • budget.name
    stringrequired
  • budget.version
    integerrequired
  • budget.line_count
    integerrequired
  • budget.created_by_id
    integer | nullrequired
  • budget.created_at
    string (date-time)required
  • budget.status
    anyrequired
    One of: draft, submitted, approved, locked.
  • budget.description
    string | nullrequired
  • budget.copy_source
    string | nullrequired
  • budget.submitted_by_id
    integer | nullrequired
  • budget.submitted_at
    string | null (date-time)required
  • budget.approved_by_id
    integer | nullrequired
  • budget.approved_at
    string | null (date-time)required
  • budget.locked_by_id
    integer | nullrequired
  • budget.locked_at
    string | null (date-time)required
  • budget.returned_reason
    string | nullrequired
  • budget.total
    string
  • months
    string[]required
  • editable
    booleanrequired
  • rows
    object[]required
  • rows[].key
    stringrequired
  • rows[].account
    object | nullrequired
  • rows[].kind
    anyrequired
    One of: income_statement, balance_sheet.
  • rows[].entity_id
    integer | nullrequired
  • rows[].department_id
    integer | nullrequired
  • rows[].project_id
    integer | nullrequired
  • rows[].cost_code_id
    integer | nullrequired
  • rows[].dimension_value_id
    integer | nullrequired
  • rows[].amounts
    string[]required
  • rows[].total
    stringrequired
    Income statement: the year's sum; balance sheet: the last month's balance
  • totals
    objectrequired
  • totals.income_statement
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Financial Reports

POST /rest/v1.0/companies/{company_id}/accounting/budgets/{id}/lock

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    anyrequired
    One of: draft, submitted, approved, locked.
  • description
    string | nullrequired
  • copy_source
    string | nullrequired
  • submitted_by_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • locked_by_id
    integer | nullrequired
  • locked_at
    string | null (date-time)required
  • returned_reason
    string | nullrequired
  • total
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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}/return

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

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    anyrequired
    One of: draft, submitted, approved, locked.
  • description
    string | nullrequired
  • copy_source
    string | nullrequired
  • submitted_by_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • locked_by_id
    integer | nullrequired
  • locked_at
    string | null (date-time)required
  • returned_reason
    string | nullrequired
  • total
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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}/spread

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

v1.0Implemented

Parameters

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

Request body

  • spread
    objectrequired
  • spread.account_id
    integerrequired
  • spread.entity_id
    integer | null
  • spread.department_id
    integer | null
  • spread.project_id
    integer | null
  • spread.cost_code_id
    integer | null
  • spread.dimension_value_id
    integer | null
  • spread.annual_amount
    string | numberrequired
  • spread.method
    anyrequired
    One of: even, prior_year, custom.
  • spread.percents
    (string | number)[]

Response · 200 · object

  • months
    object[]required
  • months[].period
    stringrequired
  • months[].amount
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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}/submit

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    anyrequired
    One of: draft, submitted, approved, locked.
  • description
    string | nullrequired
  • copy_source
    string | nullrequired
  • submitted_by_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • locked_by_id
    integer | nullrequired
  • locked_at
    string | null (date-time)required
  • returned_reason
    string | nullrequired
  • total
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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/variance

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • budget_id
    integerquery
  • fiscal_year
    integerquery
  • from
    stringquery
  • to
    stringquery
  • entity_id
    integerquery
  • project_id
    integerquery
  • scenario_id
    integerquery

Response · 200 · object

  • budget
    objectrequired
  • budget.id
    integerrequired
  • budget.fiscal_year
    integerrequired
  • budget.name
    stringrequired
  • budget.version
    integerrequired
  • budget.line_count
    integerrequired
  • budget.created_by_id
    integer | nullrequired
  • budget.created_at
    string (date-time)required
  • budget.status
    anyrequired
    One of: draft, submitted, approved, locked.
  • budget.description
    string | nullrequired
  • budget.copy_source
    string | nullrequired
  • budget.submitted_by_id
    integer | nullrequired
  • budget.submitted_at
    string | null (date-time)required
  • budget.approved_by_id
    integer | nullrequired
  • budget.approved_at
    string | null (date-time)required
  • budget.locked_by_id
    integer | nullrequired
  • budget.locked_at
    string | null (date-time)required
  • budget.returned_reason
    string | nullrequired
  • budget.total
    string
  • scenario
    object | nullrequired
  • scenario.id
    integerrequired
  • scenario.name
    stringrequired
  • months
    string[]required
  • entity_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • rows
    object[]required
  • rows[].account
    objectrequired
  • rows[].kind
    anyrequired
    One of: income_statement, balance_sheet.
  • rows[].budget
    stringrequired
  • rows[].actual
    stringrequired
  • rows[].variance
    stringrequired
  • rows[].variance_pct
    string | nullrequired
  • rows[].favorable
    boolean | nullrequired
  • rows[].by_month
    object[]required
  • net_income
    objectrequired
  • net_income.budget
    stringrequired
  • net_income.actual
    stringrequired
  • net_income.variance
    stringrequired
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].formula
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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/versions

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

v1.0Implemented

Parameters

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

Request body

  • budget
    objectrequired
  • budget.fiscal_year
    integerrequired
  • budget.name
    stringrequired
  • budget.description
    string | null
  • budget.copy_from
    object
  • budget.copy_from.kind
    anyrequired

Response · 201 · object

  • id
    integerrequired
  • fiscal_year
    integerrequired
  • name
    stringrequired
  • version
    integerrequired
  • line_count
    integerrequired
  • created_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • status
    anyrequired
    One of: draft, submitted, approved, locked.
  • description
    string | nullrequired
  • copy_source
    string | nullrequired
  • submitted_by_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • locked_by_id
    integer | nullrequired
  • locked_at
    string | null (date-time)required
  • returned_reason
    string | nullrequired
  • total
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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_allowance

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

v1.0Implemented

Parameters

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

Request body

  • entity_id
    integerrequired
  • as_of
    string (date)required

Response · 200 · object

  • entry
    object | nullrequired
    The posted journal entry (JournalEntry fields), or null when nothing needed posting
  • adjustment
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace
  • 422Validation failed or refused

Example request

Generated from the contractcurl
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_reclass

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

v1.0Implemented

Parameters

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

Request body

  • entity_id
    integerrequired
  • as_of
    string (date)required

Response · 200 · object

  • entry
    object | nullrequired
    The posted journal entry (JournalEntry fields), or null when nothing needed posting
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].name
    stringrequired
  • items[].current
    stringrequired
  • items[].noncurrent
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace
  • 422Validation failed or refused

Example request

Generated from the contractcurl
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/dashboards

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • preset
    anyquery
    Show another preset's default layout instead of the saved one One of: cfo, controller, project_manager, ap_clerk.
  • as_of
    string (date)query
    Date the widgets read (default the company's today)

Response · 200 · object

  • preset
    anyrequired
    One of: cfo, controller, project_manager, ap_clerk.
  • customized
    booleanrequired
  • as_of
    string | null (date)required
  • hidden
    string[]required
    Saved widgets the caller's grant can no longer read (not shown)
  • widgets
    object[]required
  • widgets[].key
    stringrequired
  • widgets[].size
    anyrequired
    One of: s, m, l.
  • widgets[].title
    stringrequired
  • widgets[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • widgets[].data
    object | nullrequired
    Widget 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[].error
    string | nullrequired
  • available
    object[]required
  • available[].key
    stringrequired
  • available[].title
    stringrequired
  • available[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • available[].description
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 422Unknown preset or malformed as_of

Example request

Generated from the contractcurl
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/dashboards

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

v1.0Implemented

Parameters

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

Request body

  • dashboard
    objectrequired
  • dashboard.preset
    anyrequired
    One of: cfo, controller, project_manager, ap_clerk.
  • dashboard.widgets
    object[]required
  • dashboard.widgets[].key
    stringrequired
  • dashboard.widgets[].size
    any
    One of: s, m, l.

Response · 200 · object

  • preset
    anyrequired
    One of: cfo, controller, project_manager, ap_clerk.
  • customized
    booleanrequired
  • as_of
    string | null (date)required
  • hidden
    string[]required
    Saved widgets the caller's grant can no longer read (not shown)
  • widgets
    object[]required
  • widgets[].key
    stringrequired
  • widgets[].size
    anyrequired
    One of: s, m, l.
  • widgets[].title
    stringrequired
  • widgets[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • widgets[].data
    object | nullrequired
    Widget 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[].error
    string | nullrequired
  • available
    object[]required
  • available[].key
    stringrequired
  • available[].title
    stringrequired
  • available[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • available[].description
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 422Unknown widget, a widget the grant cannot read, or an unknown preset

Example request

Generated from the contractcurl
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/dashboards

Reset my dashboard

Removes the saved layout (back to the role preset), or with preset saves that preset's default widgets. Requires accounting:write.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • preset
    anyquery
    Preset to reset to (default the role's) One of: cfo, controller, project_manager, ap_clerk.

Response · 200 · object

  • preset
    anyrequired
    One of: cfo, controller, project_manager, ap_clerk.
  • customized
    booleanrequired
  • as_of
    string | null (date)required
  • hidden
    string[]required
    Saved widgets the caller's grant can no longer read (not shown)
  • widgets
    object[]required
  • widgets[].key
    stringrequired
  • widgets[].size
    anyrequired
    One of: s, m, l.
  • widgets[].title
    stringrequired
  • widgets[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • widgets[].data
    object | nullrequired
    Widget 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[].error
    string | nullrequired
  • available
    object[]required
  • available[].key
    stringrequired
  • available[].title
    stringrequired
  • available[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • available[].description
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 422Unknown preset

Example request

Generated from the contractcurl
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/widgets

Dashboard widgets and presets

Widgets the caller's grant can read, and each role preset's widgets. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • widgets
    object[]required
  • widgets[].key
    stringrequired
  • widgets[].title
    stringrequired
  • widgets[].kind
    anyrequired
    One of: kpi, trend, bar, table, aging, list.
  • widgets[].description
    stringrequired
  • presets
    object[]required
  • presets[].key
    stringrequired
  • presets[].title
    stringrequired
  • presets[].widgets
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

Generated from the contractcurl
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_schedules

List debt and lease schedules

Active principal maturity schedules, optionally for one entity. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • debt_schedules
    object[]required
  • debt_schedules[].id
    integerrequired
  • debt_schedules[].entity_id
    integerrequired
  • debt_schedules[].name
    stringrequired
  • debt_schedules[].kind
    anyrequired
    One of: note, lease.
  • debt_schedules[].account_id
    integerrequired
    Long-term liability holding the principal
  • debt_schedules[].current_account_id
    integer | nullrequired
    Current liability credited by the reclass; null = the CURRENT_PORTION_LTD role account
  • debt_schedules[].payments
    object[]required
  • debt_schedules[].is_active
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace
  • 422Validation failed or refused

Example request

Generated from the contractcurl
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_schedules

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

v1.0Implemented

Parameters

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

Request body

  • debt_schedule
    objectrequired
  • debt_schedule.entity_id
    integerrequired
  • debt_schedule.name
    stringrequired
  • debt_schedule.kind
    any
    One of: note, lease.
  • debt_schedule.account_id
    integerrequired
  • debt_schedule.current_account_id
    integer | null
  • debt_schedule.payments
    object[]required
  • debt_schedule.payments[].due_date
    string (date)required
  • debt_schedule.payments[].principal
    stringrequired
    Positive amount, at most 2 dp

Response · 201 · object

  • debt_schedule
    objectrequired
  • debt_schedule.id
    integerrequired
  • debt_schedule.entity_id
    integerrequired
  • debt_schedule.name
    stringrequired
  • debt_schedule.kind
    anyrequired
    One of: note, lease.
  • debt_schedule.account_id
    integerrequired
    Long-term liability holding the principal
  • debt_schedule.current_account_id
    integer | nullrequired
    Current liability credited by the reclass; null = the CURRENT_PORTION_LTD role account
  • debt_schedule.payments
    object[]required
  • debt_schedule.is_active
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace
  • 422Validation failed or refused

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • deleted
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, entity outside the grant, wrong company, or read-only workspace
  • 404Not found
  • 422Validation failed or refused

Example request

Generated from the contractcurl
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_forecast

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • granularity
    anyquery
    One of: week, month.
  • buckets
    integerquery
  • scenario_id
    integerquery
  • entity_id
    integerquery
    One 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_of
    string (date)required
  • granularity
    anyrequired
    One of: week, month.
  • horizon_end
    string (date)required
  • opening
    stringrequired
  • inflows
    stringrequired
  • outflows
    stringrequired
  • closing
    stringrequired
  • floor
    string | nullrequired
  • low_point
    object | nullrequired
  • low_point.end
    string (date)required
  • low_point.balance
    stringrequired
  • scenario
    object | nullrequired
  • scenario.id
    integerrequired
  • scenario.name
    stringrequired
  • scenario.kind
    stringrequired
  • scenario.adjustments
    integerrequired
  • payroll_included
    booleanrequired
  • entity_ids
    integer[] | nullrequired
  • accounts
    object[]required
  • accounts[].id
    integerrequired
  • accounts[].name
    stringrequired
  • accounts[].gl_account_id
    integerrequired
  • accounts[].balance
    stringrequired
  • buckets
    object[]required
  • buckets[].index
    integerrequired
  • buckets[].start
    string (date)required
  • buckets[].end
    string (date)required
  • buckets[].opening
    stringrequired
  • buckets[].inflows
    stringrequired
  • buckets[].outflows
    stringrequired
  • buckets[].net
    stringrequired
  • buckets[].closing
    stringrequired
  • buckets[].below_floor
    booleanrequired
  • buckets[].by_source
    objectrequired
  • buckets[].lines
    object[]required
  • excluded
    object[]required
  • excluded[].source
    anyrequired
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
  • excluded[].reason
    anyrequired
    One of: beyond_horizon, disputed, no_completion_date, unapplied_credit, vendor_credit, foreign_currency.
  • excluded[].label
    stringrequired
  • excluded[].ref_type
    string | nullrequired
  • excluded[].ref_id
    integer | nullrequired
  • excluded[].amount
    stringrequired
  • excluded[].date
    string | null (date)required
  • ties
    objectrequired
    Per source: open items, the part inside the horizon and what is beyond it or excluded
  • settings
    objectrequired
  • settings.dtp_method
    anyrequired
    One of: median, mean.
  • settings.dtp_lookback_days
    integerrequired
  • settings.honor_discounts
    booleanrequired
  • settings.customer_terms_days
    integerrequired
  • settings.vendor_pay_days
    integerrequired
  • settings.default_duration_months
    integerrequired
  • settings.retainage_release_days
    integerrequired
  • settings.payroll_average_runs
    integerrequired
  • settings.fade_threshold_pct
    stringrequired
  • settings.fade_threshold_amount
    stringrequired
  • settings.saved
    booleanrequired
    False while the defaults apply
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].formula
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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/adjustments

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • date
    string (date)required
  • amount
    stringrequired
  • reason
    stringrequired
  • entity_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • voided_at
    string | null (date-time)required
  • voided_by_id
    integer | nullrequired
  • void_reason
    string | nullrequired

Errors

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

Example request

Generated from the contractcurl
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/adjustments

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

v1.0Implemented

Parameters

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

Request body

  • adjustment
    objectrequired
  • adjustment.date
    string (date)required
  • adjustment.amount
    string | numberrequired
  • adjustment.reason
    stringrequired
  • adjustment.entity_id
    integer | null
  • adjustment.project_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • date
    string (date)required
  • amount
    stringrequired
  • reason
    stringrequired
  • entity_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • voided_at
    string | null (date-time)required
  • voided_by_id
    integer | nullrequired
  • void_reason
    string | nullrequired

Errors

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

Example request

Generated from the contractcurl
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}/void

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

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • date
    string (date)required
  • amount
    stringrequired
  • reason
    stringrequired
  • entity_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • voided_at
    string | null (date-time)required
  • voided_by_id
    integer | nullrequired
  • void_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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/compare

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • granularity
    anyquery
    One of: week, month.
  • buckets
    integerquery
  • scenario_ids
    stringqueryrequired
  • entity_id
    integerquery
    One 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_of
    string (date)required
  • granularity
    anyrequired
    One of: week, month.
  • opening
    stringrequired
  • scenarios
    object[]required
  • scenarios[].id
    integerrequired
  • scenarios[].name
    stringrequired
  • scenarios[].kind
    stringrequired
  • buckets
    object[]required
  • buckets[].index
    integerrequired
  • buckets[].start
    string (date)required
  • buckets[].end
    string (date)required
  • buckets[].base
    objectrequired
  • buckets[].scenarios
    object[]required
  • totals
    objectrequired
  • totals.base
    objectrequired
  • totals.scenarios
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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_pay

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • customer_id
    integerquery

Response · 200 · object

  • as_of
    string (date)required
  • method
    anyrequired
    One of: median, mean.
  • lookback_days
    integerrequired
  • customers
    object[]required
  • customers[].customer_id
    integer | nullrequired
  • customers[].customer_name
    string | nullrequired
  • customers[].count
    integerrequired
  • customers[].mean_days_to_pay
    integerrequired
  • customers[].median_days_to_pay
    integerrequired
  • customers[].mean_days_late
    integerrequired
  • customers[].median_days_late
    integerrequired
  • customers[].lag_days
    integerrequired
  • customers[].samples
    object[]required

Errors

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

Example request

Generated from the contractcurl
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/snapshots

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • as_of
    string (date)required
  • granularity
    anyrequired
    One of: week, month.
  • bucket_count
    integerrequired
  • scenario_id
    integer | nullrequired
  • entity_ids
    integer[]required
  • bank_gl_account_ids
    integer[]required
  • opening
    stringrequired
  • inflows
    stringrequired
  • outflows
    stringrequired
  • closing
    stringrequired
  • content_hash
    stringrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • params
    objectrequired
  • lines
    object[]
  • lines[].bucket
    integerrequired
  • lines[].date
    string (date)required
  • lines[].amount
    stringrequired
  • lines[].source
    anyrequired
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
  • lines[].label
    stringrequired
  • lines[].ref_type
    string | nullrequired
  • lines[].ref_id
    integer | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].party_id
    integer | nullrequired
  • lines[].basis
    stringrequired

Errors

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

Example request

Generated from the contractcurl
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/snapshots

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

v1.0Implemented

Parameters

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

Request body

  • snapshot
    objectrequired
  • snapshot.name
    string
  • snapshot.granularity
    any
    One of: week, month.
  • snapshot.buckets
    integer
  • snapshot.scenario_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • as_of
    string (date)required
  • granularity
    anyrequired
    One of: week, month.
  • bucket_count
    integerrequired
  • scenario_id
    integer | nullrequired
  • entity_ids
    integer[]required
  • bank_gl_account_ids
    integer[]required
  • opening
    stringrequired
  • inflows
    stringrequired
  • outflows
    stringrequired
  • closing
    stringrequired
  • content_hash
    stringrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • params
    objectrequired
  • lines
    object[]
  • lines[].bucket
    integerrequired
  • lines[].date
    string (date)required
  • lines[].amount
    stringrequired
  • lines[].source
    anyrequired
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
  • lines[].label
    stringrequired
  • lines[].ref_type
    string | nullrequired
  • lines[].ref_id
    integer | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].party_id
    integer | nullrequired
  • lines[].basis
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • as_of
    string (date)required
  • granularity
    anyrequired
    One of: week, month.
  • bucket_count
    integerrequired
  • scenario_id
    integer | nullrequired
  • entity_ids
    integer[]required
  • bank_gl_account_ids
    integer[]required
  • opening
    stringrequired
  • inflows
    stringrequired
  • outflows
    stringrequired
  • closing
    stringrequired
  • content_hash
    stringrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • params
    objectrequired
  • lines
    object[]
  • lines[].bucket
    integerrequired
  • lines[].date
    string (date)required
  • lines[].amount
    stringrequired
  • lines[].source
    anyrequired
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, scenario.
  • lines[].label
    stringrequired
  • lines[].ref_type
    string | nullrequired
  • lines[].ref_id
    integer | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].party_id
    integer | nullrequired
  • lines[].basis
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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}/accuracy

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • as_of
    string (date)query

Response · 200 · object

  • snapshot
    objectrequired
  • snapshot.id
    integerrequired
  • snapshot.name
    stringrequired
  • snapshot.as_of
    string (date)required
  • snapshot.granularity
    anyrequired
    One of: week, month.
  • snapshot.bucket_count
    integerrequired
  • snapshot.scenario_id
    integer | nullrequired
  • snapshot.entity_ids
    integer[]required
  • snapshot.bank_gl_account_ids
    integer[]required
  • snapshot.opening
    stringrequired
  • snapshot.inflows
    stringrequired
  • snapshot.outflows
    stringrequired
  • snapshot.closing
    stringrequired
  • snapshot.content_hash
    stringrequired
  • snapshot.created_by_id
    integerrequired
  • snapshot.created_at
    string (date-time)required
  • snapshot.params
    objectrequired
  • snapshot.lines
    object[]
  • as_of
    string (date)required
  • pending_buckets
    integerrequired
  • buckets
    object[]required
  • buckets[].index
    integerrequired
  • buckets[].start
    string (date)required
  • buckets[].end
    string (date)required
  • buckets[].forecast_in
    stringrequired
  • buckets[].forecast_out
    stringrequired
  • buckets[].forecast_net
    stringrequired
  • buckets[].actual_in
    stringrequired
  • buckets[].actual_out
    stringrequired
  • buckets[].actual_net
    stringrequired
  • buckets[].error
    stringrequired
  • buckets[].abs_error
    stringrequired
  • buckets[].abs_pct_error
    string | nullrequired
  • buckets[].forecast_closing
    stringrequired
  • buckets[].actual_closing
    string | nullrequired
  • summary
    objectrequired
  • summary.buckets
    integerrequired
  • summary.forecast_net
    stringrequired
  • summary.actual_net
    stringrequired
  • summary.bias
    stringrequired
  • summary.mae
    string | nullrequired
  • summary.mape
    string | nullrequired
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].formula
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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_fade

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
  • flagged
    anyquery
    One of: true, false.

Response · 200 · object

  • thresholds
    objectrequired
  • thresholds.pct
    stringrequired
  • thresholds.amount
    stringrequired
  • summary
    objectrequired
  • summary.jobs
    integerrequired
  • summary.faded
    integerrequired
  • jobs
    object[]required
  • jobs[].project_id
    integerrequired
  • jobs[].name
    stringrequired
  • jobs[].snapshots
    integerrequired
  • jobs[].latest
    object | nullrequired
  • jobs[].vs_prior
    object | nullrequired
  • jobs[].vs_baseline
    object | nullrequired
  • jobs[].flags
    any[]required
    One of: fade_vs_prior, fade_vs_baseline.
  • jobs[].faded
    booleanrequired
  • jobs[].events
    integerrequired

Errors

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

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • project
    objectrequired
  • project.id
    integerrequired
  • project.name
    stringrequired
  • thresholds
    objectrequired
  • thresholds.pct
    stringrequired
  • thresholds.amount
    stringrequired
  • history
    object[]required
  • history[].period_end
    string (date)required
  • history[].contract_value
    stringrequired
  • history[].eac
    stringrequired
  • history[].projected_margin
    stringrequired
  • history[].margin_pct
    stringrequired
  • history[].source
    anyrequired
    One of: wip, forecast, import.
  • history[].source_id
    integer | nullrequired
  • history[].captured_by_id
    integerrequired
  • vs_prior
    object | nullrequired
  • vs_prior.from_period
    string (date)required
  • vs_prior.to_period
    string (date)required
  • vs_prior.pct_points
    stringrequired
  • vs_prior.amount
    stringrequired
  • vs_prior.exceeds
    booleanrequired
  • vs_baseline
    object | nullrequired
  • vs_baseline.from_period
    string (date)required
  • vs_baseline.to_period
    string (date)required
  • vs_baseline.pct_points
    stringrequired
  • vs_baseline.amount
    stringrequired
  • vs_baseline.exceeds
    booleanrequired
  • flags
    any[]required
    One of: fade_vs_prior, fade_vs_baseline.
  • faded
    booleanrequired
  • events
    object[]required
  • events[].from_period
    string (date)required
  • events[].to_period
    string (date)required
  • events[].pct_points
    stringrequired
  • events[].amount
    stringrequired
  • events[].exceeds
    booleanrequired
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].formula
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Financial Reports

POST /rest/v1.0/companies/{company_id}/accounting/fpa/margin_fade/capture

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

v1.0Implemented

Parameters

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

Request body

  • period_end
    string (date)required

Response · 200 · object

  • period_end
    string (date)required
  • captured
    object[]required
  • captured[].project_id
    integerrequired
  • captured[].source
    anyrequired
    One of: wip, forecast.
  • skipped_project_ids
    integer[]required

Errors

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

Example request

Generated from the contractcurl
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/scenarios

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: base, upside, downside, custom.
  • description
    string | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • adjustments
    object[]
  • adjustments[].id
    integerrequired
  • adjustments[].scenario_id
    integerrequired
  • adjustments[].target
    anyrequired
    One of: budget, cash.
  • adjustments[].method
    anyrequired
    One of: percent, amount, shift_days.
  • adjustments[].value
    stringrequired
  • adjustments[].account_id
    integer | nullrequired
  • adjustments[].project_id
    integer | nullrequired
  • adjustments[].driver
    string | nullrequired
  • adjustments[].from_date
    string | null (date)required
  • adjustments[].to_date
    string | null (date)required
  • adjustments[].memo
    string | nullrequired
  • adjustments[].created_by_id
    integerrequired
  • adjustments[].created_at
    string (date-time)required

Errors

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

Example request

Generated from the contractcurl
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/scenarios

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

v1.0Implemented

Parameters

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

Request body

  • scenario
    objectrequired
  • scenario.name
    stringrequired
  • scenario.kind
    any
    One of: base, upside, downside, custom.
  • scenario.description
    string | null
  • scenario.adjustments
    object[]
  • scenario.adjustments[].target
    anyrequired
    One of: budget, cash.
  • scenario.adjustments[].method
    anyrequired
    One of: percent, amount, shift_days.
  • scenario.adjustments[].value
    string | numberrequired
    Percent, amount or whole days
  • scenario.adjustments[].account_id
    integer | null
  • scenario.adjustments[].project_id
    integer | null
  • scenario.adjustments[].driver
    string | null
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, null.
  • scenario.adjustments[].from_date
    string | null (date)
  • scenario.adjustments[].to_date
    string | null (date)
  • scenario.adjustments[].memo
    string | null

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: base, upside, downside, custom.
  • description
    string | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • adjustments
    object[]
  • adjustments[].id
    integerrequired
  • adjustments[].scenario_id
    integerrequired
  • adjustments[].target
    anyrequired
    One of: budget, cash.
  • adjustments[].method
    anyrequired
    One of: percent, amount, shift_days.
  • adjustments[].value
    stringrequired
  • adjustments[].account_id
    integer | nullrequired
  • adjustments[].project_id
    integer | nullrequired
  • adjustments[].driver
    string | nullrequired
  • adjustments[].from_date
    string | null (date)required
  • adjustments[].to_date
    string | null (date)required
  • adjustments[].memo
    string | nullrequired
  • adjustments[].created_by_id
    integerrequired
  • adjustments[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 409Conflict with the record's state
  • 422Validation failed

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: base, upside, downside, custom.
  • description
    string | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • adjustments
    object[]
  • adjustments[].id
    integerrequired
  • adjustments[].scenario_id
    integerrequired
  • adjustments[].target
    anyrequired
    One of: budget, cash.
  • adjustments[].method
    anyrequired
    One of: percent, amount, shift_days.
  • adjustments[].value
    stringrequired
  • adjustments[].account_id
    integer | nullrequired
  • adjustments[].project_id
    integer | nullrequired
  • adjustments[].driver
    string | nullrequired
  • adjustments[].from_date
    string | null (date)required
  • adjustments[].to_date
    string | null (date)required
  • adjustments[].memo
    string | nullrequired
  • adjustments[].created_by_id
    integerrequired
  • adjustments[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Conflict with the record's state

Example request

Generated from the contractcurl
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}/adjustments

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

v1.0Implemented

Parameters

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

Request body

  • adjustment
    objectrequired
  • adjustment.target
    anyrequired
    One of: budget, cash.
  • adjustment.method
    anyrequired
    One of: percent, amount, shift_days.
  • adjustment.value
    string | numberrequired
    Percent, amount or whole days
  • adjustment.account_id
    integer | null
  • adjustment.project_id
    integer | null
  • adjustment.driver
    string | null
    One of: ar, ar_retainage, billing, ap, ap_run, ap_retainage, commitment, payroll, recurring, scheduled, debt, lease, manual, null.
  • adjustment.from_date
    string | null (date)
  • adjustment.to_date
    string | null (date)
  • adjustment.memo
    string | null

Response · 201 · object

  • id
    integerrequired
  • scenario_id
    integerrequired
  • target
    anyrequired
    One of: budget, cash.
  • method
    anyrequired
    One of: percent, amount, shift_days.
  • value
    stringrequired
  • account_id
    integer | nullrequired
  • project_id
    integer | nullrequired
  • driver
    string | nullrequired
  • from_date
    string | null (date)required
  • to_date
    string | null (date)required
  • memo
    string | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company

Example request

Generated from the contractcurl
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/compare

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • budget_id
    integerqueryrequired
  • scenario_ids
    stringqueryrequired

Response · 200 · object

  • budget
    objectrequired
  • budget.id
    integerrequired
  • budget.fiscal_year
    integerrequired
  • budget.name
    stringrequired
  • budget.version
    integerrequired
  • budget.line_count
    integerrequired
  • budget.created_by_id
    integer | nullrequired
  • budget.created_at
    string (date-time)required
  • budget.status
    anyrequired
    One of: draft, submitted, approved, locked.
  • budget.description
    string | nullrequired
  • budget.copy_source
    string | nullrequired
  • budget.submitted_by_id
    integer | nullrequired
  • budget.submitted_at
    string | null (date-time)required
  • budget.approved_by_id
    integer | nullrequired
  • budget.approved_at
    string | null (date-time)required
  • budget.locked_by_id
    integer | nullrequired
  • budget.locked_at
    string | null (date-time)required
  • budget.returned_reason
    string | nullrequired
  • budget.total
    string
  • scenarios
    object[]required
  • scenarios[].id
    integerrequired
  • scenarios[].name
    stringrequired
  • scenarios[].kind
    stringrequired
  • rows
    object[]required
  • rows[].account
    objectrequired
  • rows[].base
    stringrequired
  • rows[].scenarios
    object[]required
  • net_income
    objectrequired
  • net_income.base
    stringrequired
  • net_income.scenarios
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed

Example request

Generated from the contractcurl
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/settings

FP&A settings

Cash forecast timing policy and margin fade thresholds (defaults until saved: saved false). Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • dtp_method
    anyrequired
    One of: median, mean.
  • dtp_lookback_days
    integerrequired
  • honor_discounts
    booleanrequired
  • customer_terms_days
    integerrequired
  • vendor_pay_days
    integerrequired
  • default_duration_months
    integerrequired
  • retainage_release_days
    integerrequired
  • payroll_average_runs
    integerrequired
  • fade_threshold_pct
    stringrequired
  • fade_threshold_amount
    stringrequired
  • saved
    booleanrequired
    False while the defaults apply

Errors

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

Example request

Generated from the contractcurl
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/settings

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

v1.0Implemented

Parameters

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

Request body

  • settings
    objectrequired
  • settings.dtp_method
    any
    One of: median, mean.
  • settings.dtp_lookback_days
    integer
  • settings.honor_discounts
    boolean
  • settings.customer_terms_days
    integer
  • settings.vendor_pay_days
    integer
  • settings.default_duration_months
    integer
  • settings.retainage_release_days
    integer
  • settings.payroll_average_runs
    integer
  • settings.fade_threshold_pct
    string | number
  • settings.fade_threshold_amount
    string | number

Response · 200 · object

  • dtp_method
    anyrequired
    One of: median, mean.
  • dtp_lookback_days
    integerrequired
  • honor_discounts
    booleanrequired
  • customer_terms_days
    integerrequired
  • vendor_pay_days
    integerrequired
  • default_duration_months
    integerrequired
  • retainage_release_days
    integerrequired
  • payroll_average_runs
    integerrequired
  • fade_threshold_pct
    stringrequired
  • fade_threshold_amount
    stringrequired
  • saved
    booleanrequired
    False while the defaults apply

Errors

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

Example request

Generated from the contractcurl
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_definitions

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • source
    stringquery
    Only this data source
  • page
    integerquery
    Page
  • per_page
    integerquery
    Page size

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • source
    stringrequired
  • visibility
    anyrequired
    One of: private, role, company.
  • shared_roles
    string[]required
  • version
    integerrequired
  • owner_id
    integerrequired
  • owner_name
    string | nullrequired
  • can_edit
    booleanrequired
  • spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • spec.base_report
    string
    source=catalog: the report library key
  • spec.columns
    string[]required
  • spec.group_by
    string[]
  • spec.filters
    object[]
  • spec.sort
    object[]
  • spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • spec.subtotals
    boolean
  • spec.limit
    integer | null
  • spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

Generated from the contractcurl
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_definitions

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

v1.0Implemented

Parameters

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

Request body

  • report_definition
    objectrequired
  • report_definition.name
    stringrequired
  • report_definition.description
    string | null
  • report_definition.visibility
    any
    One of: private, role, company.
  • report_definition.shared_roles
    any[]
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • report_definition.spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • report_definition.spec.base_report
    string
    source=catalog: the report library key
  • report_definition.spec.columns
    string[]required
  • report_definition.spec.group_by
    string[]
  • report_definition.spec.filters
    object[]
  • report_definition.spec.filters[].field
    stringrequired
  • report_definition.spec.filters[].op
    anyrequired
    One of: eq, in, not_in, gte, lte, contains.
  • report_definition.spec.filters[].value
    string | string[]required
  • report_definition.spec.sort
    object[]
  • report_definition.spec.sort[].field
    stringrequired
  • report_definition.spec.sort[].dir
    any
    One of: asc, desc.
  • report_definition.spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • report_definition.spec.subtotals
    boolean
  • report_definition.spec.limit
    integer | null
  • report_definition.spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • source
    stringrequired
  • visibility
    anyrequired
    One of: private, role, company.
  • shared_roles
    string[]required
  • version
    integerrequired
  • owner_id
    integerrequired
  • owner_name
    string | nullrequired
  • can_edit
    booleanrequired
  • spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • spec.base_report
    string
    source=catalog: the report library key
  • spec.columns
    string[]required
  • spec.group_by
    string[]
  • spec.filters
    object[]
  • spec.sort
    object[]
  • spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • spec.subtotals
    boolean
  • spec.limit
    integer | null
  • spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Unknown library report or budget
  • 422Invalid spec (unknown column, grouping or comparison), name or sharing

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • source
    stringrequired
  • visibility
    anyrequired
    One of: private, role, company.
  • shared_roles
    string[]required
  • version
    integerrequired
  • owner_id
    integerrequired
  • owner_name
    string | nullrequired
  • can_edit
    booleanrequired
  • spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • spec.base_report
    string
    source=catalog: the report library key
  • spec.columns
    string[]required
  • spec.group_by
    string[]
  • spec.filters
    object[]
  • spec.sort
    object[]
  • spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • spec.subtotals
    boolean
  • spec.limit
    integer | null
  • spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Not found or not shared with the caller

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Request body

  • report_definition
    objectrequired
  • report_definition.name
    string
  • report_definition.description
    string | null
  • report_definition.visibility
    any
    One of: private, role, company.
  • report_definition.shared_roles
    any[]
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • report_definition.spec
    object
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • report_definition.spec.base_report
    string
    source=catalog: the report library key
  • report_definition.spec.columns
    string[]required
  • report_definition.spec.group_by
    string[]
  • report_definition.spec.filters
    object[]
  • report_definition.spec.filters[].field
    stringrequired
  • report_definition.spec.filters[].op
    anyrequired
    One of: eq, in, not_in, gte, lte, contains.
  • report_definition.spec.filters[].value
    string | string[]required
  • report_definition.spec.sort
    object[]
  • report_definition.spec.sort[].field
    stringrequired
  • report_definition.spec.sort[].dir
    any
    One of: asc, desc.
  • report_definition.spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • report_definition.spec.subtotals
    boolean
  • report_definition.spec.limit
    integer | null
  • report_definition.spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • source
    stringrequired
  • visibility
    anyrequired
    One of: private, role, company.
  • shared_roles
    string[]required
  • version
    integerrequired
  • owner_id
    integerrequired
  • owner_name
    string | nullrequired
  • can_edit
    booleanrequired
  • spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • spec.base_report
    string
    source=catalog: the report library key
  • spec.columns
    string[]required
  • spec.group_by
    string[]
  • spec.filters
    object[]
  • spec.sort
    object[]
  • spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • spec.subtotals
    boolean
  • spec.limit
    integer | null
  • spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Not the owner, or no accounting access
  • 404Not found or not shared with the caller
  • 422Invalid spec, name or sharing

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403Not the owner, or no accounting access
  • 404Not found or not shared with the caller

Example request

Generated from the contractcurl
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}/export

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • format
    anyquery
    File format (default csv) One of: csv, xlsx, pdf.
  • as_of
    string (date)query
    Balance date (as-of sources); overrides the saved parameter
  • from
    string (date)query
    Start of the activity range; overrides the saved parameter
  • to
    string (date)query
    End of the activity range; overrides the saved parameter
  • entity_id
    integerquery
    Entity (must be inside the caller's grant)
  • project_id
    integerquery
    Job (must be inside the caller's grant)
  • department_id
    integerquery
    Department
  • budget_id
    integerquery
    GL budget for compare=budget
  • basis
    anyquery
    Aging basis for open-item sources One of: due, document.
  • version
    integerquery
    Run an earlier saved version

Response · 200 · string

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Not found or not shared with the caller
  • 422Unknown format or invalid parameter
  • 429Export rate limit reached (Retry-After)

Example request

Generated from the contractcurl
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}/run

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • as_of
    string (date)query
    Balance date (as-of sources); overrides the saved parameter
  • from
    string (date)query
    Start of the activity range; overrides the saved parameter
  • to
    string (date)query
    End of the activity range; overrides the saved parameter
  • entity_id
    integerquery
    Entity (must be inside the caller's grant)
  • project_id
    integerquery
    Job (must be inside the caller's grant)
  • department_id
    integerquery
    Department
  • budget_id
    integerquery
    GL budget for compare=budget
  • basis
    anyquery
    Aging basis for open-item sources One of: due, document.
  • version
    integerquery
    Run an earlier saved version

Response · 200 · object

  • key
    stringrequired
  • title
    stringrequired
  • subtitle
    stringrequired
    Dates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
  • params
    objectrequired
  • columns
    object[]required
  • columns[].key
    stringrequired
  • columns[].label
    stringrequired
  • columns[].fmt
    anyrequired
    One of: text, money, pct, int, date.
  • rows
    object[]required
  • rows[].id
    stringrequired
  • rows[].kind
    anyrequired
    One of: header, line, account, subtotal, total, detail, note.
  • rows[].depth
    integerrequired
  • rows[].cells
    objectrequired
  • rows[].href
    string | null
    In-app drill-down link
  • rows[].cellHrefs
    object
    Per-cell drill-down links (column key to in-app link) for pivot and comparison columns
  • rows[].tone
    any
    One of: ok, warn, risk, null.
  • checks
    object[]required
  • checks[].label
    stringrequired
  • checks[].ok
    booleanrequired
  • checks[].difference
    stringrequired
    A money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
  • checks[].detail
    string | null
  • notes
    string[]required
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].value
    stringrequired
  • explain[].formula
    string
  • explain[].cite
    string
  • generatedAt
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No 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 grant
  • 422Invalid parameter, or too many detail lines

Example request

Generated from the contractcurl
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}/versions

Report definition versions

Every saved version, newest first. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • version
    integerrequired
  • name
    stringrequired
  • source
    stringrequired
  • spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • spec.base_report
    string
    source=catalog: the report library key
  • spec.columns
    string[]required
  • spec.group_by
    string[]
  • spec.filters
    object[]
  • spec.sort
    object[]
  • spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • spec.subtotals
    boolean
  • spec.limit
    integer | null
  • spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Not found or not shared with the caller

Example request

Generated from the contractcurl
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/preview

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
    Balance date (as-of sources); overrides the saved parameter
  • from
    string (date)query
    Start of the activity range; overrides the saved parameter
  • to
    string (date)query
    End of the activity range; overrides the saved parameter
  • entity_id
    integerquery
    Entity (must be inside the caller's grant)
  • project_id
    integerquery
    Job (must be inside the caller's grant)
  • department_id
    integerquery
    Department
  • budget_id
    integerquery
    GL budget for compare=budget
  • basis
    anyquery
    Aging basis for open-item sources One of: due, document.

Request body

  • report_definition
    objectrequired
  • report_definition.spec
    objectrequired
    Columns, 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.source
    anyrequired
    One of: gl_detail, trial_balance, cash, ap_open_items, ar_open_items, job_cost, job_cost_entries, catalog.
  • report_definition.spec.base_report
    string
    source=catalog: the report library key
  • report_definition.spec.columns
    string[]required
  • report_definition.spec.group_by
    string[]
  • report_definition.spec.filters
    object[]
  • report_definition.spec.filters[].field
    stringrequired
  • report_definition.spec.filters[].op
    anyrequired
    One of: eq, in, not_in, gte, lte, contains.
  • report_definition.spec.filters[].value
    string | string[]required
  • report_definition.spec.sort
    object[]
  • report_definition.spec.sort[].field
    stringrequired
  • report_definition.spec.sort[].dir
    any
    One of: asc, desc.
  • report_definition.spec.compare
    any
    One of: none, prior_period, prior_year, budget.
  • report_definition.spec.subtotals
    boolean
  • report_definition.spec.limit
    integer | null
  • report_definition.spec.params
    object
    Saved report parameters (as_of, from, to, entity_id, project_id, department_id, budget_id, basis…)

Response · 200 · object

  • key
    stringrequired
  • title
    stringrequired
  • subtitle
    stringrequired
    Dates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
  • params
    objectrequired
  • columns
    object[]required
  • columns[].key
    stringrequired
  • columns[].label
    stringrequired
  • columns[].fmt
    anyrequired
    One of: text, money, pct, int, date.
  • rows
    object[]required
  • rows[].id
    stringrequired
  • rows[].kind
    anyrequired
    One of: header, line, account, subtotal, total, detail, note.
  • rows[].depth
    integerrequired
  • rows[].cells
    objectrequired
  • rows[].href
    string | null
    In-app drill-down link
  • rows[].cellHrefs
    object
    Per-cell drill-down links (column key to in-app link) for pivot and comparison columns
  • rows[].tone
    any
    One of: ok, warn, risk, null.
  • checks
    object[]required
  • checks[].label
    stringrequired
  • checks[].ok
    booleanrequired
  • checks[].difference
    stringrequired
    A money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
  • checks[].detail
    string | null
  • notes
    string[]required
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].value
    stringrequired
  • explain[].formula
    string
  • explain[].cite
    string
  • generatedAt
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No 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 company
  • 422Invalid spec or parameter, or too many detail lines

Example request

Generated from the contractcurl
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/sources

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • key
    stringrequired
  • title
    stringrequired
  • description
    stringrequired
  • params
    string[]required
  • columns
    object[]required
  • columns[].key
    stringrequired
  • columns[].label
    stringrequired
  • columns[].role
    anyrequired
    One of: dim, attr, measure.
  • columns[].fmt
    anyrequired
    One of: text, money, pct, int, date.
  • columns[].groupable
    boolean
  • columns[].compare
    any[]
    One of: prior_period, prior_year, budget.
  • default_columns
    string[]required
  • default_group_by
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

Generated from the contractcurl
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/reports

Report library

Every report with its group and accepted parameters. Requires the accounting:read scope and an accounting grant.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • key
    anyrequired
    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.
  • title
    stringrequired
  • group
    stringrequired
  • description
    stringrequired
  • params
    any[]required
    One 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 token
  • 403No 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 company
  • 422Malformed parameter

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • report_key
    anypathrequired
    Report 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_of
    string (date)query
    Balance date (default `to`, else today)
  • from
    string (date)query
    Start of the activity range (default the start of the fiscal year holding `to`)
  • to
    string (date)query
    End of the activity range (default today)
  • adj_from
    string (date)query
    Trial 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)
  • compare
    anyquery
    Comparative 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_id
    integerquery
    With compare=budget: the GL budget version to compare with
  • columns
    anyquery
    Income 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_id
    integerquery
    One entity (within the grant entities)
  • project_id
    integerquery
    One job
  • department_id
    integerquery
    One department
  • dimension
    stringquery
    User-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_level
    integerquery
    Roll grouped values up to this hierarchy level (1 = top-level values); omitted = the posted value.
  • dimension_value_ids
    stringquery
    Comma-separated dimension value ids: lines carrying one of them or a child value (values of one dimension OR, dimensions AND).
  • account_id
    integerquery
    One account (general ledger)
  • journal
    anyquery
    One journal (journal report) One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • basis
    anyquery
    Aging basis One of: due, document.
  • include_zero
    anyquery
    Also show rows with no balance One of: true, false.
  • jtd
    stringquery
    Job profitability: job to date through `to` (ignores `from`) One of: true, false.
  • actor_id
    integerquery
    Audit log: only events by this user
  • item_type
    stringquery
    Audit log: only events on this accounting record type (e.g. AcctAccount)
  • action
    stringquery
    Audit log: only events with this action (e.g. updated)
  • rollup
    stringquery
    Balance sheet and income statement: group account rows under their parent account with a subtotal row One of: true, false.

Response · 200 · object

  • key
    anyrequired
    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.
  • title
    stringrequired
  • subtitle
    stringrequired
    Dates and scope; ends with the entity, job and department filters applied, e.g. `As of 2026-10-31 · Entity: E1 Main · Job: Riverside`
  • params
    objectrequired
  • columns
    object[]required
  • columns[].key
    stringrequired
  • columns[].label
    stringrequired
  • columns[].fmt
    anyrequired
    One of: text, money, pct, int, date.
  • rows
    object[]required
  • rows[].id
    stringrequired
  • rows[].kind
    anyrequired
    One of: header, line, account, subtotal, total, detail, note.
  • rows[].depth
    integerrequired
  • rows[].cells
    objectrequired
  • rows[].href
    string | null
    In-app drill-down link
  • rows[].cellHrefs
    object
    Per-cell drill-down links (column key to in-app link) for pivot and comparison columns
  • rows[].tone
    any
    One of: ok, warn, risk, null.
  • checks
    object[]required
  • checks[].label
    stringrequired
  • checks[].ok
    booleanrequired
  • checks[].difference
    stringrequired
    A money amount with two decimals ("12.50"), or a bare item count ("3") for checks that count exceptions.
  • checks[].detail
    string | null
  • notes
    string[]required
  • explain
    object[]required
  • explain[].label
    stringrequired
  • explain[].value
    stringrequired
  • explain[].formula
    string
  • explain[].cite
    string
  • generatedAt
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No 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 company
  • 422Malformed parameter
  • 429Company heavy-read budget spent (ACCT_HEAVY_BUDGET units per minute); retry after the Retry-After seconds

Example request

Generated from the contractcurl
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}/export

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • report_key
    anypathrequired
    Report 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.
  • format
    anyquery
    File format (default csv) One of: csv, xlsx, pdf.
  • as_of
    string (date)query
    Balance date (default `to`, else today)
  • from
    string (date)query
    Start of the activity range (default the start of the fiscal year holding `to`)
  • to
    string (date)query
    End of the activity range (default today)
  • adj_from
    string (date)query
    Trial 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)
  • compare
    anyquery
    Comparative 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_id
    integerquery
    With compare=budget: the GL budget version to compare with
  • columns
    anyquery
    Income 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_id
    integerquery
    One entity (within the grant entities)
  • project_id
    integerquery
    One job
  • department_id
    integerquery
    One department
  • dimension
    stringquery
    User-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_level
    integerquery
    Roll grouped values up to this hierarchy level (1 = top-level values); omitted = the posted value.
  • dimension_value_ids
    stringquery
    Comma-separated dimension value ids: lines carrying one of them or a child value (values of one dimension OR, dimensions AND).
  • account_id
    integerquery
    One account (general ledger)
  • journal
    anyquery
    One journal (journal report) One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • basis
    anyquery
    Aging basis One of: due, document.
  • include_zero
    anyquery
    Also show rows with no balance One of: true, false.
  • jtd
    stringquery
    Job profitability: job to date through `to` (ignores `from`) One of: true, false.
  • actor_id
    integerquery
    Audit log: only events by this user
  • item_type
    stringquery
    Audit log: only events on this accounting record type (e.g. AcctAccount)
  • action
    stringquery
    Audit log: only events with this action (e.g. updated)
  • rollup
    stringquery
    Balance 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 token
  • 403No 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 company
  • 422Malformed parameter
  • 429Export limit reached, or the company heavy-read budget is spent; retry after the Retry-After seconds

Example request

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

Ask the OS

Reading this page

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

Suggested

    AI · may be imperfect · sample data where shown

    Open file