Esc

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

Fiscal Periods

Resolve close blockers, approve evidence and close eligible periods. 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 Fiscal Periods guide for the workflow.

76 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/close/alert_testsAlert delivery tests
  2. POST /rest/v1.0/companies/{company_id}/accounting/close/alert_testsSend a test alert
  3. GET /rest/v1.0/companies/{company_id}/accounting/close/cockpitClose cockpit
  4. POST /rest/v1.0/companies/{company_id}/accounting/close/cockpit/generateGenerate close tasks
  5. POST /rest/v1.0/companies/{company_id}/accounting/close/cockpit/syncRefresh close evidence
  6. GET /rest/v1.0/companies/{company_id}/accounting/close/fluxFlux analysis of a period
  7. POST /rest/v1.0/companies/{company_id}/accounting/close/flux/explanationsExplain a flux row
  8. GET /rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}Show a flux explanation
  9. POST /rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}/reviewReview a flux explanation
  10. GET /rest/v1.0/companies/{company_id}/accounting/close/flux/settingsFlux settings
  11. PUT /rest/v1.0/companies/{company_id}/accounting/close/flux/settingsSave flux settings
  12. GET /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholdsList flux thresholds
  13. POST /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholdsCreate a flux threshold
  14. PATCH /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholds/{id}Update a flux threshold
  15. GET /rest/v1.0/companies/{company_id}/accounting/close/rec_rulesList reconciliation rules
  16. POST /rest/v1.0/companies/{company_id}/accounting/close/rec_rulesCreate a reconciliation rule
  17. PATCH /rest/v1.0/companies/{company_id}/accounting/close/rec_rules/{id}Update a reconciliation rule
  18. GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliationsList account reconciliations
  19. GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}Show an account reconciliation
  20. GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsList attachments on an account reconciliation
  21. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsAttach a workpaper to an account reconciliation
  22. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/itemsAdd a reconciling item or schedule line
  23. PATCH /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/items/{item_id}Update or clear a reconciliation item
  24. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/preparePrepare an account reconciliation
  25. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/reviewReview an account reconciliation
  26. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/unsignUnsign an account reconciliation
  27. POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/generateGenerate account reconciliations
  28. GET /rest/v1.0/companies/{company_id}/accounting/close/settingsClose cockpit settings
  29. PUT /rest/v1.0/companies/{company_id}/accounting/close/settingsSave close cockpit settings
  30. GET /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}Show a close task
  31. POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/preparePrepare a close task
  32. POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/reviewReview a close task
  33. POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/startStart a close task
  34. POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/unsignUnsign a close task
  35. GET /rest/v1.0/companies/{company_id}/accounting/close/templatesList close templates
  36. POST /rest/v1.0/companies/{company_id}/accounting/close/templatesCreate a close template
  37. GET /rest/v1.0/companies/{company_id}/accounting/close/templates/{id}Show a close template
  38. PUT /rest/v1.0/companies/{company_id}/accounting/close/templates/{id}Replace a close template
  39. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runsList equity-method runs
  40. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runsPrepare an equity-method run
  41. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}Get an equity-method run
  42. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}/decisionApprove or cancel an equity-method run
  43. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputesList intercompany disputes
  44. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputesRaise an intercompany dispute
  45. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}Get an intercompany dispute
  46. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/adjustmentPropose the adjusting entry
  47. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/assignAssign an intercompany dispute
  48. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/commentsComment on an intercompany dispute
  49. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/decisionApprove or reject the adjusting entry
  50. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/resolveResolve or withdraw an intercompany dispute
  51. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlementsList intercompany settlement runs
  52. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlementsPrepare an intercompany settlement
  53. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}Get an intercompany settlement run
  54. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}/decisionApprove or cancel an intercompany settlement
  55. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfersList intercompany asset transfers
  56. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfersRegister an intercompany asset transfer
  57. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}Get an intercompany asset transfer
  58. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/eventsRecord a sale on or a disposal
  59. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/voidVoid an intercompany asset transfer
  60. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ownershipList ownership versions
  61. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ownershipRecord an ownership version
  62. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}Get an ownership version
  63. POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}/voidVoid an ownership version
  64. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/settingsConsolidation settings
  65. PATCH /rest/v1.0/companies/{company_id}/accounting/consolidation/settingsUpdate consolidation settings
  66. GET /rest/v1.0/companies/{company_id}/accounting/consolidation/structureConsolidation group on a date
  67. POST /rest/v1.0/companies/{company_id}/accounting/fiscal_yearsGenerate a fiscal year
  68. POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/adjusting_periodAdd the adjusting period (period 13)
  69. POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_closePost the year-end close
  70. POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_close/reverseReverse the year-end close
  71. GET /rest/v1.0/companies/{company_id}/accounting/periodsList fiscal periods
  72. GET /rest/v1.0/companies/{company_id}/accounting/periods/{id}Show a fiscal period
  73. POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/closeClose or soft-close a period
  74. POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/eliminate_intercompanyEliminate intercompany at a period end
  75. POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/reopenReopen a period
  76. POST /rest/v1.0/companies/{company_id}/accounting/periods/rebuild_balancesRebuild period balance snapshots

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/alert_tests

Alert delivery tests

Alert delivery evidence, newest first: each requested test alert with one attempt per channel and recipient (email through the finance alert recipient path and the configured transport; a signed webhook test delivery per active subscription receiving accounting events, with its live outcome). Needs close_period; refused to project-scoped grants. Requires the accounting:read scope. See docs/accounting/INTERFACE-FAILURE-VERIFICATION.md.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • status
    stringrequired
    One of: queued, delivered, partial, failed.
  • requested_by_id
    integerrequired
  • job_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • finished_at
    string | null (date-time)required
  • attempts
    object[]required
  • attempts[].id
    integerrequired
  • attempts[].channel
    stringrequired
    One of: email, webhook.
  • attempts[].transport
    stringrequired
    email: the configured transport (outbox records locally, webhook or resend hand to a provider); webhook: durable_delivery
  • attempts[].recipient_user_id
    integer | nullrequired
  • attempts[].subscription_id
    integer | nullrequired
  • attempts[].email_message_id
    integer | nullrequired
  • attempts[].webhook_delivery_id
    string | null (uuid)required
  • attempts[].outcome
    stringrequired
    recorded: written to the local outbox (no external delivery); accepted: the email provider accepted it (not proof of mailbox delivery); queued: a signed webhook test delivery was queued (see delivery_outcome) One of: recorded, accepted, failed, queued, skipped, no_recipient.
  • attempts[].error_code
    string | nullrequired
    A sanitized code, never an address or provider text
  • attempts[].created_at
    string (date-time)required
  • attempts[].delivery_outcome
    string | null
    One of: pending, succeeded, cancelled, null.
  • attempts[].delivery_http_status
    integer | null
  • attempts[].delivery_error_code
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing close_period (or a project-scoped grant), 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/close/alert_tests" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/alert_tests

Send a test alert

Queues a test alert (job accounting_alert_test) to the finance alert recipients, by the same recipient resolution and email transport real finance alerts use, and, when the requester is a company administrator, a signed webhook.test delivery to each active subscription receiving accounting events. Idempotent on request_key: a repeat returns the existing test. Nobody is mailed twice by one test, even when its job is retried. Needs close_period; refused to project-scoped grants. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • request_key
    stringrequired

Response · 202 · object

  • id
    integerrequired
  • status
    stringrequired
    One of: queued, delivered, partial, failed.
  • requested_by_id
    integerrequired
  • job_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • finished_at
    string | null (date-time)required
  • attempts
    object[]required
  • attempts[].id
    integerrequired
  • attempts[].channel
    stringrequired
    One of: email, webhook.
  • attempts[].transport
    stringrequired
    email: the configured transport (outbox records locally, webhook or resend hand to a provider); webhook: durable_delivery
  • attempts[].recipient_user_id
    integer | nullrequired
  • attempts[].subscription_id
    integer | nullrequired
  • attempts[].email_message_id
    integer | nullrequired
  • attempts[].webhook_delivery_id
    string | null (uuid)required
  • attempts[].outcome
    stringrequired
    recorded: written to the local outbox (no external delivery); accepted: the email provider accepted it (not proof of mailbox delivery); queued: a signed webhook test delivery was queued (see delivery_outcome) One of: recorded, accepted, failed, queued, skipped, no_recipient.
  • attempts[].error_code
    string | nullrequired
    A sanitized code, never an address or provider text
  • attempts[].created_at
    string (date-time)required
  • attempts[].delivery_outcome
    string | null
    One of: pending, succeeded, cancelled, null.
  • attempts[].delivery_http_status
    integer | null
  • attempts[].delivery_error_code
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing close_period (or a project-scoped grant), wrong company, accounting:read token, or read-only workspace
  • 422Invalid request_key

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/cockpit

Close cockpit

Progress by status and category, the critical path (longest chain of unfinished dependent tasks), overdue tasks, who is blocking whom, the reconciliation summary and what the period close would refuse now. entity_id omitted: the all-entities task list. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • period_id
    integerqueryrequired
    The period
  • entity_id
    integerquery
    Entity scope (omit for all entities)

Response · 200 · object

  • period
    objectrequired
  • period.id
    integerrequired
  • period.name
    stringrequired
  • period.start_date
    string | null (date)required
  • period.end_date
    string | null (date)required
  • period.status
    stringrequired
  • entity_id
    integer | nullrequired
  • today
    string (date)required
  • settings
    objectrequired
  • settings.require_tasks
    booleanrequired
  • settings.require_recs
    booleanrequired
  • settings.require_flux
    boolean
    GL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
  • settings.default_template_id
    integer | nullrequired
  • progress
    objectrequired
  • progress.total
    integerrequired
  • progress.reviewed
    integerrequired
  • progress.percent
    integerrequired
  • progress.overdue
    integerrequired
  • progress.required_open
    integerrequired
  • progress.by_status
    objectrequired
  • progress.by_category
    object[]required
  • critical_path
    integer[]required
    Task ids, first to last: the longest chain of unfinished dependent tasks.
  • blocking
    object[]required
  • blocking[].blocker_id
    integer | nullrequired
  • blocking[].blocker_name
    string | nullrequired
  • blocking[].blocked_id
    integer | nullrequired
  • blocking[].blocked_name
    string | nullrequired
  • blocking[].tasks
    object[]required
  • reconciliations
    objectrequired
  • reconciliations.total
    integerrequired
  • reconciliations.by_status
    objectrequired
  • reconciliations.stale
    integerrequired
  • reconciliations.auto_reconciled
    integerrequired
  • reconciliations.missing
    integerrequired
  • reconciliations.open_items
    integerrequired
  • reconciliations.items_over_90
    integerrequired
  • close_blockers
    object[]required
  • close_blockers[].code
    stringrequired
  • close_blockers[].message
    stringrequired
  • close_blockers[].href
    string
  • tasks
    object[]required
  • tasks[].id
    integerrequired
  • tasks[].period_id
    integerrequired
  • tasks[].entity_id
    integer | nullrequired
  • tasks[].key
    stringrequired
  • tasks[].title
    stringrequired
  • tasks[].category
    stringrequired
  • tasks[].close_module
    string | nullrequired
  • tasks[].owner_id
    integer | nullrequired
  • tasks[].reviewer_id
    integer | nullrequired
  • tasks[].due_date
    string | null (date)required
  • tasks[].depends_on
    string[]required
  • tasks[].evidence
    string | nullrequired
  • tasks[].required
    booleanrequired
  • tasks[].instructions
    string | nullrequired
  • tasks[].status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • tasks[].prepared_by_id
    integer | nullrequired
  • tasks[].prepared_at
    string | null (date-time)required
  • tasks[].prep_note
    string | nullrequired
  • tasks[].reviewed_by_id
    integer | nullrequired
  • tasks[].reviewed_at
    string | null (date-time)required
  • tasks[].review_note
    string | nullrequired
  • tasks[].auto_completed
    booleanrequired
  • tasks[].evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • tasks[].evidence_message
    string | nullrequired
  • tasks[].evidence_checked_at
    string | null (date-time)required
  • tasks[].stale_at
    string | null (date-time)required
  • tasks[].stale_reason
    string | nullrequired
  • tasks[].overdue
    booleanrequired
  • tasks[].open_dependencies
    string[]required
  • tasks[].critical
    booleanrequired

Errors

  • 400period_id missing
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Period or entity not found

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/cockpit/generate

Generate close tasks

Creates the scope's tasks for the period from a template (default: the settings' default); keys already present are kept. Needs close_period (all entities: unrestricted entity access). Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • generate
    objectrequired
  • generate.period_id
    integerrequired
  • generate.entity_id
    integer | null
  • generate.template_id
    integer | null

Response · 200 · object

  • created
    integerrequired
  • kept
    integerrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Period, entity or template not found
  • 422No template given and no default set

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/cockpit/sync

Refresh close evidence

Re-evaluates every evidence task of the scope (subledger tie-outs, module close readiness, depreciation, allocation, WIP and elimination runs, reconciliations): passing evidence completes the task (reviewed, auto-completed); a completed task whose evidence fails goes stale (not started, with the reason). Then auto-reconciles the scope's reconciliations. Needs close_period. Audited per change. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • sync
    objectrequired
  • sync.period_id
    integerrequired
  • sync.entity_id
    integer | null

Response · 200 · object

  • completed
    integerrequired
  • stale
    integerrequired
  • reconciled
    integerrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Period or entity not found

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/flux

Flux analysis of a period

Rows of one period for one entity (entity_id) or every entity the grant reaches, with the three comparisons, the threshold that applied, whether an explanation is required and the explanation state (none, explained, reviewed or stale). Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • period
    object | nullrequired
  • period.id
    integerrequired
  • period.name
    stringrequired
  • period.start_date
    string (date)required
  • period.end_date
    string (date)required
  • prior_period
    object | nullrequired
  • prior_period.id
    integerrequired
  • prior_period.name
    stringrequired
  • prior_period.start_date
    string (date)required
  • prior_period.end_date
    string (date)required
  • prior_year_period
    object | nullrequired
  • prior_year_period.id
    integerrequired
  • prior_year_period.name
    stringrequired
  • prior_year_period.start_date
    string (date)required
  • prior_year_period.end_date
    string (date)required
  • budget
    object | nullrequired
  • budget.id
    integer
  • budget.name
    string
  • budget.fiscal_year
    integer
  • budget.version
    integer
  • settings
    objectrequired
  • settings.default_amount
    stringrequired
  • settings.default_percent
    stringrequired
  • settings.threshold_mode
    anyrequired
    One of: both, either.
  • settings.materiality_floor
    stringrequired
  • settings.compare_prior_period
    booleanrequired
  • settings.compare_prior_year
    booleanrequired
  • settings.compare_budget
    booleanrequired
  • settings.revision
    integerrequired
  • settings.updated_at
    string | null (date-time)required
  • entity_ids
    integer[]required
  • summary
    objectrequired
  • summary.rows
    integerrequired
  • summary.requiring
    integerrequired
  • summary.unexplained
    integerrequired
  • summary.explained
    integerrequired
  • summary.reviewed
    integerrequired
  • summary.stale
    integerrequired
  • rows
    object[]required
  • rows[].key
    stringrequired
  • rows[].entity_id
    integerrequired
  • rows[].kind
    anyrequired
    One of: income_statement, balance_sheet.
  • rows[].account
    objectrequired
  • rows[].dimension
    object | nullrequired
  • rows[].dimension_value
    object | nullrequired
  • rows[].current
    stringrequired
  • rows[].prior_period
    stringrequired
  • rows[].prior_year
    stringrequired
  • rows[].budget
    string | nullrequired
  • rows[].comparisons
    object[]required
  • rows[].threshold
    objectrequired
  • rows[].requires_explanation
    booleanrequired
  • rows[].status
    anyrequired
    One of: none, explained, reviewed, stale.
  • rows[].stale_reason
    string | nullrequired
  • rows[].explanation
    object | nullrequired

Errors

  • 400period_id missing
  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant, outside the entity scope or wrong company
  • 404Period or entity not found
  • 422The adjusting period has no flux analysis

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/flux/explanations

Explain a flux row

Write or rewrite the explanation of one row (period, entity, account and, for a split account, dimension value). Needs post_journal and the entity in scope; the caller becomes the preparer. One explanation per row (natural key), so a repeat updates it; rewriting a reviewed explanation makes the review stale. The same text over moved figures confirms them for a fresh review. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • flux_explanation
    objectrequired
  • flux_explanation.period_id
    integerrequired
  • flux_explanation.entity_id
    integerrequired
  • flux_explanation.account_id
    integerrequired
  • flux_explanation.dimension_value_id
    integer | null
  • flux_explanation.explanation
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • account_id
    integerrequired
  • dimension_value_id
    integer | nullrequired
  • explanation
    stringrequired
  • revision
    integerrequired
  • figures
    objectrequired
    Figures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
  • prepared_by_id
    integerrequired
  • prepared_at
    string | null (date-time)required
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • balance_debit
    string | null
  • balance_credit
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403Missing post_journal, outside the entity scope, project-scoped or read-only workspace
  • 404Period or entity not found
  • 422Invalid body, or (explanations) no flux figures for that row

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/close/flux/explanations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "flux_explanation": {
    "period_id": 1,
    "entity_id": 1,
    "account_id": 1,
    "explanation": "string"
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}

Show a flux explanation

The explanation with its live row (figures, comparisons, status and stale reason). Needs view_ledger and the entity in scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • account_id
    integerrequired
  • dimension_value_id
    integer | nullrequired
  • explanation
    stringrequired
  • revision
    integerrequired
  • figures
    objectrequired
    Figures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
  • prepared_by_id
    integerrequired
  • prepared_at
    string | null (date-time)required
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • balance_debit
    string | null
  • balance_credit
    string | null
  • row
    object | nullrequired
  • row.key
    stringrequired
  • row.entity_id
    integerrequired
  • row.kind
    anyrequired
    One of: income_statement, balance_sheet.
  • row.account
    objectrequired
  • row.dimension
    object | nullrequired
  • row.dimension_value
    object | nullrequired
  • row.current
    stringrequired
  • row.prior_period
    stringrequired
  • row.prior_year
    stringrequired
  • row.budget
    string | nullrequired
  • row.comparisons
    object[]required
  • row.threshold
    objectrequired
  • row.requires_explanation
    booleanrequired
  • row.status
    anyrequired
    One of: none, explained, reviewed, stale.
  • row.stale_reason
    string | nullrequired
  • row.explanation
    object | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, outside the entity scope or project-scoped
  • 404Not found

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}/review

Review a flux explanation

Sign as reviewer: needs close_period and the entity in scope; the preparer is refused (403). Refused (409) when the figures or balance moved since the explanation was written (the preparer confirms it first) or when the review is already current. The reviewer signs a hash of the explanation, the figures and the cumulative posted debit and credit. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • account_id
    integerrequired
  • dimension_value_id
    integer | nullrequired
  • explanation
    stringrequired
  • revision
    integerrequired
  • figures
    objectrequired
    Figures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
  • prepared_by_id
    integerrequired
  • prepared_at
    string | null (date-time)required
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • balance_debit
    string | null
  • balance_credit
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403Missing close_period, the preparer, outside the entity scope or project-scoped
  • 404Not found
  • 409Figures moved since the explanation, already reviewed, or changed concurrently
  • 422Invalid body, or (explanations) no flux figures for that row

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/flux/settings

Flux settings

Default thresholds, threshold mode, materiality floor and which comparisons apply. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • default_amount
    stringrequired
  • default_percent
    stringrequired
  • threshold_mode
    anyrequired
    One of: both, either.
  • materiality_floor
    stringrequired
  • compare_prior_period
    booleanrequired
  • compare_prior_year
    booleanrequired
  • compare_budget
    booleanrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access or a project-scoped grant

Example request

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

Accounting / Fiscal Periods

PUT /rest/v1.0/companies/{company_id}/accounting/close/flux/settings

Save flux settings

Owner or controller with close_period and unrestricted entity access. threshold_mode both: a variance needs an explanation when it reaches the amount AND the percent threshold; either: one of them. A variance below materiality_floor never does. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • flux_settings
    objectrequired
  • flux_settings.default_amount
    stringrequired
  • flux_settings.default_percent
    stringrequired
  • flux_settings.threshold_mode
    anyrequired
    One of: both, either.
  • flux_settings.materiality_floor
    stringrequired
  • flux_settings.compare_prior_period
    booleanrequired
  • flux_settings.compare_prior_year
    booleanrequired
  • flux_settings.compare_budget
    booleanrequired

Response · 200 · object

  • default_amount
    stringrequired
  • default_percent
    stringrequired
  • threshold_mode
    anyrequired
    One of: both, either.
  • materiality_floor
    stringrequired
  • compare_prior_period
    booleanrequired
  • compare_prior_year
    booleanrequired
  • compare_budget
    booleanrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Missing close_period, not an owner or controller, entity-restricted, project-scoped or read-only workspace
  • 422Invalid body, or (explanations) no flux figures for that row

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/close/flux/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "flux_settings": {
    "default_amount": "0.00",
    "default_percent": "0.00",
    "threshold_mode": "both",
    "materiality_floor": "string",
    "compare_prior_period": true,
    "compare_prior_year": true,
    "compare_budget": true
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholds

List flux thresholds

Threshold overrides per account type or account. An account's own threshold wins over its type's; with neither, the settings' defaults apply. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • account_type
    string | nullrequired
  • account_id
    integer | nullrequired
  • amount
    stringrequired
  • percent
    stringrequired
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access or a project-scoped grant

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholds

Create a flux threshold

For exactly one of account_type or account_id. Owner or controller with close_period and unrestricted entity access; a second threshold for the same type or account is 409. Audited. 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

  • flux_threshold
    objectrequired
  • flux_threshold.account_type
    string | null
  • flux_threshold.account_id
    integer | null
  • flux_threshold.amount
    stringrequired
  • flux_threshold.percent
    stringrequired
  • flux_threshold.is_active
    boolean

Response · 201 · object

  • id
    integerrequired
  • account_type
    string | nullrequired
  • account_id
    integer | nullrequired
  • amount
    stringrequired
  • percent
    stringrequired
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Missing close_period, not an owner or controller, entity-restricted or project-scoped
  • 404Account not found
  • 409A threshold for the type or account exists
  • 422Invalid body, or (explanations) no flux figures for that row

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/close/flux/thresholds" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "flux_threshold": {
    "amount": "0.00",
    "percent": "0.00"
  }
}'

Accounting / Fiscal Periods

PATCH /rest/v1.0/companies/{company_id}/accounting/close/flux/thresholds/{id}

Update a flux threshold

Change the amount, percent or active flag. Owner or controller with 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

Request body

  • flux_threshold
    objectrequired
  • flux_threshold.amount
    string
  • flux_threshold.percent
    string
  • flux_threshold.is_active
    boolean

Response · 200 · object

  • id
    integerrequired
  • account_type
    string | nullrequired
  • account_id
    integer | nullrequired
  • amount
    stringrequired
  • percent
    stringrequired
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Missing close_period, not an owner or controller, entity-restricted or project-scoped
  • 404Not found
  • 422Invalid body, or (explanations) no flux figures for that row

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/close/flux/thresholds/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "flux_threshold": {}
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/rec_rules

List reconciliation rules

Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • account_types
    string[]required
  • account_ids
    integer[]required
  • entity_ids
    integer[]required
  • source
    stringrequired
    One of: auto, tie_out, manual.
  • tie_out_key
    string | nullrequired
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • risk_rating
    stringrequired
    One of: low, medium, high.
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, 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/close/rec_rules" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/rec_rules

Create a reconciliation rule

Which balance sheet accounts need a reconciliation (by account type or list, optionally per entity), the supporting source (auto picks the subledger tie-out by account type: AP, AR, retainage, payroll liabilities, fixed assets, WIP, bank; else manual schedule lines) and the materiality (absolute and percent of the GL balance) and risk that set the review level (high risk, or medium and material: two reviewers) and frequency (low risk and immaterial: quarterly). Owner or controller with close_period. Audited. 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

  • rec_rule
    objectrequired
  • rec_rule.name
    stringrequired
  • rec_rule.account_types
    string[]
    One of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings.
  • rec_rule.account_ids
    integer[]
  • rec_rule.entity_ids
    integer[]
  • rec_rule.source
    stringrequired
    One of: auto, tie_out, manual.
  • rec_rule.tie_out_key
    string | null
    One of: ap, ap_retainage, ar, ar_retainage, payroll, assets, cash_reconciliation, job_cost, wip, wip_revenue, prepaids, null.
  • rec_rule.materiality_abs
    stringrequired
  • rec_rule.materiality_pct
    stringrequired
  • rec_rule.risk_rating
    stringrequired
    One of: low, medium, high.
  • rec_rule.is_active
    boolean

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • account_types
    string[]required
  • account_ids
    integer[]required
  • entity_ids
    integer[]required
  • source
    stringrequired
    One of: auto, tie_out, manual.
  • tie_out_key
    string | nullrequired
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • risk_rating
    stringrequired
    One of: low, medium, high.
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 409Idempotency-Key reused
  • 422Invalid rule

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/close/rec_rules" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "rec_rule": {
    "name": "string",
    "source": "auto",
    "materiality_abs": "string",
    "materiality_pct": "string",
    "risk_rating": "low"
  }
}'

Accounting / Fiscal Periods

PATCH /rest/v1.0/companies/{company_id}/accounting/close/rec_rules/{id}

Update a reconciliation rule

Name, active flag, materiality or risk. Existing reconciliations keep the parameters they were generated with. Owner or controller with close_period. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • rec_rule
    objectrequired
  • rec_rule.is_active
    boolean
  • rec_rule.materiality_abs
    string
  • rec_rule.materiality_pct
    string
  • rec_rule.risk_rating
    string
    One of: low, medium, high.
  • rec_rule.name
    string

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • account_types
    string[]required
  • account_ids
    integer[]required
  • entity_ids
    integer[]required
  • source
    stringrequired
    One of: auto, tie_out, manual.
  • tie_out_key
    string | nullrequired
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • risk_rating
    stringrequired
    One of: low, medium, high.
  • is_active
    booleanrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Invalid change

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/close/rec_rules/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "rec_rule": {}
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliations

List account reconciliations

The period's reconciliations in the grant's entity scope, each with its live GL balance (period balance snapshots), supporting balance (subledger tie-out or schedule lines), open reconciling items, unexplained difference, staleness and item aging. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • period_id
    integerqueryrequired
    The period
  • entity_id
    integerquery
    One entity
  • status
    stringquery
    One of: not_started, in_progress, prepared, reviewed.

Response · 200 · object[]

  • id
    integerrequired
  • period_id
    integerrequired
  • period_name
    stringrequired
  • entity_id
    integerrequired
  • rule_id
    integer | nullrequired
  • account
    objectrequired
  • account.id
    integerrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.type
    stringrequired
  • account.normal_balance
    stringrequired
  • source
    stringrequired
    One of: tie_out, manual.
  • tie_out_key
    string | nullrequired
  • risk_rating
    stringrequired
  • frequency
    stringrequired
    One of: monthly, quarterly.
  • review_level
    integerrequired
    One of: 1, 2.
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • material
    booleanrequired
  • tolerance
    stringrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • auto_reconciled
    booleanrequired
  • stale
    booleanrequired
  • stale_reason
    string | nullrequired
  • live
    objectrequired
  • live.gl_balance
    stringrequired
  • live.support_balance
    string | nullrequired
  • live.items_total
    stringrequired
  • live.schedule_total
    stringrequired
  • live.unexplained
    string | nullrequired
  • live.within_tolerance
    booleanrequired
  • live.tie_out
    object | nullrequired
  • live.bank_reconciliation
    object | nullrequired
  • signed
    objectrequired
  • signed.gl_balance
    string | nullrequired
  • signed.support_balance
    string | nullrequired
  • signed.items_total
    string | nullrequired
  • signed.unexplained
    string | nullrequired
  • signed.balance_debit
    string | nullrequired
  • signed.balance_credit
    string | nullrequired
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • second_reviewed_by_id
    integer | nullrequired
  • second_reviewed_at
    string | null (date-time)required
  • second_review_note
    string | nullrequired
  • aging
    objectrequired
  • aging.oldest_days
    integer | nullrequired
  • aging.buckets
    objectrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • items[].description
    stringrequired
  • items[].reference
    string | nullrequired
  • items[].amount
    stringrequired
  • items[].item_date
    string | null (date)required
  • items[].age_days
    integerrequired
  • items[].aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • items[].cleared
    booleanrequired
  • items[].cleared_at
    string | null (date-time)required
  • items[].carried_forward
    booleanrequired
  • items[].carried_from_item_id
    integer | nullrequired
  • items[].created_by_id
    integerrequired
  • items[].created_at
    string | null (date-time)required

Errors

  • 400period_id missing or unknown status
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Period not found

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}

Show an account reconciliation

Needs view_ledger and the reconciliation's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • period_name
    stringrequired
  • entity_id
    integerrequired
  • rule_id
    integer | nullrequired
  • account
    objectrequired
  • account.id
    integerrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.type
    stringrequired
  • account.normal_balance
    stringrequired
  • source
    stringrequired
    One of: tie_out, manual.
  • tie_out_key
    string | nullrequired
  • risk_rating
    stringrequired
  • frequency
    stringrequired
    One of: monthly, quarterly.
  • review_level
    integerrequired
    One of: 1, 2.
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • material
    booleanrequired
  • tolerance
    stringrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • auto_reconciled
    booleanrequired
  • stale
    booleanrequired
  • stale_reason
    string | nullrequired
  • live
    objectrequired
  • live.gl_balance
    stringrequired
  • live.support_balance
    string | nullrequired
  • live.items_total
    stringrequired
  • live.schedule_total
    stringrequired
  • live.unexplained
    string | nullrequired
  • live.within_tolerance
    booleanrequired
  • live.tie_out
    object | nullrequired
  • live.bank_reconciliation
    object | nullrequired
  • signed
    objectrequired
  • signed.gl_balance
    string | nullrequired
  • signed.support_balance
    string | nullrequired
  • signed.items_total
    string | nullrequired
  • signed.unexplained
    string | nullrequired
  • signed.balance_debit
    string | nullrequired
  • signed.balance_credit
    string | nullrequired
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • second_reviewed_by_id
    integer | nullrequired
  • second_reviewed_at
    string | null (date-time)required
  • second_review_note
    string | nullrequired
  • aging
    objectrequired
  • aging.oldest_days
    integer | nullrequired
  • aging.buckets
    objectrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • items[].description
    stringrequired
  • items[].reference
    string | nullrequired
  • items[].amount
    stringrequired
  • items[].item_date
    string | null (date)required
  • items[].age_days
    integerrequired
  • items[].aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • items[].cleared
    booleanrequired
  • items[].cleared_at
    string | null (date-time)required
  • items[].carried_forward
    booleanrequired
  • items[].carried_from_item_id
    integer | nullrequired
  • items[].created_by_id
    integerrequired
  • items[].created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachments

List attachments on an account reconciliation

Oldest first. Needs view_ledger and the reconciliation's entity scope; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

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

Errors

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

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachments

Attach a workpaper to an account reconciliation

Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES): statements, schedules and other support. Writes an attachment_added audit event on the reconciliation. Needs post_journal and the reconciliation's entity scope. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

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

Errors

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

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/items

Add a reconciling item or schedule line

A reconciling item explains GL vs support (signed, in the account's normal-balance direction; carried forward while open); a schedule line is the support of a manual reconciliation. Refused (409) while the reconciliation is signed. Needs post_journal. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • item
    objectrequired
  • item.kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • item.description
    stringrequired
  • item.amount
    stringrequired
  • item.item_date
    string (date)required
  • item.reference
    string | null

Response · 201 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • description
    stringrequired
  • reference
    string | nullrequired
  • amount
    stringrequired
  • item_date
    string | null (date)required
  • age_days
    integerrequired
  • aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • cleared
    booleanrequired
  • cleared_at
    string | null (date-time)required
  • carried_forward
    booleanrequired
  • carried_from_item_id
    integer | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Signed reconciliation, or Idempotency-Key reused
  • 422Invalid item, or a schedule line on a tie-out reconciliation

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/close/reconciliations/1/items" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "item": {
    "kind": "reconciling_item",
    "description": "string",
    "amount": "0.00",
    "item_date": "2026-11-01"
  }
}'

Accounting / Fiscal Periods

PATCH /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/items/{item_id}

Update or clear a reconciliation item

Edit the description, amount or reference, or clear (resolve) the item: a cleared item stops explaining the difference and is not carried forward. Refused (409) while signed. Needs post_journal. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • item
    objectrequired
  • item.description
    string
  • item.amount
    string
  • item.reference
    string | null
  • item.cleared
    boolean

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • description
    stringrequired
  • reference
    string | nullrequired
  • amount
    stringrequired
  • item_date
    string | null (date)required
  • age_days
    integerrequired
  • aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • cleared
    booleanrequired
  • cleared_at
    string | null (date-time)required
  • carried_forward
    booleanrequired
  • carried_from_item_id
    integer | nullrequired
  • created_by_id
    integerrequired
  • created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Signed reconciliation
  • 422Invalid change

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/close/reconciliations/1/items/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "item": {}
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/prepare

Prepare an account reconciliation

Sign as preparer (post_journal): the unexplained difference must be within the tolerance (the lesser of the absolute materiality and the percentage of the GL balance). Snapshots the cumulative posted debit and credit, support and items. A signed reconciliation that went stale may be prepared again. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • prepare
    objectrequired
  • prepare.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • period_name
    stringrequired
  • entity_id
    integerrequired
  • rule_id
    integer | nullrequired
  • account
    objectrequired
  • account.id
    integerrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.type
    stringrequired
  • account.normal_balance
    stringrequired
  • source
    stringrequired
    One of: tie_out, manual.
  • tie_out_key
    string | nullrequired
  • risk_rating
    stringrequired
  • frequency
    stringrequired
    One of: monthly, quarterly.
  • review_level
    integerrequired
    One of: 1, 2.
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • material
    booleanrequired
  • tolerance
    stringrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • auto_reconciled
    booleanrequired
  • stale
    booleanrequired
  • stale_reason
    string | nullrequired
  • live
    objectrequired
  • live.gl_balance
    stringrequired
  • live.support_balance
    string | nullrequired
  • live.items_total
    stringrequired
  • live.schedule_total
    stringrequired
  • live.unexplained
    string | nullrequired
  • live.within_tolerance
    booleanrequired
  • live.tie_out
    object | nullrequired
  • live.bank_reconciliation
    object | nullrequired
  • signed
    objectrequired
  • signed.gl_balance
    string | nullrequired
  • signed.support_balance
    string | nullrequired
  • signed.items_total
    string | nullrequired
  • signed.unexplained
    string | nullrequired
  • signed.balance_debit
    string | nullrequired
  • signed.balance_credit
    string | nullrequired
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • second_reviewed_by_id
    integer | nullrequired
  • second_reviewed_at
    string | null (date-time)required
  • second_review_note
    string | nullrequired
  • aging
    objectrequired
  • aging.oldest_days
    integer | nullrequired
  • aging.buckets
    objectrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • items[].description
    stringrequired
  • items[].reference
    string | nullrequired
  • items[].amount
    stringrequired
  • items[].item_date
    string | null (date)required
  • items[].age_days
    integerrequired
  • items[].aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • items[].cleared
    booleanrequired
  • items[].cleared_at
    string | null (date-time)required
  • items[].carried_forward
    booleanrequired
  • items[].carried_from_item_id
    integer | nullrequired
  • items[].created_by_id
    integerrequired
  • items[].created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Not in a state that allows this, changed concurrently, or stale since preparation
  • 422Invalid request, unavailable support, or an unexplained difference over tolerance

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/review

Review an account reconciliation

Sign as reviewer: needs close_period; the preparer is refused (403); a two-level reconciliation needs a second reviewer who is neither the preparer nor the first reviewer. Refused (409) if the GL or support moved since preparation. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • period_name
    stringrequired
  • entity_id
    integerrequired
  • rule_id
    integer | nullrequired
  • account
    objectrequired
  • account.id
    integerrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.type
    stringrequired
  • account.normal_balance
    stringrequired
  • source
    stringrequired
    One of: tie_out, manual.
  • tie_out_key
    string | nullrequired
  • risk_rating
    stringrequired
  • frequency
    stringrequired
    One of: monthly, quarterly.
  • review_level
    integerrequired
    One of: 1, 2.
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • material
    booleanrequired
  • tolerance
    stringrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • auto_reconciled
    booleanrequired
  • stale
    booleanrequired
  • stale_reason
    string | nullrequired
  • live
    objectrequired
  • live.gl_balance
    stringrequired
  • live.support_balance
    string | nullrequired
  • live.items_total
    stringrequired
  • live.schedule_total
    stringrequired
  • live.unexplained
    string | nullrequired
  • live.within_tolerance
    booleanrequired
  • live.tie_out
    object | nullrequired
  • live.bank_reconciliation
    object | nullrequired
  • signed
    objectrequired
  • signed.gl_balance
    string | nullrequired
  • signed.support_balance
    string | nullrequired
  • signed.items_total
    string | nullrequired
  • signed.unexplained
    string | nullrequired
  • signed.balance_debit
    string | nullrequired
  • signed.balance_credit
    string | nullrequired
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • second_reviewed_by_id
    integer | nullrequired
  • second_reviewed_at
    string | null (date-time)required
  • second_review_note
    string | nullrequired
  • aging
    objectrequired
  • aging.oldest_days
    integer | nullrequired
  • aging.buckets
    objectrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • items[].description
    stringrequired
  • items[].reference
    string | nullrequired
  • items[].amount
    stringrequired
  • items[].item_date
    string | null (date)required
  • items[].age_days
    integerrequired
  • items[].aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • items[].cleared
    booleanrequired
  • items[].cleared_at
    string | null (date-time)required
  • items[].carried_forward
    booleanrequired
  • items[].carried_from_item_id
    integer | nullrequired
  • items[].created_by_id
    integerrequired
  • items[].created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Not in a state that allows this, changed concurrently, or stale since preparation
  • 422Invalid request, unavailable support, or an unexplained difference over tolerance

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/unsign

Unsign an account reconciliation

Withdraws every sign-off (back to in_progress) with a reason. Needs close_period. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • unsign
    objectrequired
  • unsign.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • period_name
    stringrequired
  • entity_id
    integerrequired
  • rule_id
    integer | nullrequired
  • account
    objectrequired
  • account.id
    integerrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.type
    stringrequired
  • account.normal_balance
    stringrequired
  • source
    stringrequired
    One of: tie_out, manual.
  • tie_out_key
    string | nullrequired
  • risk_rating
    stringrequired
  • frequency
    stringrequired
    One of: monthly, quarterly.
  • review_level
    integerrequired
    One of: 1, 2.
  • materiality_abs
    stringrequired
  • materiality_pct
    stringrequired
  • material
    booleanrequired
  • tolerance
    stringrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • auto_reconciled
    booleanrequired
  • stale
    booleanrequired
  • stale_reason
    string | nullrequired
  • live
    objectrequired
  • live.gl_balance
    stringrequired
  • live.support_balance
    string | nullrequired
  • live.items_total
    stringrequired
  • live.schedule_total
    stringrequired
  • live.unexplained
    string | nullrequired
  • live.within_tolerance
    booleanrequired
  • live.tie_out
    object | nullrequired
  • live.bank_reconciliation
    object | nullrequired
  • signed
    objectrequired
  • signed.gl_balance
    string | nullrequired
  • signed.support_balance
    string | nullrequired
  • signed.items_total
    string | nullrequired
  • signed.unexplained
    string | nullrequired
  • signed.balance_debit
    string | nullrequired
  • signed.balance_credit
    string | nullrequired
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • second_reviewed_by_id
    integer | nullrequired
  • second_reviewed_at
    string | null (date-time)required
  • second_review_note
    string | nullrequired
  • aging
    objectrequired
  • aging.oldest_days
    integer | nullrequired
  • aging.buckets
    objectrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    stringrequired
    One of: reconciling_item, schedule_line.
  • items[].description
    stringrequired
  • items[].reference
    string | nullrequired
  • items[].amount
    stringrequired
  • items[].item_date
    string | null (date)required
  • items[].age_days
    integerrequired
  • items[].aging_bucket
    stringrequired
    One of: 0-30, 31-60, 61-90, over_90.
  • items[].cleared
    booleanrequired
  • items[].cleared_at
    string | null (date-time)required
  • items[].carried_forward
    booleanrequired
  • items[].carried_from_item_id
    integer | nullrequired
  • items[].created_by_id
    integerrequired
  • items[].created_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409Not in a state that allows this, changed concurrently, or stale since preparation
  • 422Invalid request, unavailable support, or an unexplained difference over tolerance

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/reconciliations/generate

Generate account reconciliations

Creates the period's due reconciliations (rules x accounts x entities with posted activity, due by frequency), carries open reconciling items and schedule lines forward from the latest earlier reconciliation with their original dates, then auto-reconciles those whose tie-out passes with nothing unexplained. 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

  • generate
    objectrequired
  • generate.period_id
    integerrequired
  • generate.entity_id
    integer | null

Response · 200 · object

  • created
    integerrequired
  • carried
    integerrequired
  • reconciled
    integerrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Period or entity not found

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/settings

Close cockpit settings

Whether the period close requires the cockpit tasks and account reconciliations to be reviewed, and the default template. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • require_tasks
    booleanrequired
  • require_recs
    booleanrequired
  • require_flux
    boolean
    GL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
  • default_template_id
    integer | nullrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, 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/close/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

PUT /rest/v1.0/companies/{company_id}/accounting/close/settings

Save close cockpit settings

Owner or controller with close_period and unrestricted entity access. With require_tasks the period close (prepare, approve and close) is refused while a required task of the scope is not reviewed; with require_recs a GL or whole-period close is refused while a due reconciliation is missing, not fully reviewed or stale; with require_flux a GL or whole-period close is refused while a flux variance above threshold is unexplained, unreviewed or stale. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • settings
    objectrequired
  • settings.require_tasks
    booleanrequired
  • settings.require_recs
    booleanrequired
  • settings.require_flux
    boolean
    GL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
  • settings.default_template_id
    integer | null

Response · 200 · object

  • require_tasks
    booleanrequired
  • require_recs
    booleanrequired
  • require_flux
    boolean
    GL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
  • default_template_id
    integer | nullrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 422Invalid settings or an unknown template

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/close/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "require_tasks": true,
    "require_recs": true
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}

Show a close task

Needs view_ledger and the task's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integer | nullrequired
  • key
    stringrequired
  • title
    stringrequired
  • category
    stringrequired
  • close_module
    string | nullrequired
  • owner_id
    integer | nullrequired
  • reviewer_id
    integer | nullrequired
  • due_date
    string | null (date)required
  • depends_on
    string[]required
  • evidence
    string | nullrequired
  • required
    booleanrequired
  • instructions
    string | nullrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • auto_completed
    booleanrequired
  • evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • evidence_message
    string | nullrequired
  • evidence_checked_at
    string | null (date-time)required
  • stale_at
    string | null (date-time)required
  • stale_reason
    string | nullrequired
  • overdue
    booleanrequired
  • open_dependencies
    string[]required
  • critical
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/prepare

Prepare a close task

Sign as preparer: needs post_journal, the task's owner or a close_period user, and every dependency reviewed. Evidence tasks complete from evidence only (422). Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • prepare
    objectrequired
  • prepare.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integer | nullrequired
  • key
    stringrequired
  • title
    stringrequired
  • category
    stringrequired
  • close_module
    string | nullrequired
  • owner_id
    integer | nullrequired
  • reviewer_id
    integer | nullrequired
  • due_date
    string | null (date)required
  • depends_on
    string[]required
  • evidence
    string | nullrequired
  • required
    booleanrequired
  • instructions
    string | nullrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • auto_completed
    booleanrequired
  • evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • evidence_message
    string | nullrequired
  • evidence_checked_at
    string | null (date-time)required
  • stale_at
    string | null (date-time)required
  • stale_reason
    string | nullrequired
  • overdue
    booleanrequired
  • open_dependencies
    string[]required
  • critical
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The task is not in a state that allows this
  • 422Invalid request or unreviewed dependencies

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/review

Review a close task

Sign as reviewer: needs close_period; the preparer is refused (403, segregation of duties); a designated reviewer is required unless the reviewer is an owner or controller. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integer | nullrequired
  • key
    stringrequired
  • title
    stringrequired
  • category
    stringrequired
  • close_module
    string | nullrequired
  • owner_id
    integer | nullrequired
  • reviewer_id
    integer | nullrequired
  • due_date
    string | null (date)required
  • depends_on
    string[]required
  • evidence
    string | nullrequired
  • required
    booleanrequired
  • instructions
    string | nullrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • auto_completed
    booleanrequired
  • evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • evidence_message
    string | nullrequired
  • evidence_checked_at
    string | null (date-time)required
  • stale_at
    string | null (date-time)required
  • stale_reason
    string | nullrequired
  • overdue
    booleanrequired
  • open_dependencies
    string[]required
  • critical
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The task is not in a state that allows this
  • 422Invalid request or unreviewed dependencies

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/start

Start a close task

not_started to in_progress. Needs post_journal; the task's owner or a close_period user. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integer | nullrequired
  • key
    stringrequired
  • title
    stringrequired
  • category
    stringrequired
  • close_module
    string | nullrequired
  • owner_id
    integer | nullrequired
  • reviewer_id
    integer | nullrequired
  • due_date
    string | null (date)required
  • depends_on
    string[]required
  • evidence
    string | nullrequired
  • required
    booleanrequired
  • instructions
    string | nullrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • auto_completed
    booleanrequired
  • evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • evidence_message
    string | nullrequired
  • evidence_checked_at
    string | null (date-time)required
  • stale_at
    string | null (date-time)required
  • stale_reason
    string | nullrequired
  • overdue
    booleanrequired
  • open_dependencies
    string[]required
  • critical
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The task is not in a state that allows this
  • 422Invalid request or unreviewed dependencies

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/unsign

Unsign a close task

Withdraws the preparation and review (back to in_progress) with a reason; tasks depending on it lose their sign-off too. Needs close_period. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • unsign
    objectrequired
  • unsign.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integer | nullrequired
  • key
    stringrequired
  • title
    stringrequired
  • category
    stringrequired
  • close_module
    string | nullrequired
  • owner_id
    integer | nullrequired
  • reviewer_id
    integer | nullrequired
  • due_date
    string | null (date)required
  • depends_on
    string[]required
  • evidence
    string | nullrequired
  • required
    booleanrequired
  • instructions
    string | nullrequired
  • status
    stringrequired
    One of: not_started, in_progress, prepared, reviewed.
  • prepared_by_id
    integer | nullrequired
  • prepared_at
    string | null (date-time)required
  • prep_note
    string | nullrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • auto_completed
    booleanrequired
  • evidence_status
    string | nullrequired
    One of: passed, failed, unavailable, null.
  • evidence_message
    string | nullrequired
  • evidence_checked_at
    string | null (date-time)required
  • stale_at
    string | null (date-time)required
  • stale_reason
    string | nullrequired
  • overdue
    booleanrequired
  • open_dependencies
    string[]required
  • critical
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The task is not in a state that allows this
  • 422Invalid request or unreviewed dependencies

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/templates

List close templates

Every close template with its tasks. Needs view_ledger. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • is_active
    booleanrequired
  • revision
    integerrequired
  • created_at
    string | null (date-time)required
  • updated_at
    string | null (date-time)required
  • tasks
    object[]required
  • tasks[].key
    stringrequired
  • tasks[].title
    stringrequired
  • tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • tasks[].close_module
    string | nullrequired
  • tasks[].owner_id
    integer | nullrequired
  • tasks[].reviewer_id
    integer | nullrequired
  • tasks[].due_day_offset
    integerrequired
  • tasks[].depends_on
    string[]required
  • tasks[].evidence
    string | nullrequired
  • tasks[].required
    booleanrequired
  • tasks[].instructions
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, 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/close/templates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/close/templates

Create a close template

Tasks with owner, reviewer, due day offset (business days after the period end), dependencies (acyclic, by key), a category, the module close the task gates and optional system evidence that completes it. Owner or controller with close_period. Audited. 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

  • template
    objectrequired
  • template.name
    stringrequired
  • template.description
    string | null
  • template.is_active
    boolean
  • template.tasks
    object[]required
  • template.tasks[].key
    stringrequired
  • template.tasks[].title
    stringrequired
  • template.tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • template.tasks[].close_module
    string | null
    One of: ap, ar, payroll, jc, cm, gl, null.
  • template.tasks[].owner_id
    integer | null
  • template.tasks[].reviewer_id
    integer | null
  • template.tasks[].due_day_offset
    integerrequired
  • template.tasks[].depends_on
    string[]
  • template.tasks[].evidence
    string | null
    One of: tie_out:ap, tie_out:ap_retainage, tie_out:ar, tie_out:ar_retainage, tie_out:payroll, tie_out:assets, tie_out:cash_reconciliation, tie_out:job_cost, tie_out:wip, tie_out:wip_revenue, tie_out:prepaids, readiness:ap, readiness:ar, readiness:payroll, readiness:jc, readiness:cm, readiness:gl, run:depreciation, run:allocation, run:wip, run:eliminations, run:prepaid_amortization, recs:complete, null.
  • template.tasks[].required
    boolean
  • template.tasks[].instructions
    string | null
  • revision
    integer

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • is_active
    booleanrequired
  • revision
    integerrequired
  • created_at
    string | null (date-time)required
  • updated_at
    string | null (date-time)required
  • tasks
    object[]required
  • tasks[].key
    stringrequired
  • tasks[].title
    stringrequired
  • tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • tasks[].close_module
    string | nullrequired
  • tasks[].owner_id
    integer | nullrequired
  • tasks[].reviewer_id
    integer | nullrequired
  • tasks[].due_day_offset
    integerrequired
  • tasks[].depends_on
    string[]required
  • tasks[].evidence
    string | nullrequired
  • tasks[].required
    booleanrequired
  • tasks[].instructions
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 409A template with this name exists, or the Idempotency-Key was reused
  • 422Invalid tasks, unknown or cyclic dependencies, or an owner outside the company

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/close/templates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "template": {
    "name": "string",
    "tasks": [
      {
        "key": "string",
        "title": "string",
        "category": "subledger_close",
        "due_day_offset": 1
      }
    ]
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/close/templates/{id}

Show a close template

Needs view_ledger. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • is_active
    booleanrequired
  • revision
    integerrequired
  • created_at
    string | null (date-time)required
  • updated_at
    string | null (date-time)required
  • tasks
    object[]required
  • tasks[].key
    stringrequired
  • tasks[].title
    stringrequired
  • tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • tasks[].close_module
    string | nullrequired
  • tasks[].owner_id
    integer | nullrequired
  • tasks[].reviewer_id
    integer | nullrequired
  • tasks[].due_day_offset
    integerrequired
  • tasks[].depends_on
    string[]required
  • tasks[].evidence
    string | nullrequired
  • tasks[].required
    booleanrequired
  • tasks[].instructions
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Fiscal Periods

PUT /rest/v1.0/companies/{company_id}/accounting/close/templates/{id}

Replace a close template

Replaces the name, description and tasks; revision refuses a stale edit (409). Tasks already generated for periods keep their copy. Owner or controller with close_period. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • template
    objectrequired
  • template.name
    stringrequired
  • template.description
    string | null
  • template.is_active
    boolean
  • template.tasks
    object[]required
  • template.tasks[].key
    stringrequired
  • template.tasks[].title
    stringrequired
  • template.tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • template.tasks[].close_module
    string | null
    One of: ap, ar, payroll, jc, cm, gl, null.
  • template.tasks[].owner_id
    integer | null
  • template.tasks[].reviewer_id
    integer | null
  • template.tasks[].due_day_offset
    integerrequired
  • template.tasks[].depends_on
    string[]
  • template.tasks[].evidence
    string | null
    One of: tie_out:ap, tie_out:ap_retainage, tie_out:ar, tie_out:ar_retainage, tie_out:payroll, tie_out:assets, tie_out:cash_reconciliation, tie_out:job_cost, tie_out:wip, tie_out:wip_revenue, tie_out:prepaids, readiness:ap, readiness:ar, readiness:payroll, readiness:jc, readiness:cm, readiness:gl, run:depreciation, run:allocation, run:wip, run:eliminations, run:prepaid_amortization, recs:complete, null.
  • template.tasks[].required
    boolean
  • template.tasks[].instructions
    string | null
  • revision
    integer

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • is_active
    booleanrequired
  • revision
    integerrequired
  • created_at
    string | null (date-time)required
  • updated_at
    string | null (date-time)required
  • tasks
    object[]required
  • tasks[].key
    stringrequired
  • tasks[].title
    stringrequired
  • tasks[].category
    stringrequired
    One of: subledger_close, accruals, reconciliations, reporting, review, other.
  • tasks[].close_module
    string | nullrequired
  • tasks[].owner_id
    integer | nullrequired
  • tasks[].reviewer_id
    integer | nullrequired
  • tasks[].due_day_offset
    integerrequired
  • tasks[].depends_on
    string[]required
  • tasks[].evidence
    string | nullrequired
  • tasks[].required
    booleanrequired
  • tasks[].instructions
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
  • 404Not found in this company
  • 409The template changed, or the name is taken
  • 422Invalid tasks

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/close/templates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "template": {
    "name": "string",
    "tasks": [
      {
        "key": "string",
        "title": "string",
        "category": "subledger_close",
        "due_day_offset": 1
      }
    ]
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs

List equity-method runs

Runs newest first. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • investee_entity_id
    integerquery
    Filter: investee
  • period_id
    integerquery
    Filter: period

Response · 200 · object[]

  • id
    integerrequired
  • investor_entity_id
    integerrequired
  • investee_entity_id
    integerrequired
  • ownership_id
    integer
  • period_id
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • as_of
    string (date)
  • income_source
    string
    One of: ledger, manual.
  • source_note
    string | null
  • investee_net_income
    string
    Decimal string with two places
  • investee_oci
    string
    Decimal string with two places
  • share_of_income
    string
    Decimal string with two places
  • recognized_income
    string
    Decimal string with two places
  • share_of_oci
    string
    Decimal string with two places
  • carrying_before
    string
    Decimal string with two places
  • suspended_before
    string
    Decimal string with two places
  • suspended_after
    string
    Decimal string with two places
  • post_income
    string
    Decimal string with two places
  • post_oci
    string
    Decimal string with two places
  • segments
    object[]
  • evidence_hash
    string
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_id
    integer | null
  • cancel_reason
    string | null
  • unchanged
    boolean

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs

Prepare an equity-method run

The investor's share of the investee's net income and OCI for a period (ASC 323-10-35), segment by segment through ownership changes, losses limited to the carrying amount with the excess suspended. An investee kept elsewhere takes a reported net income with its source. The same evidence returns the prepared run (200); a revision posts only the change since earlier posted revisions. Needs post_journal over every entity. 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

  • run
    objectrequired
  • run.investee_entity_id
    integerrequired
  • run.period_id
    integerrequired
  • run.investee_net_income
    string
  • run.investee_oci
    string
  • run.source_note
    string

Response · 200 · object

  • id
    integerrequired
  • investor_entity_id
    integerrequired
  • investee_entity_id
    integerrequired
  • ownership_id
    integer
  • period_id
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • as_of
    string (date)
  • income_source
    string
    One of: ledger, manual.
  • source_note
    string | null
  • investee_net_income
    string
    Decimal string with two places
  • investee_oci
    string
    Decimal string with two places
  • share_of_income
    string
    Decimal string with two places
  • recognized_income
    string
    Decimal string with two places
  • share_of_oci
    string
    Decimal string with two places
  • carrying_before
    string
    Decimal string with two places
  • suspended_before
    string
    Decimal string with two places
  • suspended_after
    string
    Decimal string with two places
  • post_income
    string
    Decimal string with two places
  • post_oci
    string
    Decimal string with two places
  • segments
    object[]
  • evidence_hash
    string
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_id
    integer | null
  • cancel_reason
    string | null
  • unchanged
    boolean

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}

Get an equity-method run

One run. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • investor_entity_id
    integerrequired
  • investee_entity_id
    integerrequired
  • ownership_id
    integer
  • period_id
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • as_of
    string (date)
  • income_source
    string
    One of: ledger, manual.
  • source_note
    string | null
  • investee_net_income
    string
    Decimal string with two places
  • investee_oci
    string
    Decimal string with two places
  • share_of_income
    string
    Decimal string with two places
  • recognized_income
    string
    Decimal string with two places
  • share_of_oci
    string
    Decimal string with two places
  • carrying_before
    string
    Decimal string with two places
  • suspended_before
    string
    Decimal string with two places
  • suspended_after
    string
    Decimal string with two places
  • post_income
    string
    Decimal string with two places
  • post_oci
    string
    Decimal string with two places
  • segments
    object[]
  • evidence_hash
    string
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_id
    integer | null
  • cancel_reason
    string | null
  • unchanged
    boolean

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}/decision

Approve or cancel an equity-method run

approve (approve_journal, never the preparer): recomputes the evidence (409 if anything moved) and posts the investor's entry (investment against equity in earnings and, for OCI, the CTA account). cancel (post_journal, with a reason). A repeat of a finished decision returns the run. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.action
    stringrequired
    One of: approve, cancel.
  • decision.reason
    string
    Required to cancel

Response · 200 · object

  • id
    integerrequired
  • investor_entity_id
    integerrequired
  • investee_entity_id
    integerrequired
  • ownership_id
    integer
  • period_id
    integerrequired
  • revision
    integerrequired
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • as_of
    string (date)
  • income_source
    string
    One of: ledger, manual.
  • source_note
    string | null
  • investee_net_income
    string
    Decimal string with two places
  • investee_oci
    string
    Decimal string with two places
  • share_of_income
    string
    Decimal string with two places
  • recognized_income
    string
    Decimal string with two places
  • share_of_oci
    string
    Decimal string with two places
  • carrying_before
    string
    Decimal string with two places
  • suspended_before
    string
    Decimal string with two places
  • suspended_after
    string
    Decimal string with two places
  • post_income
    string
    Decimal string with two places
  • post_oci
    string
    Decimal string with two places
  • segments
    object[]
  • evidence_hash
    string
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_id
    integer | null
  • cancel_reason
    string | null
  • unchanged
    boolean

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes

List intercompany disputes

Newest first. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • status
    stringquery
    Filter: status One of: open, adjustment_pending, resolved, withdrawn.

Response · 200 · object[]

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes

Raise an intercompany dispute

On a pair and currency whose difference on as_of exceeds the tolerance; the active dispute on the same pair and currency is returned instead (200). Needs post_journal over every entity. Audited. 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

  • dispute
    objectrequired
  • dispute.entity_a_id
    integerrequired
  • dispute.entity_b_id
    integerrequired
  • dispute.currency
    stringrequired
  • dispute.as_of
    string (date)required
  • dispute.note
    string

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/disputes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "dispute": {
    "entity_a_id": 1,
    "entity_b_id": 1,
    "currency": "string",
    "as_of": "2026-11-01"
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}

Get an intercompany dispute

One dispute with its history (raised, assigned, comments, adjustment proposed, approved or rejected, resolved, withdrawn). Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/adjustment

Propose the adjusting entry

Proposes the entry in the responsible entity that brings the pair's difference to zero on posting_date: its intercompany account (due-from or due-to by direction, naming the other entity) against offset_account_id. The dispute waits for a second user's decision. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • adjustment
    objectrequired
  • adjustment.posting_date
    string (date)required
  • adjustment.offset_account_id
    integerrequired
  • adjustment.memo
    string

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/disputes/1/adjustment" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "adjustment": {
    "posting_date": "2026-11-01",
    "offset_account_id": 1
  }
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/assign

Assign an intercompany dispute

Assigns an open dispute to a user with accounting access and the entity (one of the pair) that must correct it. The same assignment again changes nothing. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • assignment
    objectrequired
  • assignment.assignee_user_id
    integerrequired
  • assignment.responsible_entity_id
    integerrequired
  • assignment.note
    string

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/disputes/1/assign" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "assignment": {
    "assignee_user_id": 1,
    "responsible_entity_id": 1
  }
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/comments

Comment on an intercompany dispute

Adds a comment to the dispute's history. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • comment
    objectrequired
  • comment.body
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/decision

Approve or reject the adjusting entry

approve (approve_journal, never the proposer): re-checks the difference (409 if it moved), posts the entry and resolves the dispute. reject (post_journal, with a reason) reopens it. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.action
    stringrequired
    One of: approve, reject.
  • decision.reason
    string
    Required to reject

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/resolve

Resolve or withdraw an intercompany dispute

resolve: allowed once the pair's difference today is within the tolerance (422 otherwise); withdraw: closes it with the note. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • resolution
    objectrequired
  • resolution.action
    stringrequired
    One of: resolve, withdraw.
  • resolution.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_a_id
    integerrequired
  • entity_b_id
    integerrequired
  • currency
    stringrequired
  • as_of
    string (date)
  • difference
    stringrequired
    Decimal string with two places
  • status
    stringrequired
    One of: open, adjustment_pending, resolved, withdrawn.
  • assignee_user_id
    integer | null
  • responsible_entity_id
    integer | null
  • raised_by_id
    integer
  • proposal
    object | null
  • proposed_by_id
    integer | null
  • proposed_at
    string | null (date-time)
  • entry_id
    integer | null
  • resolved_by_id
    integer | null
  • resolved_at
    string | null (date-time)
  • resolution
    string | null
  • created_at
    string (date-time)
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
  • events[].actor_id
    integer
  • events[].body
    string | null
  • events[].data
    any
  • events[].created_at
    string (date-time)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/disputes/1/resolve" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "resolution": {
    "action": "resolve",
    "note": "string"
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements

List intercompany settlement runs

Newest first. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • as_of
    string (date)required
  • mode
    stringrequired
    One of: cash, netting.
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • evidence_hash
    string
  • lines
    object[]required
  • lines[].entity_id
    integer
  • lines[].counterparty_entity_id
    integer | null
  • lines[].account_id
    integer
  • lines[].debit
    string
    Decimal string with two places
  • lines[].credit
    string
    Decimal string with two places
  • pairs
    object[]
  • pairs[].entity_a_id
    integer
  • pairs[].entity_b_id
    integer
  • pairs[].amount
    string
    Decimal string with two places
  • cash_accounts
    object | null
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_ids
    integer[]
  • cancel_reason
    string | null
  • unchanged
    boolean
  • skipped
    object[]
  • skipped[].entity_a_id
    integer
  • skipped[].entity_b_id
    integer
  • skipped[].reason
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements

Prepare an intercompany settlement

cash: every matched pair in the base currency is cleared through the entities' cash accounts; netting: each entity's balances against one counterparty are offset into one account. Pairs that do not match, lack a cash account or are in a foreign currency are skipped (listed). The same evidence returns the prepared run (200). Needs post_journal over every entity. 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

  • settlement
    objectrequired
  • settlement.as_of
    string (date)required
  • settlement.mode
    stringrequired
    One of: cash, netting.
  • settlement.cash_accounts
    object[]
  • settlement.cash_accounts[].entity_id
    integerrequired
  • settlement.cash_accounts[].account_id
    integerrequired
  • settlement.pairs
    object[]
  • settlement.pairs[].entity_a_id
    integerrequired
  • settlement.pairs[].entity_b_id
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • as_of
    string (date)required
  • mode
    stringrequired
    One of: cash, netting.
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • evidence_hash
    string
  • lines
    object[]required
  • lines[].entity_id
    integer
  • lines[].counterparty_entity_id
    integer | null
  • lines[].account_id
    integer
  • lines[].debit
    string
    Decimal string with two places
  • lines[].credit
    string
    Decimal string with two places
  • pairs
    object[]
  • pairs[].entity_a_id
    integer
  • pairs[].entity_b_id
    integer
  • pairs[].amount
    string
    Decimal string with two places
  • cash_accounts
    object | null
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_ids
    integer[]
  • cancel_reason
    string | null
  • unchanged
    boolean
  • skipped
    object[]
  • skipped[].entity_a_id
    integer
  • skipped[].entity_b_id
    integer
  • skipped[].reason
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/settlements" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "settlement": {
    "as_of": "2026-11-01",
    "mode": "cash"
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}

Get an intercompany settlement run

One run with its lines and settled pairs. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • as_of
    string (date)required
  • mode
    stringrequired
    One of: cash, netting.
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • evidence_hash
    string
  • lines
    object[]required
  • lines[].entity_id
    integer
  • lines[].counterparty_entity_id
    integer | null
  • lines[].account_id
    integer
  • lines[].debit
    string
    Decimal string with two places
  • lines[].credit
    string
    Decimal string with two places
  • pairs
    object[]
  • pairs[].entity_a_id
    integer
  • pairs[].entity_b_id
    integer
  • pairs[].amount
    string
    Decimal string with two places
  • cash_accounts
    object | null
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_ids
    integer[]
  • cancel_reason
    string | null
  • unchanged
    boolean
  • skipped
    object[]
  • skipped[].entity_a_id
    integer
  • skipped[].entity_b_id
    integer
  • skipped[].reason
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}/decision

Approve or cancel an intercompany settlement

approve (approve_journal, never the preparer): recomputes (409 if balances moved) and posts one IC entry per entity, keyed by run and line so a retry posts nothing twice. cancel (post_journal, with a reason). Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.action
    stringrequired
    One of: approve, cancel.
  • decision.reason
    string
    Required to cancel

Response · 200 · object

  • id
    integerrequired
  • as_of
    string (date)required
  • mode
    stringrequired
    One of: cash, netting.
  • status
    stringrequired
    One of: prepared, posted, cancelled, superseded.
  • evidence_hash
    string
  • lines
    object[]required
  • lines[].entity_id
    integer
  • lines[].counterparty_entity_id
    integer | null
  • lines[].account_id
    integer
  • lines[].debit
    string
    Decimal string with two places
  • lines[].credit
    string
    Decimal string with two places
  • pairs
    object[]
  • pairs[].entity_a_id
    integer
  • pairs[].entity_b_id
    integer
  • pairs[].amount
    string
    Decimal string with two places
  • cash_accounts
    object | null
  • prepared_by_id
    integer
  • prepared_at
    string (date-time)
  • approved_by_id
    integer | null
  • approved_at
    string | null (date-time)
  • entry_ids
    integer[]
  • cancel_reason
    string | null
  • unchanged
    boolean
  • skipped
    object[]
  • skipped[].entity_a_id
    integer
  • skipped[].entity_b_id
    integer
  • skipped[].reason
    string

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers

List intercompany asset transfers

Equipment and inventory sold between group entities, with profit, recognized and deferred amounts as of as_of. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • as_of
    string (date)query
    Date for the status amounts (default: today)
  • include_voided
    stringquery
    Include voided transfers One of: true, false.

Response · 200 · object[]

  • id
    integerrequired
  • kind
    stringrequired
    One of: fixed_asset, inventory.
  • seller_entity_id
    integerrequired
  • buyer_entity_id
    integerrequired
  • transfer_date
    string (date)required
  • sale_amount
    stringrequired
    Decimal string with two places
  • seller_cost
    stringrequired
    Decimal string with two places
  • seller_gain_account_id
    integer
  • seller_cost_account_id
    integer | null
  • buyer_asset_account_id
    integer
  • buyer_expense_account_id
    integer
  • useful_life_months
    integer | null
  • depreciation_start
    string | null (date)
  • memo
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    boolean
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
    One of: sold, disposed.
  • events[].event_date
    string (date)
  • events[].percent
    string
  • events[].note
    string | null
  • events[].created_by_id
    integer
  • status
    objectrequired
  • status.profit
    string
    Decimal string with two places
  • status.recognized
    string
    Decimal string with two places
  • status.deferred
    string
    Decimal string with two places
  • status.as_of
    string (date)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers

Register an intercompany asset transfer

Consolidation defers the seller's profit (sale amount less carrying amount) and recognizes it as the buyer depreciates the equipment (useful life from the depreciation start month) or sells the inventory on. Both entities report in the base currency. The identical active transfer is returned (200). Refused in a closed period. Needs post_journal over every entity. Audited. 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

  • transfer
    objectrequired
  • transfer.kind
    stringrequired
    One of: fixed_asset, inventory.
  • transfer.seller_entity_id
    integerrequired
  • transfer.buyer_entity_id
    integerrequired
  • transfer.transfer_date
    string (date)required
  • transfer.sale_amount
    stringrequired
  • transfer.seller_cost
    stringrequired
  • transfer.seller_gain_account_id
    integerrequired
  • transfer.seller_cost_account_id
    integer | null
  • transfer.buyer_asset_account_id
    integerrequired
  • transfer.buyer_expense_account_id
    integerrequired
  • transfer.useful_life_months
    integer | null
  • transfer.depreciation_start
    string | null (date)
  • transfer.memo
    string | null

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: fixed_asset, inventory.
  • seller_entity_id
    integerrequired
  • buyer_entity_id
    integerrequired
  • transfer_date
    string (date)required
  • sale_amount
    stringrequired
    Decimal string with two places
  • seller_cost
    stringrequired
    Decimal string with two places
  • seller_gain_account_id
    integer
  • seller_cost_account_id
    integer | null
  • buyer_asset_account_id
    integer
  • buyer_expense_account_id
    integer
  • useful_life_months
    integer | null
  • depreciation_start
    string | null (date)
  • memo
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    boolean
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
    One of: sold, disposed.
  • events[].event_date
    string (date)
  • events[].percent
    string
  • events[].note
    string | null
  • events[].created_by_id
    integer
  • status
    objectrequired
  • status.profit
    string
    Decimal string with two places
  • status.recognized
    string
    Decimal string with two places
  • status.deferred
    string
    Decimal string with two places
  • status.as_of
    string (date)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/transfers" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "transfer": {
    "kind": "fixed_asset",
    "seller_entity_id": 1,
    "buyer_entity_id": 1,
    "transfer_date": "2026-11-01",
    "sale_amount": "0.00",
    "seller_cost": "0.00",
    "seller_gain_account_id": 1,
    "buyer_asset_account_id": 1,
    "buyer_expense_account_id": 1
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}

Get an intercompany asset transfer

One transfer with its events and status amounts as of as_of. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • as_of
    string (date)query
    Date for the status amounts (default: today)

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: fixed_asset, inventory.
  • seller_entity_id
    integerrequired
  • buyer_entity_id
    integerrequired
  • transfer_date
    string (date)required
  • sale_amount
    stringrequired
    Decimal string with two places
  • seller_cost
    stringrequired
    Decimal string with two places
  • seller_gain_account_id
    integer
  • seller_cost_account_id
    integer | null
  • buyer_asset_account_id
    integer
  • buyer_expense_account_id
    integer
  • useful_life_months
    integer | null
  • depreciation_start
    string | null (date)
  • memo
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    boolean
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
    One of: sold, disposed.
  • events[].event_date
    string (date)
  • events[].percent
    string
  • events[].note
    string | null
  • events[].created_by_id
    integer
  • status
    objectrequired
  • status.profit
    string
    Decimal string with two places
  • status.recognized
    string
    Decimal string with two places
  • status.deferred
    string
    Decimal string with two places
  • status.as_of
    string (date)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/events

Record a sale on or a disposal

sold (inventory): percent of the transferred goods sold to a third party on event_date; disposed: the buyer disposed of the asset, recognizing what remains. Refused in a closed period. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • event
    objectrequired
  • event.kind
    stringrequired
    One of: sold, disposed.
  • event.event_date
    string (date)required
  • event.percent
    string
    Percent 0-100, up to four decimals
  • event.note
    string

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: fixed_asset, inventory.
  • seller_entity_id
    integerrequired
  • buyer_entity_id
    integerrequired
  • transfer_date
    string (date)required
  • sale_amount
    stringrequired
    Decimal string with two places
  • seller_cost
    stringrequired
    Decimal string with two places
  • seller_gain_account_id
    integer
  • seller_cost_account_id
    integer | null
  • buyer_asset_account_id
    integer
  • buyer_expense_account_id
    integer
  • useful_life_months
    integer | null
  • depreciation_start
    string | null (date)
  • memo
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    boolean
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
    One of: sold, disposed.
  • events[].event_date
    string (date)
  • events[].percent
    string
  • events[].note
    string | null
  • events[].created_by_id
    integer
  • status
    objectrequired
  • status.profit
    string
    Decimal string with two places
  • status.recognized
    string
    Decimal string with two places
  • status.deferred
    string
    Decimal string with two places
  • status.as_of
    string (date)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ic/transfers/1/events" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "event": {
    "kind": "sold",
    "event_date": "2026-11-01"
  }
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/void

Void an intercompany asset transfer

Marks it void with a reason (kept; append-only). Refused in a closed period. Needs post_journal. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: fixed_asset, inventory.
  • seller_entity_id
    integerrequired
  • buyer_entity_id
    integerrequired
  • transfer_date
    string (date)required
  • sale_amount
    stringrequired
    Decimal string with two places
  • seller_cost
    stringrequired
    Decimal string with two places
  • seller_gain_account_id
    integer
  • seller_cost_account_id
    integer | null
  • buyer_asset_account_id
    integer
  • buyer_expense_account_id
    integer
  • useful_life_months
    integer | null
  • depreciation_start
    string | null (date)
  • memo
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    boolean
  • voided_at
    string | null (date-time)
  • void_reason
    string | null
  • events
    object[]
  • events[].id
    integer
  • events[].kind
    string
    One of: sold, disposed.
  • events[].event_date
    string (date)
  • events[].percent
    string
  • events[].note
    string | null
  • events[].created_by_id
    integer
  • status
    objectrequired
  • status.profit
    string
    Decimal string with two places
  • status.recognized
    string
    Decimal string with two places
  • status.deferred
    string
    Decimal string with two places
  • status.as_of
    string (date)

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership

List ownership versions

Effective-dated, append-only ownership versions (parent, child, ownership and voting percent, method: full, equity, cost or none), oldest first per child. Needs a grant over every entity. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • child_entity_id
    integerquery
    Filter: child entity
  • include_voided
    stringquery
    Include voided versions One of: true, false.

Response · 200 · object[]

  • id
    integerrequired
  • parent_entity_id
    integerrequired
  • child_entity_id
    integerrequired
  • ownership_pct
    stringrequired
  • voting_pct
    stringrequired
  • nci_pct
    string | null
  • method
    stringrequired
    One of: full, equity, cost, none.
  • effective_from
    string (date)required
  • investment_account_id
    integer | null
  • earnings_account_id
    integer | null
  • control_basis
    string | null
  • note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    booleanrequired
  • voided_at
    string | null (date-time)
  • voided_by_id
    integer | null
  • void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership

Record an ownership version

Adds a version effective from effective_from; the relationship in force on a date is the child's latest version on or before it. Full consolidation needs a voting majority or a stated control basis; the equity method needs the investment and equity-in-earnings accounts. Refused (422) when it would change a closed period or form a cycle; the identical version again returns it (200); a different version on the same day is 409. Needs manage_coa over every entity. Audited. 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

  • ownership
    objectrequired
  • ownership.parent_entity_id
    integerrequired
  • ownership.child_entity_id
    integerrequired
  • ownership.ownership_pct
    stringrequired
    Percent 0-100, up to four decimals
  • ownership.voting_pct
    string
    Voting percent (default: the ownership percent)
  • ownership.method
    stringrequired
    One of: full, equity, cost, none.
  • ownership.effective_from
    string (date)required
  • ownership.investment_account_id
    integer | null
  • ownership.earnings_account_id
    integer | null
  • ownership.control_basis
    string | null
  • ownership.note
    string | null

Response · 200 · object

  • id
    integerrequired
  • parent_entity_id
    integerrequired
  • child_entity_id
    integerrequired
  • ownership_pct
    stringrequired
  • voting_pct
    stringrequired
  • nci_pct
    string | null
  • method
    stringrequired
    One of: full, equity, cost, none.
  • effective_from
    string (date)required
  • investment_account_id
    integer | null
  • earnings_account_id
    integer | null
  • control_basis
    string | null
  • note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    booleanrequired
  • voided_at
    string | null (date-time)
  • voided_by_id
    integer | null
  • void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/consolidation/ownership" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "ownership": {
    "parent_entity_id": 1,
    "child_entity_id": 1,
    "ownership_pct": "string",
    "method": "full",
    "effective_from": "2026-11-01"
  }
}'

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}

Get an ownership version

One ownership version, voided or not. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • parent_entity_id
    integerrequired
  • child_entity_id
    integerrequired
  • ownership_pct
    stringrequired
  • voting_pct
    stringrequired
  • nci_pct
    string | null
  • method
    stringrequired
    One of: full, equity, cost, none.
  • effective_from
    string (date)required
  • investment_account_id
    integer | null
  • earnings_account_id
    integer | null
  • control_basis
    string | null
  • note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    booleanrequired
  • voided_at
    string | null (date-time)
  • voided_by_id
    integer | null
  • void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}/void

Void an ownership version

Marks the version void with a reason (the row is kept; history is append-only). Refused when it would change a closed period. Voiding again returns it. Needs manage_coa over every entity. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • parent_entity_id
    integerrequired
  • child_entity_id
    integerrequired
  • ownership_pct
    stringrequired
  • voting_pct
    stringrequired
  • nci_pct
    string | null
  • method
    stringrequired
    One of: full, equity, cost, none.
  • effective_from
    string (date)required
  • investment_account_id
    integer | null
  • earnings_account_id
    integer | null
  • control_basis
    string | null
  • note
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)
  • voided
    booleanrequired
  • voided_at
    string | null (date-time)
  • voided_by_id
    integer | null
  • void_reason
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/settings

Consolidation settings

The intercompany matching tolerance. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • ic_tolerance
    stringrequired
    Decimal string with two places
  • updated_at
    string | null (date-time)
  • updated_by_id
    integer | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

PATCH /rest/v1.0/companies/{company_id}/accounting/consolidation/settings

Update consolidation settings

Sets the intercompany matching tolerance (manage_coa over every entity). Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • settings
    objectrequired
  • settings.ic_tolerance
    stringrequired

Response · 200 · object

  • ic_tolerance
    stringrequired
    Decimal string with two places
  • updated_at
    string | null (date-time)
  • updated_by_id
    integer | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company, read-only token, or the preparer approving their own work
  • 404Not found in this company
  • 409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

GET /rest/v1.0/companies/{company_id}/accounting/consolidation/structure

Consolidation group on a date

Members (roots and fully consolidated entities) with parent, group share and NCI percent, and the entities outside the group (equity, cost, not held, or held through one of those). Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • as_of
    string (date)required
  • members
    object[]required
  • members[].entity_id
    integer
  • members[].code
    string | null
  • members[].name
    string | null
  • members[].parent_entity_id
    integer | null
  • members[].ownership_id
    integer | null
  • members[].ownership_pct
    string | null
  • members[].group_share_pct
    string
  • members[].nci_pct
    string
  • members[].method
    string
    One of: root, full.
  • outside
    object[]required
  • outside[].entity_id
    integer
  • outside[].code
    string | null
  • outside[].name
    string | null
  • outside[].reason
    string
    One of: equity, cost, none, under_excluded.
  • outside[].parent_entity_id
    integer | null
  • outside[].ownership_id
    integer | null
  • outside[].ownership_pct
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company
  • 404Not found in this company
  • 422Validation failed, a closed period, a missing account mapping, or nothing to do

Example request

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

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years

Generate a fiscal year

Creates the fiscal year (labelled by the calendar year it ends in) and its twelve monthly periods from the settings' start month. Returns the existing year unchanged if it already exists. A year before a closed period is refused unless closed is true. Needs close_period with unrestricted entity access. 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

  • fiscal_year
    objectrequired
  • fiscal_year.year
    integerrequired
  • fiscal_year.closed
    boolean
    Create every period and module closed. Required when the year comes before a closed period (422 otherwise).

Response · 201 · object

  • id
    integerrequired
  • year
    integerrequired
  • start_date
    string (date)required
  • end_date
    string (date)required
  • status
    anyrequired
    One of: open, soft_closed, closed.
  • periods
    object[]required
  • periods[].id
    integerrequired
  • periods[].fiscal_year_id
    integerrequired
  • periods[].fiscal_year
    integer | nullrequired
  • periods[].number
    integerrequired
  • periods[].name
    stringrequired
  • periods[].start_date
    string (date)required
  • periods[].end_date
    string (date)required
  • periods[].status
    anyrequired
    One of: open, soft_closed, closed.
  • periods[].module_status
    objectrequired
  • periods[].closed_at
    string | null (date-time)required
  • periods[].closed_by_id
    integer | nullrequired
  • periods[].is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • periods[].entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • periods[].rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.

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
  • 409Conflict, including an Idempotency-Key reused for a different request or still in progress
  • 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/fiscal_years" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "fiscal_year": {
    "year": 1
  }
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/adjusting_period

Add the adjusting period (period 13)

Adds period 13 to the fiscal year: one day on the year's last day, open, for audit adjustments that land after later months closed. Entries reach it only with adjusting: true (GJ or CL), it is exempt from later closed periods, and it closes and reopens on its own. Idempotent: 200 with the existing period. Needs close_period with 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 · 200 · object

  • period
    objectrequired
  • period.id
    integerrequired
  • period.fiscal_year_id
    integerrequired
  • period.fiscal_year
    integer | nullrequired
  • period.number
    integerrequired
  • period.name
    stringrequired
  • period.start_date
    string (date)required
  • period.end_date
    string (date)required
  • period.status
    anyrequired
    One of: open, soft_closed, closed.
  • period.module_status
    objectrequired
  • period.closed_at
    string | null (date-time)required
  • period.closed_by_id
    integer | nullrequired
  • period.is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • period.entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • period.rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.

Errors

  • 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/fiscal_years/1/adjusting_period" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_close

Post the year-end close

Posts one closing entry (journal CL, is_closing_entry: true, source year_end_close with the fiscal year id) dated the last day of the year. It moves the year’s income and expense balances of every entity into retained earnings, balanced per entity, and marks the fiscal year closed. Earlier fiscal years with income or expense balances must be closed first. Once closed, the year refuses every posting except closing entries until the close is reversed (POST .../year_end_close/reverse). Each entity closes into its own retained_earnings_account_id when set (else the company's retained earnings), and equity accounts with subtype distributions (S-corp distributions, partner draws) close into it too. When the year has period 13, the closing entry posts there, period 13 may stay open, and each later adjusting entry re-closes the year with a new revision. Every period of the year must be soft-closed (or closed) for GL first, and the last period must still accept GL postings. Idempotent: a rerun returns the existing entry with 200. Reports already present prior-year earnings in retained earnings, so the entry changes no statement total. Needs close_period with 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 · 200 · object

  • fiscal_year
    object
  • fiscal_year.id
    integer
  • fiscal_year.year
    integer
  • fiscal_year.start_date
    string (date)
  • fiscal_year.end_date
    string (date)
  • fiscal_year.status
    any
    One of: open, soft_closed, closed.
  • journal_entry
    object
  • journal_entry.id
    integerrequired
  • journal_entry.number
    string | nullrequired
    JE-YYYY-#####, assigned on posting
  • journal_entry.status
    anyrequired
    One of: draft, pending_approval, posted, reversed.
  • journal_entry.journal
    anyrequired
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • journal_entry.entity_id
    integerrequired
  • journal_entry.period_id
    integerrequired
  • journal_entry.posting_date
    string (date)required
  • journal_entry.document_date
    string | null (date)required
  • journal_entry.memo
    string | nullrequired
  • journal_entry.source_type
    stringrequired
  • journal_entry.source_id
    integer | nullrequired
  • journal_entry.source_revision
    integerrequired
  • journal_entry.total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.currency
    stringrequired
  • journal_entry.prepared_by_id
    integerrequired
  • journal_entry.approved_by_id
    integer | nullrequired
  • journal_entry.posted_by_id
    integer | nullrequired
  • journal_entry.posted_at
    string | null (date-time)required
  • journal_entry.reverses_id
    integer | nullrequired
  • journal_entry.reversed_by_id
    integer | nullrequired
  • journal_entry.auto_reverse_date
    string | null (date)required
  • journal_entry.created_at
    string (date-time)required
  • journal_entry.updated_at
    string (date-time)required
  • journal_entry.exchange_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • journal_entry.is_closing_entry
    booleanrequired
  • journal_entry.batch_id
    integer | nullrequired
  • journal_entry.recurring_id
    integer | nullrequired
  • journal_entry.submitted_at
    string | null (date-time)required
  • journal_entry.approved_at
    string | null (date-time)required
  • journal_entry.total_debit
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.total_credit
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.balanced
    booleanrequired
  • journal_entry.lines
    object[]required
  • journal_entry.is_noncash
    booleanrequired

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/fiscal_years/1/year_end_close" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_close/reverse

Reverse the year-end close

Reverses the fiscal year's standing year-end closing entry on its own date (the year's last day) and reopens the fiscal year (status open), so the year can take postings and be closed again. The last period must still accept GL postings. Needs post_journal and close_period with unrestricted entity access; at or above the approval threshold the reverser must hold approve_journal and must not have prepared the close. 404 when the year has no posted closing entry. Audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • reversal
    object
  • reversal.reason
    string | null

Response · 201 · object

  • id
    integerrequired
  • number
    string | nullrequired
    JE-YYYY-#####, assigned on posting
  • status
    anyrequired
    One of: draft, pending_approval, posted, reversed.
  • journal
    anyrequired
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • posting_date
    string (date)required
  • document_date
    string | null (date)required
  • memo
    string | nullrequired
  • source_type
    stringrequired
  • source_id
    integer | nullrequired
  • source_revision
    integerrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • currency
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • posted_by_id
    integer | nullrequired
  • posted_at
    string | null (date-time)required
  • reverses_id
    integer | nullrequired
  • reversed_by_id
    integer | nullrequired
  • auto_reverse_date
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • exchange_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • is_closing_entry
    booleanrequired
  • batch_id
    integer | nullrequired
  • recurring_id
    integer | nullrequired
  • submitted_at
    string | null (date-time)required
  • approved_at
    string | null (date-time)required
  • total_debit
    stringrequired
    Decimal amount as a string, 2 dp
  • total_credit
    stringrequired
    Decimal amount as a string, 2 dp
  • balanced
    booleanrequired
  • lines
    object[]required
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].account_number
    string | nullrequired
  • lines[].account_name
    string | nullrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].entity_id
    integerrequired
  • lines[].counterparty_entity_id
    integer | nullrequired
    The other entity of an intercompany due-to/due-from line (set by the intercompany pre-pass, or by hand). Drives the pairwise intercompany check and eliminations.
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].vendor_id
    integer | nullrequired
  • lines[].customer_id
    integer | nullrequired
  • lines[].employee_id
    integer | nullrequired
  • lines[].equipment_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].commitment_id
    integer | nullrequired
  • lines[].contract_id
    integer | nullrequired
  • lines[].tax_code_id
    integer | nullrequired
  • lines[].quantity
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • lines[].unit
    string | nullrequired
  • lines[].billable
    booleanrequired
  • lines[].reconcile_state
    anyrequired
    One of: n, c, y, v.
  • lines[].source_type
    string | nullrequired
  • lines[].source_id
    integer | nullrequired
  • is_noncash
    booleanrequired

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/fiscal_years/1/year_end_close/reverse" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reversal": {}
}'

Accounting / Fiscal Periods

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

List fiscal periods

Periods in date order with the overall status and the close status of each module (AP, AR, payroll, job cost, cash management, GL). Filter with filters[fiscal_year] and filters[status]. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • filters[fiscal_year]
    integerquery
    Fiscal year label
  • filters[status]
    stringquery
    open, soft_closed or closed (comma-separated)

Response · 200 · object[]

  • id
    integerrequired
  • fiscal_year_id
    integerrequired
  • fiscal_year
    integer | nullrequired
  • number
    integerrequired
  • name
    stringrequired
  • start_date
    string (date)required
  • end_date
    string (date)required
  • status
    anyrequired
    One of: open, soft_closed, closed.
  • module_status
    objectrequired
  • module_status.ap
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.ar
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.payroll
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.jc
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.cm
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.gl
    anyrequired
    One of: open, soft_closed, closed.
  • closed_at
    string | null (date-time)required
  • closed_by_id
    integer | nullrequired
  • is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • entities[].entity_id
    integerrequired
  • entities[].status
    anyrequired
    One of: open, soft_closed, closed.
  • entities[].module_status
    objectrequired
  • entities[].closed_at
    string | null (date-time)required
  • entities[].closed_by_id
    integer | nullrequired
  • rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.
  • rollup.closed_entities
    integerrequired
  • rollup.total_entities
    integerrequired

Errors

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

Example request

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

Accounting / Fiscal Periods

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

Show a fiscal period

One period with its per-module close status. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • fiscal_year_id
    integerrequired
  • fiscal_year
    integer | nullrequired
  • number
    integerrequired
  • name
    stringrequired
  • start_date
    string (date)required
  • end_date
    string (date)required
  • status
    anyrequired
    One of: open, soft_closed, closed.
  • module_status
    objectrequired
  • module_status.ap
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.ar
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.payroll
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.jc
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.cm
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.gl
    anyrequired
    One of: open, soft_closed, closed.
  • closed_at
    string | null (date-time)required
  • closed_by_id
    integer | nullrequired
  • is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • entities[].entity_id
    integerrequired
  • entities[].status
    anyrequired
    One of: open, soft_closed, closed.
  • entities[].module_status
    objectrequired
  • entities[].closed_at
    string | null (date-time)required
  • entities[].closed_by_id
    integer | nullrequired
  • rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.
  • rollup.closed_entities
    integerrequired
  • rollup.total_entities
    integerrequired

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/periods/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/close

Close or soft-close a period

Closes one module (ap, ar, payroll, jc, cm, gl) or the whole period (all, the default). A closed period refuses postings, enforced again by a database trigger; a soft-closed one accepts postings only from users who can close periods. Needs close_period. With entity_id (per-entity close enabled), only that entity's lines are refused; an entity's readiness, checklist and evidence cover that entity only, and the elimination entity closes last (every entity closed, eliminations current). Without per-entity close enabled, entity_id answers 422 entity_close_disabled. Audited and emits accounting.period.closed or accounting.period.soft_closed. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • close
    objectrequired
  • close.module
    any
    One of: all, ap, ar, payroll, jc, cm, gl.
  • close.status
    any
    One of: soft_closed, closed.
  • close.entity_id
    integer
    Per-entity close (when enabled): act on this entity only. The company period status is the roll-up of its active entities (closed once every entity is closed). An entity-restricted grant may act on its own entities; the elimination entity needs unrestricted access. Omit for all entities.

Response · 200 · object

  • id
    integerrequired
  • fiscal_year_id
    integerrequired
  • fiscal_year
    integer | nullrequired
  • number
    integerrequired
  • name
    stringrequired
  • start_date
    string (date)required
  • end_date
    string (date)required
  • status
    anyrequired
    One of: open, soft_closed, closed.
  • module_status
    objectrequired
  • module_status.ap
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.ar
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.payroll
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.jc
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.cm
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.gl
    anyrequired
    One of: open, soft_closed, closed.
  • closed_at
    string | null (date-time)required
  • closed_by_id
    integer | nullrequired
  • is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • entities[].entity_id
    integerrequired
  • entities[].status
    anyrequired
    One of: open, soft_closed, closed.
  • entities[].module_status
    objectrequired
  • entities[].closed_at
    string | null (date-time)required
  • entities[].closed_by_id
    integer | nullrequired
  • rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.
  • rollup.closed_entities
    integerrequired
  • rollup.total_entities
    integerrequired

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, read-only workspace, an entity outside the grant's entities, or (without entity_id) an entity-restricted grant
  • 404Not found in this company
  • 422Validation failed (field errors) or the ledger refused the change (message list)
  • 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 POST "https://app.os.construction/rest/v1.0/companies/1/accounting/periods/1/close" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "close": {}
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/eliminate_intercompany

Eliminate intercompany at a period end

Posts one CL entry in the elimination entity dated the period end, auto-reversing the next day, that reverses every matched pair of intercompany due-to/due-from balances (by line counterparty), so the Consolidated column of the entity-pivot statements nets intercompany to zero. Refuses (422) when no elimination entity exists, when a pair of entities does not net to zero, or when intercompany lines with a balance name no counterparty. A rerun compares with what earlier runs still contribute at the period end, even after their auto-reversal: unchanged returns the latest entry (200, created false); otherwise a still-posted revision is reversed, an already auto-reversed one is offset on the period end, and a new revision posts (201). It also posts a second CL entry (pl_journal_entry) dated the period end, not auto-reversing, that reverses the period's intercompany revenue and cost: income-statement lines naming a counterparty entity (the intercompany pre-pass tags them only when an entry's P&L sits in exactly two entities and nets to zero), so the consolidated income statement leaves out EquipCo rent charged to OpCo jobs; only pairs that net to zero are eliminated, the others stay in consolidation and are listed in pl_mismatches without blocking the balance-sheet elimination, and a rerun reverses the standing revision when the period's activity changed. Needs close_period and unrestricted entity access (403 otherwise). Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • journal_entry
    object | nullrequired
  • journal_entry.id
    integerrequired
  • journal_entry.number
    string | nullrequired
    JE-YYYY-#####, assigned on posting
  • journal_entry.status
    anyrequired
    One of: draft, pending_approval, posted, reversed.
  • journal_entry.journal
    anyrequired
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • journal_entry.entity_id
    integerrequired
  • journal_entry.period_id
    integerrequired
  • journal_entry.posting_date
    string (date)required
  • journal_entry.document_date
    string | null (date)required
  • journal_entry.memo
    string | nullrequired
  • journal_entry.source_type
    stringrequired
  • journal_entry.source_id
    integer | nullrequired
  • journal_entry.source_revision
    integerrequired
  • journal_entry.total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.currency
    stringrequired
  • journal_entry.prepared_by_id
    integerrequired
  • journal_entry.approved_by_id
    integer | nullrequired
  • journal_entry.posted_by_id
    integer | nullrequired
  • journal_entry.posted_at
    string | null (date-time)required
  • journal_entry.reverses_id
    integer | nullrequired
  • journal_entry.reversed_by_id
    integer | nullrequired
  • journal_entry.auto_reverse_date
    string | null (date)required
  • journal_entry.created_at
    string (date-time)required
  • journal_entry.updated_at
    string (date-time)required
  • journal_entry.exchange_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • journal_entry.is_closing_entry
    booleanrequired
  • journal_entry.batch_id
    integer | nullrequired
  • journal_entry.recurring_id
    integer | nullrequired
  • journal_entry.submitted_at
    string | null (date-time)required
  • journal_entry.approved_at
    string | null (date-time)required
  • journal_entry.total_debit
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.total_credit
    stringrequired
    Decimal amount as a string, 2 dp
  • journal_entry.balanced
    booleanrequired
  • journal_entry.lines
    object[]required
  • journal_entry.is_noncash
    booleanrequired
  • created
    booleanrequired
  • pl_mismatches
    object[]required
    Entity pairs (by entity code) whose counterparty P&L lines do not net to zero for the period; left in consolidation, not eliminated.
  • pl_mismatches[].a
    stringrequired
  • pl_mismatches[].b
    stringrequired
  • pl_mismatches[].difference
    stringrequired
  • pl_journal_entry
    object | nullrequired
    The period's intercompany revenue and cost elimination (ASC 810-10-45-1): income-statement lines naming a counterparty entity, reversed out in the elimination entity at the period end. Not auto-reversing; null when the period has no intercompany P&L.
  • pl_journal_entry.id
    integerrequired
  • pl_journal_entry.number
    string | nullrequired
    JE-YYYY-#####, assigned on posting
  • pl_journal_entry.status
    anyrequired
    One of: draft, pending_approval, posted, reversed.
  • pl_journal_entry.journal
    anyrequired
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • pl_journal_entry.entity_id
    integerrequired
  • pl_journal_entry.period_id
    integerrequired
  • pl_journal_entry.posting_date
    string (date)required
  • pl_journal_entry.document_date
    string | null (date)required
  • pl_journal_entry.memo
    string | nullrequired
  • pl_journal_entry.source_type
    stringrequired
  • pl_journal_entry.source_id
    integer | nullrequired
  • pl_journal_entry.source_revision
    integerrequired
  • pl_journal_entry.total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • pl_journal_entry.currency
    stringrequired
  • pl_journal_entry.prepared_by_id
    integerrequired
  • pl_journal_entry.approved_by_id
    integer | nullrequired
  • pl_journal_entry.posted_by_id
    integer | nullrequired
  • pl_journal_entry.posted_at
    string | null (date-time)required
  • pl_journal_entry.reverses_id
    integer | nullrequired
  • pl_journal_entry.reversed_by_id
    integer | nullrequired
  • pl_journal_entry.auto_reverse_date
    string | null (date)required
  • pl_journal_entry.created_at
    string (date-time)required
  • pl_journal_entry.updated_at
    string (date-time)required
  • pl_journal_entry.exchange_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • pl_journal_entry.is_closing_entry
    booleanrequired
  • pl_journal_entry.batch_id
    integer | nullrequired
  • pl_journal_entry.recurring_id
    integer | nullrequired
  • pl_journal_entry.submitted_at
    string | null (date-time)required
  • pl_journal_entry.approved_at
    string | null (date-time)required
  • pl_journal_entry.total_debit
    stringrequired
    Decimal amount as a string, 2 dp
  • pl_journal_entry.total_credit
    stringrequired
    Decimal amount as a string, 2 dp
  • pl_journal_entry.balanced
    booleanrequired
  • pl_journal_entry.lines
    object[]required
  • pl_journal_entry.is_noncash
    booleanrequired

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/periods/1/eliminate_intercompany" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/periods/{id}/reopen

Reopen a period

Reopens one module or the whole period. A reason is required and recorded in the audit trail. Refused with 422 while a later period is closed, unless cascade is true: then every later closed period is reopened too, its close reviews are invalidated, and each reopen is audited. Reopening a hard-closed scope (a closed period or module, or a cascade over closed periods) needs two close_period users: the first call records a request and answers 202 with the unchanged period and pending_reopen; a different user's call with the same module and cascade within 7 days applies the reopen (200). Soft-closed scopes reopen on one call. With entity_id, the reopen, cascade and two-person request apply to that entity's rows; reopening a real entity also reopens the elimination entity where it is closed in that period or later. Needs close_period. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • reopen
    objectrequired
  • reopen.module
    any
    One of: all, ap, ar, payroll, jc, cm, gl.
  • reopen.reason
    stringrequired
  • reopen.cascade
    boolean
  • reopen.entity_id
    integer
    Per-entity close (when enabled): act on this entity only. The company period status is the roll-up of its active entities (closed once every entity is closed). An entity-restricted grant may act on its own entities; the elimination entity needs unrestricted access. Omit for all entities.

Response · 200 · object

  • id
    integerrequired
  • fiscal_year_id
    integerrequired
  • fiscal_year
    integer | nullrequired
  • number
    integerrequired
  • name
    stringrequired
  • start_date
    string (date)required
  • end_date
    string (date)required
  • status
    anyrequired
    One of: open, soft_closed, closed.
  • module_status
    objectrequired
  • module_status.ap
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.ar
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.payroll
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.jc
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.cm
    anyrequired
    One of: open, soft_closed, closed.
  • module_status.gl
    anyrequired
    One of: open, soft_closed, closed.
  • closed_at
    string | null (date-time)required
  • closed_by_id
    integer | nullrequired
  • is_adjusting
    booleanrequired
    Period 13 (adjusting): one day on the fiscal year's last day, numbered 13. Takes only GJ/CL entries posted with adjusting: true, is exempt from later closed periods (no cascade reopen) and never returned for a date lookup.
  • entities
    object[]
    Present when per-entity close is enabled: each entity's period status, limited to the caller's entities. `status` and `module_status` above are the company roll-up.
  • entities[].entity_id
    integerrequired
  • entities[].status
    anyrequired
    One of: open, soft_closed, closed.
  • entities[].module_status
    objectrequired
  • entities[].closed_at
    string | null (date-time)required
  • entities[].closed_by_id
    integer | nullrequired
  • rollup
    object
    Present with `entities`: active entities closed out of the active entities listed.
  • rollup.closed_entities
    integerrequired
  • rollup.total_entities
    integerrequired

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, read-only workspace, an entity outside the grant's entities, or (without entity_id) an entity-restricted grant
  • 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/periods/1/reopen" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reopen": {
    "reason": "string"
  }
}'

Accounting / Fiscal Periods

POST /rest/v1.0/companies/{company_id}/accounting/periods/rebuild_balances

Rebuild period balance snapshots

Recomputes acct_period_balances (what TB, balance sheet and income statement read for whole periods) from the posted journal lines, under every period row lock, and audits the number of corrected rows. Use when the integrity check period_balances_parity fails. Needs close_period and unrestricted entity access (403 otherwise). Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired

Response · 200 · object

  • corrected
    integerrequired
    Snapshot rows that differed from the lines
  • rows
    integerrequired
    Snapshot rows written

Errors

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

Example request

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

Ask the OS

Reading this page

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

Suggested

    AI · may be imperfect · sample data where shown

    Open file