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.
- GET
/rest/v1.0/companies/{company_id}/accounting/close/alert_testsAlert delivery tests - POST
/rest/v1.0/companies/{company_id}/accounting/close/alert_testsSend a test alert - GET
/rest/v1.0/companies/{company_id}/accounting/close/cockpitClose cockpit - POST
/rest/v1.0/companies/{company_id}/accounting/close/cockpit/generateGenerate close tasks - POST
/rest/v1.0/companies/{company_id}/accounting/close/cockpit/syncRefresh close evidence - GET
/rest/v1.0/companies/{company_id}/accounting/close/fluxFlux analysis of a period - POST
/rest/v1.0/companies/{company_id}/accounting/close/flux/explanationsExplain a flux row - GET
/rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}Show a flux explanation - POST
/rest/v1.0/companies/{company_id}/accounting/close/flux/explanations/{id}/reviewReview a flux explanation - GET
/rest/v1.0/companies/{company_id}/accounting/close/flux/settingsFlux settings - PUT
/rest/v1.0/companies/{company_id}/accounting/close/flux/settingsSave flux settings - GET
/rest/v1.0/companies/{company_id}/accounting/close/flux/thresholdsList flux thresholds - POST
/rest/v1.0/companies/{company_id}/accounting/close/flux/thresholdsCreate a flux threshold - PATCH
/rest/v1.0/companies/{company_id}/accounting/close/flux/thresholds/{id}Update a flux threshold - GET
/rest/v1.0/companies/{company_id}/accounting/close/rec_rulesList reconciliation rules - POST
/rest/v1.0/companies/{company_id}/accounting/close/rec_rulesCreate a reconciliation rule - PATCH
/rest/v1.0/companies/{company_id}/accounting/close/rec_rules/{id}Update a reconciliation rule - GET
/rest/v1.0/companies/{company_id}/accounting/close/reconciliationsList account reconciliations - GET
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}Show an account reconciliation - GET
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsList attachments on an account reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsAttach a workpaper to an account reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/itemsAdd a reconciling item or schedule line - PATCH
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/items/{item_id}Update or clear a reconciliation item - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/preparePrepare an account reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/reviewReview an account reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/unsignUnsign an account reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/generateGenerate account reconciliations - GET
/rest/v1.0/companies/{company_id}/accounting/close/settingsClose cockpit settings - PUT
/rest/v1.0/companies/{company_id}/accounting/close/settingsSave close cockpit settings - GET
/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}Show a close task - POST
/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/preparePrepare a close task - POST
/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/reviewReview a close task - POST
/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/startStart a close task - POST
/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/unsignUnsign a close task - GET
/rest/v1.0/companies/{company_id}/accounting/close/templatesList close templates - POST
/rest/v1.0/companies/{company_id}/accounting/close/templatesCreate a close template - GET
/rest/v1.0/companies/{company_id}/accounting/close/templates/{id}Show a close template - PUT
/rest/v1.0/companies/{company_id}/accounting/close/templates/{id}Replace a close template - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runsList equity-method runs - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runsPrepare an equity-method run - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}Get an equity-method run - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/equity_method/runs/{id}/decisionApprove or cancel an equity-method run - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputesList intercompany disputes - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputesRaise an intercompany dispute - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}Get an intercompany dispute - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/adjustmentPropose the adjusting entry - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/assignAssign an intercompany dispute - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/commentsComment on an intercompany dispute - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/decisionApprove or reject the adjusting entry - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/disputes/{id}/resolveResolve or withdraw an intercompany dispute - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlementsList intercompany settlement runs - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlementsPrepare an intercompany settlement - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}Get an intercompany settlement run - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/settlements/{id}/decisionApprove or cancel an intercompany settlement - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfersList intercompany asset transfers - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfersRegister an intercompany asset transfer - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}Get an intercompany asset transfer - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/eventsRecord a sale on or a disposal - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ic/transfers/{id}/voidVoid an intercompany asset transfer - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ownershipList ownership versions - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ownershipRecord an ownership version - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}Get an ownership version - POST
/rest/v1.0/companies/{company_id}/accounting/consolidation/ownership/{id}/voidVoid an ownership version - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/settingsConsolidation settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/consolidation/settingsUpdate consolidation settings - GET
/rest/v1.0/companies/{company_id}/accounting/consolidation/structureConsolidation group on a date - POST
/rest/v1.0/companies/{company_id}/accounting/fiscal_yearsGenerate a fiscal year - POST
/rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/adjusting_periodAdd the adjusting period (period 13) - POST
/rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_closePost the year-end close - POST
/rest/v1.0/companies/{company_id}/accounting/fiscal_years/{id}/year_end_close/reverseReverse the year-end close - GET
/rest/v1.0/companies/{company_id}/accounting/periodsList fiscal periods - GET
/rest/v1.0/companies/{company_id}/accounting/periods/{id}Show a fiscal period - POST
/rest/v1.0/companies/{company_id}/accounting/periods/{id}/closeClose or soft-close a period - POST
/rest/v1.0/companies/{company_id}/accounting/periods/{id}/eliminate_intercompanyEliminate intercompany at a period end - POST
/rest/v1.0/companies/{company_id}/accounting/periods/{id}/reopenReopen a period - 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_testsAlert 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- statusstringrequiredOne of: queued, delivered, partial, failed.
- requested_by_idintegerrequired
- job_idinteger | nullrequired
- created_atstring (date-time)required
- finished_atstring | null (date-time)required
- attemptsobject[]required
- attempts[].idintegerrequired
- attempts[].channelstringrequiredOne of: email, webhook.
- attempts[].transportstringrequiredemail: the configured transport (outbox records locally, webhook or resend hand to a provider); webhook: durable_delivery
- attempts[].recipient_user_idinteger | nullrequired
- attempts[].subscription_idinteger | nullrequired
- attempts[].email_message_idinteger | nullrequired
- attempts[].webhook_delivery_idstring | null (uuid)required
- attempts[].outcomestringrequiredrecorded: 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_codestring | nullrequiredA sanitized code, never an address or provider text
- attempts[].created_atstring (date-time)required
- attempts[].delivery_outcomestring | nullOne of: pending, succeeded, cancelled, null.
- attempts[].delivery_http_statusinteger | null
- attempts[].delivery_error_codestring | null
Errors
401Missing or invalid bearer token403No accounting access, missing close_period (or a project-scoped grant), wrong company, or read-only workspace
Example request
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_testsSend 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- request_keystringrequired
Response · 202 · object
- idintegerrequired
- statusstringrequiredOne of: queued, delivered, partial, failed.
- requested_by_idintegerrequired
- job_idinteger | nullrequired
- created_atstring (date-time)required
- finished_atstring | null (date-time)required
- attemptsobject[]required
- attempts[].idintegerrequired
- attempts[].channelstringrequiredOne of: email, webhook.
- attempts[].transportstringrequiredemail: the configured transport (outbox records locally, webhook or resend hand to a provider); webhook: durable_delivery
- attempts[].recipient_user_idinteger | nullrequired
- attempts[].subscription_idinteger | nullrequired
- attempts[].email_message_idinteger | nullrequired
- attempts[].webhook_delivery_idstring | null (uuid)required
- attempts[].outcomestringrequiredrecorded: 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_codestring | nullrequiredA sanitized code, never an address or provider text
- attempts[].created_atstring (date-time)required
- attempts[].delivery_outcomestring | nullOne of: pending, succeeded, cancelled, null.
- attempts[].delivery_http_statusinteger | null
- attempts[].delivery_error_codestring | null
Errors
401Missing or invalid bearer token403No accounting access, missing close_period (or a project-scoped grant), wrong company, accounting:read token, or read-only workspace422Invalid request_key
Example request
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/cockpitClose 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- period_idintegerqueryrequiredThe period
- entity_idintegerqueryEntity scope (omit for all entities)
Response · 200 · object
- periodobjectrequired
- period.idintegerrequired
- period.namestringrequired
- period.start_datestring | null (date)required
- period.end_datestring | null (date)required
- period.statusstringrequired
- entity_idinteger | nullrequired
- todaystring (date)required
- settingsobjectrequired
- settings.require_tasksbooleanrequired
- settings.require_recsbooleanrequired
- settings.require_fluxbooleanGL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
- settings.default_template_idinteger | nullrequired
- progressobjectrequired
- progress.totalintegerrequired
- progress.reviewedintegerrequired
- progress.percentintegerrequired
- progress.overdueintegerrequired
- progress.required_openintegerrequired
- progress.by_statusobjectrequired
- progress.by_categoryobject[]required
- critical_pathinteger[]requiredTask ids, first to last: the longest chain of unfinished dependent tasks.
- blockingobject[]required
- blocking[].blocker_idinteger | nullrequired
- blocking[].blocker_namestring | nullrequired
- blocking[].blocked_idinteger | nullrequired
- blocking[].blocked_namestring | nullrequired
- blocking[].tasksobject[]required
- reconciliationsobjectrequired
- reconciliations.totalintegerrequired
- reconciliations.by_statusobjectrequired
- reconciliations.staleintegerrequired
- reconciliations.auto_reconciledintegerrequired
- reconciliations.missingintegerrequired
- reconciliations.open_itemsintegerrequired
- reconciliations.items_over_90integerrequired
- close_blockersobject[]required
- close_blockers[].codestringrequired
- close_blockers[].messagestringrequired
- close_blockers[].hrefstring
- tasksobject[]required
- tasks[].idintegerrequired
- tasks[].period_idintegerrequired
- tasks[].entity_idinteger | nullrequired
- tasks[].keystringrequired
- tasks[].titlestringrequired
- tasks[].categorystringrequired
- tasks[].close_modulestring | nullrequired
- tasks[].owner_idinteger | nullrequired
- tasks[].reviewer_idinteger | nullrequired
- tasks[].due_datestring | null (date)required
- tasks[].depends_onstring[]required
- tasks[].evidencestring | nullrequired
- tasks[].requiredbooleanrequired
- tasks[].instructionsstring | nullrequired
- tasks[].statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- tasks[].prepared_by_idinteger | nullrequired
- tasks[].prepared_atstring | null (date-time)required
- tasks[].prep_notestring | nullrequired
- tasks[].reviewed_by_idinteger | nullrequired
- tasks[].reviewed_atstring | null (date-time)required
- tasks[].review_notestring | nullrequired
- tasks[].auto_completedbooleanrequired
- tasks[].evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- tasks[].evidence_messagestring | nullrequired
- tasks[].evidence_checked_atstring | null (date-time)required
- tasks[].stale_atstring | null (date-time)required
- tasks[].stale_reasonstring | nullrequired
- tasks[].overduebooleanrequired
- tasks[].open_dependenciesstring[]required
- tasks[].criticalbooleanrequired
Errors
400period_id missing401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Period or entity not found
Example request
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/generateGenerate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- generateobjectrequired
- generate.period_idintegerrequired
- generate.entity_idinteger | null
- generate.template_idinteger | null
Response · 200 · object
- createdintegerrequired
- keptintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Period, entity or template not found422No template given and no default set
Example request
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/syncRefresh 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- syncobjectrequired
- sync.period_idintegerrequired
- sync.entity_idinteger | null
Response · 200 · object
- completedintegerrequired
- staleintegerrequired
- reconciledintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Period or entity not found
Example request
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/fluxFlux 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- period_idintegerqueryrequired
- entity_idintegerquery
Response · 200 · object
- periodobject | nullrequired
- period.idintegerrequired
- period.namestringrequired
- period.start_datestring (date)required
- period.end_datestring (date)required
- prior_periodobject | nullrequired
- prior_period.idintegerrequired
- prior_period.namestringrequired
- prior_period.start_datestring (date)required
- prior_period.end_datestring (date)required
- prior_year_periodobject | nullrequired
- prior_year_period.idintegerrequired
- prior_year_period.namestringrequired
- prior_year_period.start_datestring (date)required
- prior_year_period.end_datestring (date)required
- budgetobject | nullrequired
- budget.idinteger
- budget.namestring
- budget.fiscal_yearinteger
- budget.versioninteger
- settingsobjectrequired
- settings.default_amountstringrequired
- settings.default_percentstringrequired
- settings.threshold_modeanyrequiredOne of: both, either.
- settings.materiality_floorstringrequired
- settings.compare_prior_periodbooleanrequired
- settings.compare_prior_yearbooleanrequired
- settings.compare_budgetbooleanrequired
- settings.revisionintegerrequired
- settings.updated_atstring | null (date-time)required
- entity_idsinteger[]required
- summaryobjectrequired
- summary.rowsintegerrequired
- summary.requiringintegerrequired
- summary.unexplainedintegerrequired
- summary.explainedintegerrequired
- summary.reviewedintegerrequired
- summary.staleintegerrequired
- rowsobject[]required
- rows[].keystringrequired
- rows[].entity_idintegerrequired
- rows[].kindanyrequiredOne of: income_statement, balance_sheet.
- rows[].accountobjectrequired
- rows[].dimensionobject | nullrequired
- rows[].dimension_valueobject | nullrequired
- rows[].currentstringrequired
- rows[].prior_periodstringrequired
- rows[].prior_yearstringrequired
- rows[].budgetstring | nullrequired
- rows[].comparisonsobject[]required
- rows[].thresholdobjectrequired
- rows[].requires_explanationbooleanrequired
- rows[].statusanyrequiredOne of: none, explained, reviewed, stale.
- rows[].stale_reasonstring | nullrequired
- rows[].explanationobject | nullrequired
Errors
400period_id missing401Missing or invalid bearer token403No accounting access, a project-scoped grant, outside the entity scope or wrong company404Period or entity not found422The adjusting period has no flux analysis
Example request
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/explanationsExplain 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- flux_explanationobjectrequired
- flux_explanation.period_idintegerrequired
- flux_explanation.entity_idintegerrequired
- flux_explanation.account_idintegerrequired
- flux_explanation.dimension_value_idinteger | null
- flux_explanation.explanationstringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- account_idintegerrequired
- dimension_value_idinteger | nullrequired
- explanationstringrequired
- revisionintegerrequired
- figuresobjectrequiredFigures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
- prepared_by_idintegerrequired
- prepared_atstring | null (date-time)required
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- balance_debitstring | null
- balance_creditstring | null
Errors
401Missing or invalid bearer token403Missing post_journal, outside the entity scope, project-scoped or read-only workspace404Period or entity not found422Invalid body, or (explanations) no flux figures for that row
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- account_idintegerrequired
- dimension_value_idinteger | nullrequired
- explanationstringrequired
- revisionintegerrequired
- figuresobjectrequiredFigures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
- prepared_by_idintegerrequired
- prepared_atstring | null (date-time)required
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- balance_debitstring | null
- balance_creditstring | null
- rowobject | nullrequired
- row.keystringrequired
- row.entity_idintegerrequired
- row.kindanyrequiredOne of: income_statement, balance_sheet.
- row.accountobjectrequired
- row.dimensionobject | nullrequired
- row.dimension_valueobject | nullrequired
- row.currentstringrequired
- row.prior_periodstringrequired
- row.prior_yearstringrequired
- row.budgetstring | nullrequired
- row.comparisonsobject[]required
- row.thresholdobjectrequired
- row.requires_explanationbooleanrequired
- row.statusanyrequiredOne of: none, explained, reviewed, stale.
- row.stale_reasonstring | nullrequired
- row.explanationobject | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, outside the entity scope or project-scoped404Not found
Example request
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}/reviewReview 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- account_idintegerrequired
- dimension_value_idinteger | nullrequired
- explanationstringrequired
- revisionintegerrequired
- figuresobjectrequiredFigures when last explained or reviewed: current, prior_period, prior_year, budget (null = no approved budget).
- prepared_by_idintegerrequired
- prepared_atstring | null (date-time)required
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- balance_debitstring | null
- balance_creditstring | null
Errors
401Missing or invalid bearer token403Missing close_period, the preparer, outside the entity scope or project-scoped404Not found409Figures moved since the explanation, already reviewed, or changed concurrently422Invalid body, or (explanations) no flux figures for that row
Example request
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/settingsFlux settings
Default thresholds, threshold mode, materiality floor and which comparisons apply. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- default_amountstringrequired
- default_percentstringrequired
- threshold_modeanyrequiredOne of: both, either.
- materiality_floorstringrequired
- compare_prior_periodbooleanrequired
- compare_prior_yearbooleanrequired
- compare_budgetbooleanrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant
Example request
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/settingsSave 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- flux_settingsobjectrequired
- flux_settings.default_amountstringrequired
- flux_settings.default_percentstringrequired
- flux_settings.threshold_modeanyrequiredOne of: both, either.
- flux_settings.materiality_floorstringrequired
- flux_settings.compare_prior_periodbooleanrequired
- flux_settings.compare_prior_yearbooleanrequired
- flux_settings.compare_budgetbooleanrequired
Response · 200 · object
- default_amountstringrequired
- default_percentstringrequired
- threshold_modeanyrequiredOne of: both, either.
- materiality_floorstringrequired
- compare_prior_periodbooleanrequired
- compare_prior_yearbooleanrequired
- compare_budgetbooleanrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403Missing close_period, not an owner or controller, entity-restricted, project-scoped or read-only workspace422Invalid body, or (explanations) no flux figures for that row
Example request
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/thresholdsList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- account_typestring | nullrequired
- account_idinteger | nullrequired
- amountstringrequired
- percentstringrequired
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant
Example request
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/thresholdsCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- flux_thresholdobjectrequired
- flux_threshold.account_typestring | null
- flux_threshold.account_idinteger | null
- flux_threshold.amountstringrequired
- flux_threshold.percentstringrequired
- flux_threshold.is_activeboolean
Response · 201 · object
- idintegerrequired
- account_typestring | nullrequired
- account_idinteger | nullrequired
- amountstringrequired
- percentstringrequired
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403Missing close_period, not an owner or controller, entity-restricted or project-scoped404Account not found409A threshold for the type or account exists422Invalid body, or (explanations) no flux figures for that row
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- flux_thresholdobjectrequired
- flux_threshold.amountstring
- flux_threshold.percentstring
- flux_threshold.is_activeboolean
Response · 200 · object
- idintegerrequired
- account_typestring | nullrequired
- account_idinteger | nullrequired
- amountstringrequired
- percentstringrequired
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403Missing close_period, not an owner or controller, entity-restricted or project-scoped404Not found422Invalid body, or (explanations) no flux figures for that row
Example request
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_rulesList reconciliation rules
Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- account_typesstring[]required
- account_idsinteger[]required
- entity_idsinteger[]required
- sourcestringrequiredOne of: auto, tie_out, manual.
- tie_out_keystring | nullrequired
- materiality_absstringrequired
- materiality_pctstringrequired
- risk_ratingstringrequiredOne of: low, medium, high.
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
Example request
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_rulesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- rec_ruleobjectrequired
- rec_rule.namestringrequired
- rec_rule.account_typesstring[]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_idsinteger[]
- rec_rule.entity_idsinteger[]
- rec_rule.sourcestringrequiredOne of: auto, tie_out, manual.
- rec_rule.tie_out_keystring | nullOne of: ap, ap_retainage, ar, ar_retainage, payroll, assets, cash_reconciliation, job_cost, wip, wip_revenue, prepaids, null.
- rec_rule.materiality_absstringrequired
- rec_rule.materiality_pctstringrequired
- rec_rule.risk_ratingstringrequiredOne of: low, medium, high.
- rec_rule.is_activeboolean
Response · 201 · object
- idintegerrequired
- namestringrequired
- account_typesstring[]required
- account_idsinteger[]required
- entity_idsinteger[]required
- sourcestringrequiredOne of: auto, tie_out, manual.
- tie_out_keystring | nullrequired
- materiality_absstringrequired
- materiality_pctstringrequired
- risk_ratingstringrequiredOne of: low, medium, high.
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace409Idempotency-Key reused422Invalid rule
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rec_ruleobjectrequired
- rec_rule.is_activeboolean
- rec_rule.materiality_absstring
- rec_rule.materiality_pctstring
- rec_rule.risk_ratingstringOne of: low, medium, high.
- rec_rule.namestring
Response · 200 · object
- idintegerrequired
- namestringrequired
- account_typesstring[]required
- account_idsinteger[]required
- entity_idsinteger[]required
- sourcestringrequiredOne of: auto, tie_out, manual.
- tie_out_keystring | nullrequired
- materiality_absstringrequired
- materiality_pctstringrequired
- risk_ratingstringrequiredOne of: low, medium, high.
- is_activebooleanrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company422Invalid change
Example request
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/reconciliationsList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- period_idintegerqueryrequiredThe period
- entity_idintegerqueryOne entity
- statusstringqueryOne of: not_started, in_progress, prepared, reviewed.
Response · 200 · object[]
- idintegerrequired
- period_idintegerrequired
- period_namestringrequired
- entity_idintegerrequired
- rule_idinteger | nullrequired
- accountobjectrequired
- account.idintegerrequired
- account.numberstringrequired
- account.namestringrequired
- account.typestringrequired
- account.normal_balancestringrequired
- sourcestringrequiredOne of: tie_out, manual.
- tie_out_keystring | nullrequired
- risk_ratingstringrequired
- frequencystringrequiredOne of: monthly, quarterly.
- review_levelintegerrequiredOne of: 1, 2.
- materiality_absstringrequired
- materiality_pctstringrequired
- materialbooleanrequired
- tolerancestringrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- auto_reconciledbooleanrequired
- stalebooleanrequired
- stale_reasonstring | nullrequired
- liveobjectrequired
- live.gl_balancestringrequired
- live.support_balancestring | nullrequired
- live.items_totalstringrequired
- live.schedule_totalstringrequired
- live.unexplainedstring | nullrequired
- live.within_tolerancebooleanrequired
- live.tie_outobject | nullrequired
- live.bank_reconciliationobject | nullrequired
- signedobjectrequired
- signed.gl_balancestring | nullrequired
- signed.support_balancestring | nullrequired
- signed.items_totalstring | nullrequired
- signed.unexplainedstring | nullrequired
- signed.balance_debitstring | nullrequired
- signed.balance_creditstring | nullrequired
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- second_reviewed_by_idinteger | nullrequired
- second_reviewed_atstring | null (date-time)required
- second_review_notestring | nullrequired
- agingobjectrequired
- aging.oldest_daysinteger | nullrequired
- aging.bucketsobjectrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindstringrequiredOne of: reconciling_item, schedule_line.
- items[].descriptionstringrequired
- items[].referencestring | nullrequired
- items[].amountstringrequired
- items[].item_datestring | null (date)required
- items[].age_daysintegerrequired
- items[].aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- items[].clearedbooleanrequired
- items[].cleared_atstring | null (date-time)required
- items[].carried_forwardbooleanrequired
- items[].carried_from_item_idinteger | nullrequired
- items[].created_by_idintegerrequired
- items[].created_atstring | null (date-time)required
Errors
400period_id missing or unknown status401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Period not found
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- period_namestringrequired
- entity_idintegerrequired
- rule_idinteger | nullrequired
- accountobjectrequired
- account.idintegerrequired
- account.numberstringrequired
- account.namestringrequired
- account.typestringrequired
- account.normal_balancestringrequired
- sourcestringrequiredOne of: tie_out, manual.
- tie_out_keystring | nullrequired
- risk_ratingstringrequired
- frequencystringrequiredOne of: monthly, quarterly.
- review_levelintegerrequiredOne of: 1, 2.
- materiality_absstringrequired
- materiality_pctstringrequired
- materialbooleanrequired
- tolerancestringrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- auto_reconciledbooleanrequired
- stalebooleanrequired
- stale_reasonstring | nullrequired
- liveobjectrequired
- live.gl_balancestringrequired
- live.support_balancestring | nullrequired
- live.items_totalstringrequired
- live.schedule_totalstringrequired
- live.unexplainedstring | nullrequired
- live.within_tolerancebooleanrequired
- live.tie_outobject | nullrequired
- live.bank_reconciliationobject | nullrequired
- signedobjectrequired
- signed.gl_balancestring | nullrequired
- signed.support_balancestring | nullrequired
- signed.items_totalstring | nullrequired
- signed.unexplainedstring | nullrequired
- signed.balance_debitstring | nullrequired
- signed.balance_creditstring | nullrequired
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- second_reviewed_by_idinteger | nullrequired
- second_reviewed_atstring | null (date-time)required
- second_review_notestring | nullrequired
- agingobjectrequired
- aging.oldest_daysinteger | nullrequired
- aging.bucketsobjectrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindstringrequiredOne of: reconciling_item, schedule_line.
- items[].descriptionstringrequired
- items[].referencestring | nullrequired
- items[].amountstringrequired
- items[].item_datestring | null (date)required
- items[].age_daysintegerrequired
- items[].aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- items[].clearedbooleanrequired
- items[].cleared_atstring | null (date-time)required
- items[].carried_forwardbooleanrequired
- items[].carried_from_item_idinteger | nullrequired
- items[].created_by_idintegerrequired
- items[].created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/close/reconciliations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Fiscal Periods
GET/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne 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_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/close/reconciliations/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Fiscal Periods
POST/rest/v1.0/companies/{company_id}/accounting/close/reconciliations/{id}/attachmentsAttach 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne 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_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
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}/itemsAdd 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- itemobjectrequired
- item.kindstringrequiredOne of: reconciling_item, schedule_line.
- item.descriptionstringrequired
- item.amountstringrequired
- item.item_datestring (date)required
- item.referencestring | null
Response · 201 · object
- idintegerrequired
- kindstringrequiredOne of: reconciling_item, schedule_line.
- descriptionstringrequired
- referencestring | nullrequired
- amountstringrequired
- item_datestring | null (date)required
- age_daysintegerrequired
- aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- clearedbooleanrequired
- cleared_atstring | null (date-time)required
- carried_forwardbooleanrequired
- carried_from_item_idinteger | nullrequired
- created_by_idintegerrequired
- created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409Signed reconciliation, or Idempotency-Key reused422Invalid item, or a schedule line on a tie-out reconciliation
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- item_idintegerpathrequired
Request body
- itemobjectrequired
- item.descriptionstring
- item.amountstring
- item.referencestring | null
- item.clearedboolean
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: reconciling_item, schedule_line.
- descriptionstringrequired
- referencestring | nullrequired
- amountstringrequired
- item_datestring | null (date)required
- age_daysintegerrequired
- aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- clearedbooleanrequired
- cleared_atstring | null (date-time)required
- carried_forwardbooleanrequired
- carried_from_item_idinteger | nullrequired
- created_by_idintegerrequired
- created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409Signed reconciliation422Invalid change
Example request
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}/preparePrepare 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- prepareobjectrequired
- prepare.notestringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- period_namestringrequired
- entity_idintegerrequired
- rule_idinteger | nullrequired
- accountobjectrequired
- account.idintegerrequired
- account.numberstringrequired
- account.namestringrequired
- account.typestringrequired
- account.normal_balancestringrequired
- sourcestringrequiredOne of: tie_out, manual.
- tie_out_keystring | nullrequired
- risk_ratingstringrequired
- frequencystringrequiredOne of: monthly, quarterly.
- review_levelintegerrequiredOne of: 1, 2.
- materiality_absstringrequired
- materiality_pctstringrequired
- materialbooleanrequired
- tolerancestringrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- auto_reconciledbooleanrequired
- stalebooleanrequired
- stale_reasonstring | nullrequired
- liveobjectrequired
- live.gl_balancestringrequired
- live.support_balancestring | nullrequired
- live.items_totalstringrequired
- live.schedule_totalstringrequired
- live.unexplainedstring | nullrequired
- live.within_tolerancebooleanrequired
- live.tie_outobject | nullrequired
- live.bank_reconciliationobject | nullrequired
- signedobjectrequired
- signed.gl_balancestring | nullrequired
- signed.support_balancestring | nullrequired
- signed.items_totalstring | nullrequired
- signed.unexplainedstring | nullrequired
- signed.balance_debitstring | nullrequired
- signed.balance_creditstring | nullrequired
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- second_reviewed_by_idinteger | nullrequired
- second_reviewed_atstring | null (date-time)required
- second_review_notestring | nullrequired
- agingobjectrequired
- aging.oldest_daysinteger | nullrequired
- aging.bucketsobjectrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindstringrequiredOne of: reconciling_item, schedule_line.
- items[].descriptionstringrequired
- items[].referencestring | nullrequired
- items[].amountstringrequired
- items[].item_datestring | null (date)required
- items[].age_daysintegerrequired
- items[].aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- items[].clearedbooleanrequired
- items[].cleared_atstring | null (date-time)required
- items[].carried_forwardbooleanrequired
- items[].carried_from_item_idinteger | nullrequired
- items[].created_by_idintegerrequired
- items[].created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409Not in a state that allows this, changed concurrently, or stale since preparation422Invalid request, unavailable support, or an unexplained difference over tolerance
Example request
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}/reviewReview 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- period_namestringrequired
- entity_idintegerrequired
- rule_idinteger | nullrequired
- accountobjectrequired
- account.idintegerrequired
- account.numberstringrequired
- account.namestringrequired
- account.typestringrequired
- account.normal_balancestringrequired
- sourcestringrequiredOne of: tie_out, manual.
- tie_out_keystring | nullrequired
- risk_ratingstringrequired
- frequencystringrequiredOne of: monthly, quarterly.
- review_levelintegerrequiredOne of: 1, 2.
- materiality_absstringrequired
- materiality_pctstringrequired
- materialbooleanrequired
- tolerancestringrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- auto_reconciledbooleanrequired
- stalebooleanrequired
- stale_reasonstring | nullrequired
- liveobjectrequired
- live.gl_balancestringrequired
- live.support_balancestring | nullrequired
- live.items_totalstringrequired
- live.schedule_totalstringrequired
- live.unexplainedstring | nullrequired
- live.within_tolerancebooleanrequired
- live.tie_outobject | nullrequired
- live.bank_reconciliationobject | nullrequired
- signedobjectrequired
- signed.gl_balancestring | nullrequired
- signed.support_balancestring | nullrequired
- signed.items_totalstring | nullrequired
- signed.unexplainedstring | nullrequired
- signed.balance_debitstring | nullrequired
- signed.balance_creditstring | nullrequired
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- second_reviewed_by_idinteger | nullrequired
- second_reviewed_atstring | null (date-time)required
- second_review_notestring | nullrequired
- agingobjectrequired
- aging.oldest_daysinteger | nullrequired
- aging.bucketsobjectrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindstringrequiredOne of: reconciling_item, schedule_line.
- items[].descriptionstringrequired
- items[].referencestring | nullrequired
- items[].amountstringrequired
- items[].item_datestring | null (date)required
- items[].age_daysintegerrequired
- items[].aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- items[].clearedbooleanrequired
- items[].cleared_atstring | null (date-time)required
- items[].carried_forwardbooleanrequired
- items[].carried_from_item_idinteger | nullrequired
- items[].created_by_idintegerrequired
- items[].created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409Not in a state that allows this, changed concurrently, or stale since preparation422Invalid request, unavailable support, or an unexplained difference over tolerance
Example request
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}/unsignUnsign an account reconciliation
Withdraws every sign-off (back to in_progress) with a reason. Needs close_period. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- unsignobjectrequired
- unsign.reasonstringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- period_namestringrequired
- entity_idintegerrequired
- rule_idinteger | nullrequired
- accountobjectrequired
- account.idintegerrequired
- account.numberstringrequired
- account.namestringrequired
- account.typestringrequired
- account.normal_balancestringrequired
- sourcestringrequiredOne of: tie_out, manual.
- tie_out_keystring | nullrequired
- risk_ratingstringrequired
- frequencystringrequiredOne of: monthly, quarterly.
- review_levelintegerrequiredOne of: 1, 2.
- materiality_absstringrequired
- materiality_pctstringrequired
- materialbooleanrequired
- tolerancestringrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- auto_reconciledbooleanrequired
- stalebooleanrequired
- stale_reasonstring | nullrequired
- liveobjectrequired
- live.gl_balancestringrequired
- live.support_balancestring | nullrequired
- live.items_totalstringrequired
- live.schedule_totalstringrequired
- live.unexplainedstring | nullrequired
- live.within_tolerancebooleanrequired
- live.tie_outobject | nullrequired
- live.bank_reconciliationobject | nullrequired
- signedobjectrequired
- signed.gl_balancestring | nullrequired
- signed.support_balancestring | nullrequired
- signed.items_totalstring | nullrequired
- signed.unexplainedstring | nullrequired
- signed.balance_debitstring | nullrequired
- signed.balance_creditstring | nullrequired
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- second_reviewed_by_idinteger | nullrequired
- second_reviewed_atstring | null (date-time)required
- second_review_notestring | nullrequired
- agingobjectrequired
- aging.oldest_daysinteger | nullrequired
- aging.bucketsobjectrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindstringrequiredOne of: reconciling_item, schedule_line.
- items[].descriptionstringrequired
- items[].referencestring | nullrequired
- items[].amountstringrequired
- items[].item_datestring | null (date)required
- items[].age_daysintegerrequired
- items[].aging_bucketstringrequiredOne of: 0-30, 31-60, 61-90, over_90.
- items[].clearedbooleanrequired
- items[].cleared_atstring | null (date-time)required
- items[].carried_forwardbooleanrequired
- items[].carried_from_item_idinteger | nullrequired
- items[].created_by_idintegerrequired
- items[].created_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409Not in a state that allows this, changed concurrently, or stale since preparation422Invalid request, unavailable support, or an unexplained difference over tolerance
Example request
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/generateGenerate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- generateobjectrequired
- generate.period_idintegerrequired
- generate.entity_idinteger | null
Response · 200 · object
- createdintegerrequired
- carriedintegerrequired
- reconciledintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Period or entity not found
Example request
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/settingsClose 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- require_tasksbooleanrequired
- require_recsbooleanrequired
- require_fluxbooleanGL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
- default_template_idinteger | nullrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
Example request
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/settingsSave 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- settingsobjectrequired
- settings.require_tasksbooleanrequired
- settings.require_recsbooleanrequired
- settings.require_fluxbooleanGL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
- settings.default_template_idinteger | null
Response · 200 · object
- require_tasksbooleanrequired
- require_recsbooleanrequired
- require_fluxbooleanGL and whole-period close need every flux variance above threshold explained, reviewed and current (oas-flux.json). Omitted on PUT = unchanged.
- default_template_idinteger | nullrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace422Invalid settings or an unknown template
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idinteger | nullrequired
- keystringrequired
- titlestringrequired
- categorystringrequired
- close_modulestring | nullrequired
- owner_idinteger | nullrequired
- reviewer_idinteger | nullrequired
- due_datestring | null (date)required
- depends_onstring[]required
- evidencestring | nullrequired
- requiredbooleanrequired
- instructionsstring | nullrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- auto_completedbooleanrequired
- evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- evidence_messagestring | nullrequired
- evidence_checked_atstring | null (date-time)required
- stale_atstring | null (date-time)required
- stale_reasonstring | nullrequired
- overduebooleanrequired
- open_dependenciesstring[]required
- criticalbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/close/tasks/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Fiscal Periods
POST/rest/v1.0/companies/{company_id}/accounting/close/tasks/{id}/preparePrepare 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- prepareobjectrequired
- prepare.notestringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idinteger | nullrequired
- keystringrequired
- titlestringrequired
- categorystringrequired
- close_modulestring | nullrequired
- owner_idinteger | nullrequired
- reviewer_idinteger | nullrequired
- due_datestring | null (date)required
- depends_onstring[]required
- evidencestring | nullrequired
- requiredbooleanrequired
- instructionsstring | nullrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- auto_completedbooleanrequired
- evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- evidence_messagestring | nullrequired
- evidence_checked_atstring | null (date-time)required
- stale_atstring | null (date-time)required
- stale_reasonstring | nullrequired
- overduebooleanrequired
- open_dependenciesstring[]required
- criticalbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409The task is not in a state that allows this422Invalid request or unreviewed dependencies
Example request
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}/reviewReview 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idinteger | nullrequired
- keystringrequired
- titlestringrequired
- categorystringrequired
- close_modulestring | nullrequired
- owner_idinteger | nullrequired
- reviewer_idinteger | nullrequired
- due_datestring | null (date)required
- depends_onstring[]required
- evidencestring | nullrequired
- requiredbooleanrequired
- instructionsstring | nullrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- auto_completedbooleanrequired
- evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- evidence_messagestring | nullrequired
- evidence_checked_atstring | null (date-time)required
- stale_atstring | null (date-time)required
- stale_reasonstring | nullrequired
- overduebooleanrequired
- open_dependenciesstring[]required
- criticalbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409The task is not in a state that allows this422Invalid request or unreviewed dependencies
Example request
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}/startStart 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idinteger | nullrequired
- keystringrequired
- titlestringrequired
- categorystringrequired
- close_modulestring | nullrequired
- owner_idinteger | nullrequired
- reviewer_idinteger | nullrequired
- due_datestring | null (date)required
- depends_onstring[]required
- evidencestring | nullrequired
- requiredbooleanrequired
- instructionsstring | nullrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- auto_completedbooleanrequired
- evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- evidence_messagestring | nullrequired
- evidence_checked_atstring | null (date-time)required
- stale_atstring | null (date-time)required
- stale_reasonstring | nullrequired
- overduebooleanrequired
- open_dependenciesstring[]required
- criticalbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409The task is not in a state that allows this422Invalid request or unreviewed dependencies
Example request
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}/unsignUnsign 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- unsignobjectrequired
- unsign.reasonstringrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idinteger | nullrequired
- keystringrequired
- titlestringrequired
- categorystringrequired
- close_modulestring | nullrequired
- owner_idinteger | nullrequired
- reviewer_idinteger | nullrequired
- due_datestring | null (date)required
- depends_onstring[]required
- evidencestring | nullrequired
- requiredbooleanrequired
- instructionsstring | nullrequired
- statusstringrequiredOne of: not_started, in_progress, prepared, reviewed.
- prepared_by_idinteger | nullrequired
- prepared_atstring | null (date-time)required
- prep_notestring | nullrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- auto_completedbooleanrequired
- evidence_statusstring | nullrequiredOne of: passed, failed, unavailable, null.
- evidence_messagestring | nullrequired
- evidence_checked_atstring | null (date-time)required
- stale_atstring | null (date-time)required
- stale_reasonstring | nullrequired
- overduebooleanrequired
- open_dependenciesstring[]required
- criticalbooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409The task is not in a state that allows this422Invalid request or unreviewed dependencies
Example request
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/templatesList close templates
Every close template with its tasks. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- is_activebooleanrequired
- revisionintegerrequired
- created_atstring | null (date-time)required
- updated_atstring | null (date-time)required
- tasksobject[]required
- tasks[].keystringrequired
- tasks[].titlestringrequired
- tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- tasks[].close_modulestring | nullrequired
- tasks[].owner_idinteger | nullrequired
- tasks[].reviewer_idinteger | nullrequired
- tasks[].due_day_offsetintegerrequired
- tasks[].depends_onstring[]required
- tasks[].evidencestring | nullrequired
- tasks[].requiredbooleanrequired
- tasks[].instructionsstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace
Example request
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/templatesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- templateobjectrequired
- template.namestringrequired
- template.descriptionstring | null
- template.is_activeboolean
- template.tasksobject[]required
- template.tasks[].keystringrequired
- template.tasks[].titlestringrequired
- template.tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- template.tasks[].close_modulestring | nullOne of: ap, ar, payroll, jc, cm, gl, null.
- template.tasks[].owner_idinteger | null
- template.tasks[].reviewer_idinteger | null
- template.tasks[].due_day_offsetintegerrequired
- template.tasks[].depends_onstring[]
- template.tasks[].evidencestring | nullOne 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[].requiredboolean
- template.tasks[].instructionsstring | null
- revisioninteger
Response · 201 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- is_activebooleanrequired
- revisionintegerrequired
- created_atstring | null (date-time)required
- updated_atstring | null (date-time)required
- tasksobject[]required
- tasks[].keystringrequired
- tasks[].titlestringrequired
- tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- tasks[].close_modulestring | nullrequired
- tasks[].owner_idinteger | nullrequired
- tasks[].reviewer_idinteger | nullrequired
- tasks[].due_day_offsetintegerrequired
- tasks[].depends_onstring[]required
- tasks[].evidencestring | nullrequired
- tasks[].requiredbooleanrequired
- tasks[].instructionsstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace409A template with this name exists, or the Idempotency-Key was reused422Invalid tasks, unknown or cyclic dependencies, or an owner outside the company
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- is_activebooleanrequired
- revisionintegerrequired
- created_atstring | null (date-time)required
- updated_atstring | null (date-time)required
- tasksobject[]required
- tasks[].keystringrequired
- tasks[].titlestringrequired
- tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- tasks[].close_modulestring | nullrequired
- tasks[].owner_idinteger | nullrequired
- tasks[].reviewer_idinteger | nullrequired
- tasks[].due_day_offsetintegerrequired
- tasks[].depends_onstring[]required
- tasks[].evidencestring | nullrequired
- tasks[].requiredbooleanrequired
- tasks[].instructionsstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- templateobjectrequired
- template.namestringrequired
- template.descriptionstring | null
- template.is_activeboolean
- template.tasksobject[]required
- template.tasks[].keystringrequired
- template.tasks[].titlestringrequired
- template.tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- template.tasks[].close_modulestring | nullOne of: ap, ar, payroll, jc, cm, gl, null.
- template.tasks[].owner_idinteger | null
- template.tasks[].reviewer_idinteger | null
- template.tasks[].due_day_offsetintegerrequired
- template.tasks[].depends_onstring[]
- template.tasks[].evidencestring | nullOne 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[].requiredboolean
- template.tasks[].instructionsstring | null
- revisioninteger
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- is_activebooleanrequired
- revisionintegerrequired
- created_atstring | null (date-time)required
- updated_atstring | null (date-time)required
- tasksobject[]required
- tasks[].keystringrequired
- tasks[].titlestringrequired
- tasks[].categorystringrequiredOne of: subledger_close, accruals, reconciliations, reporting, review, other.
- tasks[].close_modulestring | nullrequired
- tasks[].owner_idinteger | nullrequired
- tasks[].reviewer_idinteger | nullrequired
- tasks[].due_day_offsetintegerrequired
- tasks[].depends_onstring[]required
- tasks[].evidencestring | nullrequired
- tasks[].requiredbooleanrequired
- tasks[].instructionsstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (or a project-scoped grant), outside the entity scope, wrong company, or read-only workspace404Not found in this company409The template changed, or the name is taken422Invalid tasks
Example request
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/runsList equity-method runs
Runs newest first. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- investee_entity_idintegerqueryFilter: investee
- period_idintegerqueryFilter: period
Response · 200 · object[]
- idintegerrequired
- investor_entity_idintegerrequired
- investee_entity_idintegerrequired
- ownership_idinteger
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)
- income_sourcestringOne of: ledger, manual.
- source_notestring | null
- investee_net_incomestringDecimal string with two places
- investee_ocistringDecimal string with two places
- share_of_incomestringDecimal string with two places
- recognized_incomestringDecimal string with two places
- share_of_ocistringDecimal string with two places
- carrying_beforestringDecimal string with two places
- suspended_beforestringDecimal string with two places
- suspended_afterstringDecimal string with two places
- post_incomestringDecimal string with two places
- post_ocistringDecimal string with two places
- segmentsobject[]
- evidence_hashstring
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idinteger | null
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/runsPrepare 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- runobjectrequired
- run.investee_entity_idintegerrequired
- run.period_idintegerrequired
- run.investee_net_incomestring
- run.investee_ocistring
- run.source_notestring
Response · 200 · object
- idintegerrequired
- investor_entity_idintegerrequired
- investee_entity_idintegerrequired
- ownership_idinteger
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)
- income_sourcestringOne of: ledger, manual.
- source_notestring | null
- investee_net_incomestringDecimal string with two places
- investee_ocistringDecimal string with two places
- share_of_incomestringDecimal string with two places
- recognized_incomestringDecimal string with two places
- share_of_ocistringDecimal string with two places
- carrying_beforestringDecimal string with two places
- suspended_beforestringDecimal string with two places
- suspended_afterstringDecimal string with two places
- post_incomestringDecimal string with two places
- post_ocistringDecimal string with two places
- segmentsobject[]
- evidence_hashstring
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idinteger | null
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- investor_entity_idintegerrequired
- investee_entity_idintegerrequired
- ownership_idinteger
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)
- income_sourcestringOne of: ledger, manual.
- source_notestring | null
- investee_net_incomestringDecimal string with two places
- investee_ocistringDecimal string with two places
- share_of_incomestringDecimal string with two places
- recognized_incomestringDecimal string with two places
- share_of_ocistringDecimal string with two places
- carrying_beforestringDecimal string with two places
- suspended_beforestringDecimal string with two places
- suspended_afterstringDecimal string with two places
- post_incomestringDecimal string with two places
- post_ocistringDecimal string with two places
- segmentsobject[]
- evidence_hashstring
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idinteger | null
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/decisionApprove 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionstringrequiredOne of: approve, cancel.
- decision.reasonstringRequired to cancel
Response · 200 · object
- idintegerrequired
- investor_entity_idintegerrequired
- investee_entity_idintegerrequired
- ownership_idinteger
- period_idintegerrequired
- revisionintegerrequired
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- as_ofstring (date)
- income_sourcestringOne of: ledger, manual.
- source_notestring | null
- investee_net_incomestringDecimal string with two places
- investee_ocistringDecimal string with two places
- share_of_incomestringDecimal string with two places
- recognized_incomestringDecimal string with two places
- share_of_ocistringDecimal string with two places
- carrying_beforestringDecimal string with two places
- suspended_beforestringDecimal string with two places
- suspended_afterstringDecimal string with two places
- post_incomestringDecimal string with two places
- post_ocistringDecimal string with two places
- segmentsobject[]
- evidence_hashstring
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idinteger | null
- cancel_reasonstring | null
- unchangedboolean
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/disputesList intercompany disputes
Newest first. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- statusstringqueryFilter: status One of: open, adjustment_pending, resolved, withdrawn.
Response · 200 · object[]
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/disputesRaise 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- disputeobjectrequired
- dispute.entity_a_idintegerrequired
- dispute.entity_b_idintegerrequired
- dispute.currencystringrequired
- dispute.as_ofstring (date)required
- dispute.notestring
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/adjustmentPropose 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- adjustmentobjectrequired
- adjustment.posting_datestring (date)required
- adjustment.offset_account_idintegerrequired
- adjustment.memostring
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/assignAssign 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- assignmentobjectrequired
- assignment.assignee_user_idintegerrequired
- assignment.responsible_entity_idintegerrequired
- assignment.notestring
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/commentsComment on an intercompany dispute
Adds a comment to the dispute's history. Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- commentobjectrequired
- comment.bodystringrequired
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/decisionApprove 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionstringrequiredOne of: approve, reject.
- decision.reasonstringRequired to reject
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/resolveResolve 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- resolutionobjectrequired
- resolution.actionstringrequiredOne of: resolve, withdraw.
- resolution.notestringrequired
Response · 200 · object
- idintegerrequired
- entity_a_idintegerrequired
- entity_b_idintegerrequired
- currencystringrequired
- as_ofstring (date)
- differencestringrequiredDecimal string with two places
- statusstringrequiredOne of: open, adjustment_pending, resolved, withdrawn.
- assignee_user_idinteger | null
- responsible_entity_idinteger | null
- raised_by_idinteger
- proposalobject | null
- proposed_by_idinteger | null
- proposed_atstring | null (date-time)
- entry_idinteger | null
- resolved_by_idinteger | null
- resolved_atstring | null (date-time)
- resolutionstring | null
- created_atstring (date-time)
- eventsobject[]
- events[].idinteger
- events[].kindstring
- events[].actor_idinteger
- events[].bodystring | null
- events[].dataany
- events[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/settlementsList intercompany settlement runs
Newest first. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- as_ofstring (date)required
- modestringrequiredOne of: cash, netting.
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- evidence_hashstring
- linesobject[]required
- lines[].entity_idinteger
- lines[].counterparty_entity_idinteger | null
- lines[].account_idinteger
- lines[].debitstringDecimal string with two places
- lines[].creditstringDecimal string with two places
- pairsobject[]
- pairs[].entity_a_idinteger
- pairs[].entity_b_idinteger
- pairs[].amountstringDecimal string with two places
- cash_accountsobject | null
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idsinteger[]
- cancel_reasonstring | null
- unchangedboolean
- skippedobject[]
- skipped[].entity_a_idinteger
- skipped[].entity_b_idinteger
- skipped[].reasonstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/settlementsPrepare 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- settlementobjectrequired
- settlement.as_ofstring (date)required
- settlement.modestringrequiredOne of: cash, netting.
- settlement.cash_accountsobject[]
- settlement.cash_accounts[].entity_idintegerrequired
- settlement.cash_accounts[].account_idintegerrequired
- settlement.pairsobject[]
- settlement.pairs[].entity_a_idintegerrequired
- settlement.pairs[].entity_b_idintegerrequired
Response · 200 · object
- idintegerrequired
- as_ofstring (date)required
- modestringrequiredOne of: cash, netting.
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- evidence_hashstring
- linesobject[]required
- lines[].entity_idinteger
- lines[].counterparty_entity_idinteger | null
- lines[].account_idinteger
- lines[].debitstringDecimal string with two places
- lines[].creditstringDecimal string with two places
- pairsobject[]
- pairs[].entity_a_idinteger
- pairs[].entity_b_idinteger
- pairs[].amountstringDecimal string with two places
- cash_accountsobject | null
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idsinteger[]
- cancel_reasonstring | null
- unchangedboolean
- skippedobject[]
- skipped[].entity_a_idinteger
- skipped[].entity_b_idinteger
- skipped[].reasonstring
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- as_ofstring (date)required
- modestringrequiredOne of: cash, netting.
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- evidence_hashstring
- linesobject[]required
- lines[].entity_idinteger
- lines[].counterparty_entity_idinteger | null
- lines[].account_idinteger
- lines[].debitstringDecimal string with two places
- lines[].creditstringDecimal string with two places
- pairsobject[]
- pairs[].entity_a_idinteger
- pairs[].entity_b_idinteger
- pairs[].amountstringDecimal string with two places
- cash_accountsobject | null
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idsinteger[]
- cancel_reasonstring | null
- unchangedboolean
- skippedobject[]
- skipped[].entity_a_idinteger
- skipped[].entity_b_idinteger
- skipped[].reasonstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/decisionApprove 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionstringrequiredOne of: approve, cancel.
- decision.reasonstringRequired to cancel
Response · 200 · object
- idintegerrequired
- as_ofstring (date)required
- modestringrequiredOne of: cash, netting.
- statusstringrequiredOne of: prepared, posted, cancelled, superseded.
- evidence_hashstring
- linesobject[]required
- lines[].entity_idinteger
- lines[].counterparty_entity_idinteger | null
- lines[].account_idinteger
- lines[].debitstringDecimal string with two places
- lines[].creditstringDecimal string with two places
- pairsobject[]
- pairs[].entity_a_idinteger
- pairs[].entity_b_idinteger
- pairs[].amountstringDecimal string with two places
- cash_accountsobject | null
- prepared_by_idinteger
- prepared_atstring (date-time)
- approved_by_idinteger | null
- approved_atstring | null (date-time)
- entry_idsinteger[]
- cancel_reasonstring | null
- unchangedboolean
- skippedobject[]
- skipped[].entity_a_idinteger
- skipped[].entity_b_idinteger
- skipped[].reasonstring
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/transfersList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)queryDate for the status amounts (default: today)
- include_voidedstringqueryInclude voided transfers One of: true, false.
Response · 200 · object[]
- idintegerrequired
- kindstringrequiredOne of: fixed_asset, inventory.
- seller_entity_idintegerrequired
- buyer_entity_idintegerrequired
- transfer_datestring (date)required
- sale_amountstringrequiredDecimal string with two places
- seller_coststringrequiredDecimal string with two places
- seller_gain_account_idinteger
- seller_cost_account_idinteger | null
- buyer_asset_account_idinteger
- buyer_expense_account_idinteger
- useful_life_monthsinteger | null
- depreciation_startstring | null (date)
- memostring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedboolean
- voided_atstring | null (date-time)
- void_reasonstring | null
- eventsobject[]
- events[].idinteger
- events[].kindstringOne of: sold, disposed.
- events[].event_datestring (date)
- events[].percentstring
- events[].notestring | null
- events[].created_by_idinteger
- statusobjectrequired
- status.profitstringDecimal string with two places
- status.recognizedstringDecimal string with two places
- status.deferredstringDecimal string with two places
- status.as_ofstring (date)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/transfersRegister 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- transferobjectrequired
- transfer.kindstringrequiredOne of: fixed_asset, inventory.
- transfer.seller_entity_idintegerrequired
- transfer.buyer_entity_idintegerrequired
- transfer.transfer_datestring (date)required
- transfer.sale_amountstringrequired
- transfer.seller_coststringrequired
- transfer.seller_gain_account_idintegerrequired
- transfer.seller_cost_account_idinteger | null
- transfer.buyer_asset_account_idintegerrequired
- transfer.buyer_expense_account_idintegerrequired
- transfer.useful_life_monthsinteger | null
- transfer.depreciation_startstring | null (date)
- transfer.memostring | null
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: fixed_asset, inventory.
- seller_entity_idintegerrequired
- buyer_entity_idintegerrequired
- transfer_datestring (date)required
- sale_amountstringrequiredDecimal string with two places
- seller_coststringrequiredDecimal string with two places
- seller_gain_account_idinteger
- seller_cost_account_idinteger | null
- buyer_asset_account_idinteger
- buyer_expense_account_idinteger
- useful_life_monthsinteger | null
- depreciation_startstring | null (date)
- memostring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedboolean
- voided_atstring | null (date-time)
- void_reasonstring | null
- eventsobject[]
- events[].idinteger
- events[].kindstringOne of: sold, disposed.
- events[].event_datestring (date)
- events[].percentstring
- events[].notestring | null
- events[].created_by_idinteger
- statusobjectrequired
- status.profitstringDecimal string with two places
- status.recognizedstringDecimal string with two places
- status.deferredstringDecimal string with two places
- status.as_ofstring (date)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- as_ofstring (date)queryDate for the status amounts (default: today)
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: fixed_asset, inventory.
- seller_entity_idintegerrequired
- buyer_entity_idintegerrequired
- transfer_datestring (date)required
- sale_amountstringrequiredDecimal string with two places
- seller_coststringrequiredDecimal string with two places
- seller_gain_account_idinteger
- seller_cost_account_idinteger | null
- buyer_asset_account_idinteger
- buyer_expense_account_idinteger
- useful_life_monthsinteger | null
- depreciation_startstring | null (date)
- memostring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedboolean
- voided_atstring | null (date-time)
- void_reasonstring | null
- eventsobject[]
- events[].idinteger
- events[].kindstringOne of: sold, disposed.
- events[].event_datestring (date)
- events[].percentstring
- events[].notestring | null
- events[].created_by_idinteger
- statusobjectrequired
- status.profitstringDecimal string with two places
- status.recognizedstringDecimal string with two places
- status.deferredstringDecimal string with two places
- status.as_ofstring (date)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/eventsRecord 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- eventobjectrequired
- event.kindstringrequiredOne of: sold, disposed.
- event.event_datestring (date)required
- event.percentstringPercent 0-100, up to four decimals
- event.notestring
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: fixed_asset, inventory.
- seller_entity_idintegerrequired
- buyer_entity_idintegerrequired
- transfer_datestring (date)required
- sale_amountstringrequiredDecimal string with two places
- seller_coststringrequiredDecimal string with two places
- seller_gain_account_idinteger
- seller_cost_account_idinteger | null
- buyer_asset_account_idinteger
- buyer_expense_account_idinteger
- useful_life_monthsinteger | null
- depreciation_startstring | null (date)
- memostring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedboolean
- voided_atstring | null (date-time)
- void_reasonstring | null
- eventsobject[]
- events[].idinteger
- events[].kindstringOne of: sold, disposed.
- events[].event_datestring (date)
- events[].percentstring
- events[].notestring | null
- events[].created_by_idinteger
- statusobjectrequired
- status.profitstringDecimal string with two places
- status.recognizedstringDecimal string with two places
- status.deferredstringDecimal string with two places
- status.as_ofstring (date)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/voidVoid 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: fixed_asset, inventory.
- seller_entity_idintegerrequired
- buyer_entity_idintegerrequired
- transfer_datestring (date)required
- sale_amountstringrequiredDecimal string with two places
- seller_coststringrequiredDecimal string with two places
- seller_gain_account_idinteger
- seller_cost_account_idinteger | null
- buyer_asset_account_idinteger
- buyer_expense_account_idinteger
- useful_life_monthsinteger | null
- depreciation_startstring | null (date)
- memostring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedboolean
- voided_atstring | null (date-time)
- void_reasonstring | null
- eventsobject[]
- events[].idinteger
- events[].kindstringOne of: sold, disposed.
- events[].event_datestring (date)
- events[].percentstring
- events[].notestring | null
- events[].created_by_idinteger
- statusobjectrequired
- status.profitstringDecimal string with two places
- status.recognizedstringDecimal string with two places
- status.deferredstringDecimal string with two places
- status.as_ofstring (date)
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/ownershipList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- child_entity_idintegerqueryFilter: child entity
- include_voidedstringqueryInclude voided versions One of: true, false.
Response · 200 · object[]
- idintegerrequired
- parent_entity_idintegerrequired
- child_entity_idintegerrequired
- ownership_pctstringrequired
- voting_pctstringrequired
- nci_pctstring | null
- methodstringrequiredOne of: full, equity, cost, none.
- effective_fromstring (date)required
- investment_account_idinteger | null
- earnings_account_idinteger | null
- control_basisstring | null
- notestring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedbooleanrequired
- voided_atstring | null (date-time)
- voided_by_idinteger | null
- void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/ownershipRecord 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- ownershipobjectrequired
- ownership.parent_entity_idintegerrequired
- ownership.child_entity_idintegerrequired
- ownership.ownership_pctstringrequiredPercent 0-100, up to four decimals
- ownership.voting_pctstringVoting percent (default: the ownership percent)
- ownership.methodstringrequiredOne of: full, equity, cost, none.
- ownership.effective_fromstring (date)required
- ownership.investment_account_idinteger | null
- ownership.earnings_account_idinteger | null
- ownership.control_basisstring | null
- ownership.notestring | null
Response · 200 · object
- idintegerrequired
- parent_entity_idintegerrequired
- child_entity_idintegerrequired
- ownership_pctstringrequired
- voting_pctstringrequired
- nci_pctstring | null
- methodstringrequiredOne of: full, equity, cost, none.
- effective_fromstring (date)required
- investment_account_idinteger | null
- earnings_account_idinteger | null
- control_basisstring | null
- notestring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedbooleanrequired
- voided_atstring | null (date-time)
- voided_by_idinteger | null
- void_reasonstring | null
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- parent_entity_idintegerrequired
- child_entity_idintegerrequired
- ownership_pctstringrequired
- voting_pctstringrequired
- nci_pctstring | null
- methodstringrequiredOne of: full, equity, cost, none.
- effective_fromstring (date)required
- investment_account_idinteger | null
- earnings_account_idinteger | null
- control_basisstring | null
- notestring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedbooleanrequired
- voided_atstring | null (date-time)
- voided_by_idinteger | null
- void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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}/voidVoid 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- parent_entity_idintegerrequired
- child_entity_idintegerrequired
- ownership_pctstringrequired
- voting_pctstringrequired
- nci_pctstring | null
- methodstringrequiredOne of: full, equity, cost, none.
- effective_fromstring (date)required
- investment_account_idinteger | null
- earnings_account_idinteger | null
- control_basisstring | null
- notestring | null
- created_by_idinteger
- created_atstring (date-time)
- voidedbooleanrequired
- voided_atstring | null (date-time)
- voided_by_idinteger | null
- void_reasonstring | null
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/settingsConsolidation settings
The intercompany matching tolerance. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- ic_tolerancestringrequiredDecimal string with two places
- updated_atstring | null (date-time)
- updated_by_idinteger | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/settingsUpdate consolidation settings
Sets the intercompany matching tolerance (manage_coa over every entity). Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- settingsobjectrequired
- settings.ic_tolerancestringrequired
Response · 200 · object
- ic_tolerancestringrequiredDecimal string with two places
- updated_atstring | null (date-time)
- updated_by_idinteger | null
Errors
401Missing or invalid bearer token403No 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 work404Not found in this company409A conflicting version or decision, an evidence change since preparation, an Idempotency-Key reuse, or an immutable row422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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/structureConsolidation 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)queryDate (default: today)
Response · 200 · object
- as_ofstring (date)required
- membersobject[]required
- members[].entity_idinteger
- members[].codestring | null
- members[].namestring | null
- members[].parent_entity_idinteger | null
- members[].ownership_idinteger | null
- members[].ownership_pctstring | null
- members[].group_share_pctstring
- members[].nci_pctstring
- members[].methodstringOne of: root, full.
- outsideobject[]required
- outside[].entity_idinteger
- outside[].codestring | null
- outside[].namestring | null
- outside[].reasonstringOne of: equity, cost, none, under_excluded.
- outside[].parent_entity_idinteger | null
- outside[].ownership_idinteger | null
- outside[].ownership_pctstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, a grant limited to some entities or projects (consolidation covers every entity), wrong company404Not found in this company422Validation failed, a closed period, a missing account mapping, or nothing to do
Example request
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_yearsGenerate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- fiscal_yearobjectrequired
- fiscal_year.yearintegerrequired
- fiscal_year.closedbooleanCreate every period and module closed. Required when the year comes before a closed period (422 otherwise).
Response · 201 · object
- idintegerrequired
- yearintegerrequired
- start_datestring (date)required
- end_datestring (date)required
- statusanyrequiredOne of: open, soft_closed, closed.
- periodsobject[]required
- periods[].idintegerrequired
- periods[].fiscal_year_idintegerrequired
- periods[].fiscal_yearinteger | nullrequired
- periods[].numberintegerrequired
- periods[].namestringrequired
- periods[].start_datestring (date)required
- periods[].end_datestring (date)required
- periods[].statusanyrequiredOne of: open, soft_closed, closed.
- periods[].module_statusobjectrequired
- periods[].closed_atstring | null (date-time)required
- periods[].closed_by_idinteger | nullrequired
- periods[].is_adjustingbooleanrequiredPeriod 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[].entitiesobject[]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[].rollupobjectPresent 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 token403No accounting access, missing permission, wrong company, or read-only workspace409Conflict, including an Idempotency-Key reused for a different request or still in progress422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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_periodAdd 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- periodobjectrequired
- period.idintegerrequired
- period.fiscal_year_idintegerrequired
- period.fiscal_yearinteger | nullrequired
- period.numberintegerrequired
- period.namestringrequired
- period.start_datestring (date)required
- period.end_datestring (date)required
- period.statusanyrequiredOne of: open, soft_closed, closed.
- period.module_statusobjectrequired
- period.closed_atstring | null (date-time)required
- period.closed_by_idinteger | nullrequired
- period.is_adjustingbooleanrequiredPeriod 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.entitiesobject[]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.rollupobjectPresent with `entities`: active entities closed out of the active entities listed.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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_closePost 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- fiscal_yearobject
- fiscal_year.idinteger
- fiscal_year.yearinteger
- fiscal_year.start_datestring (date)
- fiscal_year.end_datestring (date)
- fiscal_year.statusanyOne of: open, soft_closed, closed.
- journal_entryobject
- journal_entry.idintegerrequired
- journal_entry.numberstring | nullrequiredJE-YYYY-#####, assigned on posting
- journal_entry.statusanyrequiredOne of: draft, pending_approval, posted, reversed.
- journal_entry.journalanyrequiredOne of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- journal_entry.entity_idintegerrequired
- journal_entry.period_idintegerrequired
- journal_entry.posting_datestring (date)required
- journal_entry.document_datestring | null (date)required
- journal_entry.memostring | nullrequired
- journal_entry.source_typestringrequired
- journal_entry.source_idinteger | nullrequired
- journal_entry.source_revisionintegerrequired
- journal_entry.total_amountstringrequiredDecimal amount as a string, 2 dp
- journal_entry.currencystringrequired
- journal_entry.prepared_by_idintegerrequired
- journal_entry.approved_by_idinteger | nullrequired
- journal_entry.posted_by_idinteger | nullrequired
- journal_entry.posted_atstring | null (date-time)required
- journal_entry.reverses_idinteger | nullrequired
- journal_entry.reversed_by_idinteger | nullrequired
- journal_entry.auto_reverse_datestring | null (date)required
- journal_entry.created_atstring (date-time)required
- journal_entry.updated_atstring (date-time)required
- journal_entry.exchange_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- journal_entry.is_closing_entrybooleanrequired
- journal_entry.batch_idinteger | nullrequired
- journal_entry.recurring_idinteger | nullrequired
- journal_entry.submitted_atstring | null (date-time)required
- journal_entry.approved_atstring | null (date-time)required
- journal_entry.total_debitstringrequiredDecimal amount as a string, 2 dp
- journal_entry.total_creditstringrequiredDecimal amount as a string, 2 dp
- journal_entry.balancedbooleanrequired
- journal_entry.linesobject[]required
- journal_entry.is_noncashbooleanrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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/reverseReverse 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reversalobject
- reversal.reasonstring | null
Response · 201 · object
- idintegerrequired
- numberstring | nullrequiredJE-YYYY-#####, assigned on posting
- statusanyrequiredOne of: draft, pending_approval, posted, reversed.
- journalanyrequiredOne of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- entity_idintegerrequired
- period_idintegerrequired
- posting_datestring (date)required
- document_datestring | null (date)required
- memostring | nullrequired
- source_typestringrequired
- source_idinteger | nullrequired
- source_revisionintegerrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- currencystringrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- posted_by_idinteger | nullrequired
- posted_atstring | null (date-time)required
- reverses_idinteger | nullrequired
- reversed_by_idinteger | nullrequired
- auto_reverse_datestring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- exchange_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- is_closing_entrybooleanrequired
- batch_idinteger | nullrequired
- recurring_idinteger | nullrequired
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- total_debitstringrequiredDecimal amount as a string, 2 dp
- total_creditstringrequiredDecimal amount as a string, 2 dp
- balancedbooleanrequired
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].account_numberstring | nullrequired
- lines[].account_namestring | nullrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].entity_idintegerrequired
- lines[].counterparty_entity_idinteger | nullrequiredThe 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_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].employee_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].commitment_idinteger | nullrequired
- lines[].contract_idinteger | nullrequired
- lines[].tax_code_idinteger | nullrequired
- lines[].quantitystring | nullrequiredDecimal rate or quantity as a string, 6 dp
- lines[].unitstring | nullrequired
- lines[].billablebooleanrequired
- lines[].reconcile_stateanyrequiredOne of: n, c, y, v.
- lines[].source_typestring | nullrequired
- lines[].source_idinteger | nullrequired
- is_noncashbooleanrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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/periodsList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- filters[fiscal_year]integerqueryFiscal year label
- filters[status]stringqueryopen, soft_closed or closed (comma-separated)
Response · 200 · object[]
- idintegerrequired
- fiscal_year_idintegerrequired
- fiscal_yearinteger | nullrequired
- numberintegerrequired
- namestringrequired
- start_datestring (date)required
- end_datestring (date)required
- statusanyrequiredOne of: open, soft_closed, closed.
- module_statusobjectrequired
- module_status.apanyrequiredOne of: open, soft_closed, closed.
- module_status.aranyrequiredOne of: open, soft_closed, closed.
- module_status.payrollanyrequiredOne of: open, soft_closed, closed.
- module_status.jcanyrequiredOne of: open, soft_closed, closed.
- module_status.cmanyrequiredOne of: open, soft_closed, closed.
- module_status.glanyrequiredOne of: open, soft_closed, closed.
- closed_atstring | null (date-time)required
- closed_by_idinteger | nullrequired
- is_adjustingbooleanrequiredPeriod 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.
- entitiesobject[]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_idintegerrequired
- entities[].statusanyrequiredOne of: open, soft_closed, closed.
- entities[].module_statusobjectrequired
- entities[].closed_atstring | null (date-time)required
- entities[].closed_by_idinteger | nullrequired
- rollupobjectPresent with `entities`: active entities closed out of the active entities listed.
- rollup.closed_entitiesintegerrequired
- rollup.total_entitiesintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Unknown filter value
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- fiscal_year_idintegerrequired
- fiscal_yearinteger | nullrequired
- numberintegerrequired
- namestringrequired
- start_datestring (date)required
- end_datestring (date)required
- statusanyrequiredOne of: open, soft_closed, closed.
- module_statusobjectrequired
- module_status.apanyrequiredOne of: open, soft_closed, closed.
- module_status.aranyrequiredOne of: open, soft_closed, closed.
- module_status.payrollanyrequiredOne of: open, soft_closed, closed.
- module_status.jcanyrequiredOne of: open, soft_closed, closed.
- module_status.cmanyrequiredOne of: open, soft_closed, closed.
- module_status.glanyrequiredOne of: open, soft_closed, closed.
- closed_atstring | null (date-time)required
- closed_by_idinteger | nullrequired
- is_adjustingbooleanrequiredPeriod 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.
- entitiesobject[]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_idintegerrequired
- entities[].statusanyrequiredOne of: open, soft_closed, closed.
- entities[].module_statusobjectrequired
- entities[].closed_atstring | null (date-time)required
- entities[].closed_by_idinteger | nullrequired
- rollupobjectPresent with `entities`: active entities closed out of the active entities listed.
- rollup.closed_entitiesintegerrequired
- rollup.total_entitiesintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/periods/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Fiscal Periods
POST/rest/v1.0/companies/{company_id}/accounting/periods/{id}/closeClose 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- closeobjectrequired
- close.moduleanyOne of: all, ap, ar, payroll, jc, cm, gl.
- close.statusanyOne of: soft_closed, closed.
- close.entity_idintegerPer-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
- idintegerrequired
- fiscal_year_idintegerrequired
- fiscal_yearinteger | nullrequired
- numberintegerrequired
- namestringrequired
- start_datestring (date)required
- end_datestring (date)required
- statusanyrequiredOne of: open, soft_closed, closed.
- module_statusobjectrequired
- module_status.apanyrequiredOne of: open, soft_closed, closed.
- module_status.aranyrequiredOne of: open, soft_closed, closed.
- module_status.payrollanyrequiredOne of: open, soft_closed, closed.
- module_status.jcanyrequiredOne of: open, soft_closed, closed.
- module_status.cmanyrequiredOne of: open, soft_closed, closed.
- module_status.glanyrequiredOne of: open, soft_closed, closed.
- closed_atstring | null (date-time)required
- closed_by_idinteger | nullrequired
- is_adjustingbooleanrequiredPeriod 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.
- entitiesobject[]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_idintegerrequired
- entities[].statusanyrequiredOne of: open, soft_closed, closed.
- entities[].module_statusobjectrequired
- entities[].closed_atstring | null (date-time)required
- entities[].closed_by_idinteger | nullrequired
- rollupobjectPresent with `entities`: active entities closed out of the active entities listed.
- rollup.closed_entitiesintegerrequired
- rollup.total_entitiesintegerrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, read-only workspace, an entity outside the grant's entities, or (without entity_id) an entity-restricted grant404Not found in this company422Validation 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
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_intercompanyEliminate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- journal_entryobject | nullrequired
- journal_entry.idintegerrequired
- journal_entry.numberstring | nullrequiredJE-YYYY-#####, assigned on posting
- journal_entry.statusanyrequiredOne of: draft, pending_approval, posted, reversed.
- journal_entry.journalanyrequiredOne of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- journal_entry.entity_idintegerrequired
- journal_entry.period_idintegerrequired
- journal_entry.posting_datestring (date)required
- journal_entry.document_datestring | null (date)required
- journal_entry.memostring | nullrequired
- journal_entry.source_typestringrequired
- journal_entry.source_idinteger | nullrequired
- journal_entry.source_revisionintegerrequired
- journal_entry.total_amountstringrequiredDecimal amount as a string, 2 dp
- journal_entry.currencystringrequired
- journal_entry.prepared_by_idintegerrequired
- journal_entry.approved_by_idinteger | nullrequired
- journal_entry.posted_by_idinteger | nullrequired
- journal_entry.posted_atstring | null (date-time)required
- journal_entry.reverses_idinteger | nullrequired
- journal_entry.reversed_by_idinteger | nullrequired
- journal_entry.auto_reverse_datestring | null (date)required
- journal_entry.created_atstring (date-time)required
- journal_entry.updated_atstring (date-time)required
- journal_entry.exchange_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- journal_entry.is_closing_entrybooleanrequired
- journal_entry.batch_idinteger | nullrequired
- journal_entry.recurring_idinteger | nullrequired
- journal_entry.submitted_atstring | null (date-time)required
- journal_entry.approved_atstring | null (date-time)required
- journal_entry.total_debitstringrequiredDecimal amount as a string, 2 dp
- journal_entry.total_creditstringrequiredDecimal amount as a string, 2 dp
- journal_entry.balancedbooleanrequired
- journal_entry.linesobject[]required
- journal_entry.is_noncashbooleanrequired
- createdbooleanrequired
- pl_mismatchesobject[]requiredEntity pairs (by entity code) whose counterparty P&L lines do not net to zero for the period; left in consolidation, not eliminated.
- pl_mismatches[].astringrequired
- pl_mismatches[].bstringrequired
- pl_mismatches[].differencestringrequired
- pl_journal_entryobject | nullrequiredThe 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.idintegerrequired
- pl_journal_entry.numberstring | nullrequiredJE-YYYY-#####, assigned on posting
- pl_journal_entry.statusanyrequiredOne of: draft, pending_approval, posted, reversed.
- pl_journal_entry.journalanyrequiredOne of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- pl_journal_entry.entity_idintegerrequired
- pl_journal_entry.period_idintegerrequired
- pl_journal_entry.posting_datestring (date)required
- pl_journal_entry.document_datestring | null (date)required
- pl_journal_entry.memostring | nullrequired
- pl_journal_entry.source_typestringrequired
- pl_journal_entry.source_idinteger | nullrequired
- pl_journal_entry.source_revisionintegerrequired
- pl_journal_entry.total_amountstringrequiredDecimal amount as a string, 2 dp
- pl_journal_entry.currencystringrequired
- pl_journal_entry.prepared_by_idintegerrequired
- pl_journal_entry.approved_by_idinteger | nullrequired
- pl_journal_entry.posted_by_idinteger | nullrequired
- pl_journal_entry.posted_atstring | null (date-time)required
- pl_journal_entry.reverses_idinteger | nullrequired
- pl_journal_entry.reversed_by_idinteger | nullrequired
- pl_journal_entry.auto_reverse_datestring | null (date)required
- pl_journal_entry.created_atstring (date-time)required
- pl_journal_entry.updated_atstring (date-time)required
- pl_journal_entry.exchange_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- pl_journal_entry.is_closing_entrybooleanrequired
- pl_journal_entry.batch_idinteger | nullrequired
- pl_journal_entry.recurring_idinteger | nullrequired
- pl_journal_entry.submitted_atstring | null (date-time)required
- pl_journal_entry.approved_atstring | null (date-time)required
- pl_journal_entry.total_debitstringrequiredDecimal amount as a string, 2 dp
- pl_journal_entry.total_creditstringrequiredDecimal amount as a string, 2 dp
- pl_journal_entry.balancedbooleanrequired
- pl_journal_entry.linesobject[]required
- pl_journal_entry.is_noncashbooleanrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/periods/1/eliminate_intercompany" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Fiscal Periods
POST/rest/v1.0/companies/{company_id}/accounting/periods/{id}/reopenReopen 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reopenobjectrequired
- reopen.moduleanyOne of: all, ap, ar, payroll, jc, cm, gl.
- reopen.reasonstringrequired
- reopen.cascadeboolean
- reopen.entity_idintegerPer-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
- idintegerrequired
- fiscal_year_idintegerrequired
- fiscal_yearinteger | nullrequired
- numberintegerrequired
- namestringrequired
- start_datestring (date)required
- end_datestring (date)required
- statusanyrequiredOne of: open, soft_closed, closed.
- module_statusobjectrequired
- module_status.apanyrequiredOne of: open, soft_closed, closed.
- module_status.aranyrequiredOne of: open, soft_closed, closed.
- module_status.payrollanyrequiredOne of: open, soft_closed, closed.
- module_status.jcanyrequiredOne of: open, soft_closed, closed.
- module_status.cmanyrequiredOne of: open, soft_closed, closed.
- module_status.glanyrequiredOne of: open, soft_closed, closed.
- closed_atstring | null (date-time)required
- closed_by_idinteger | nullrequired
- is_adjustingbooleanrequiredPeriod 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.
- entitiesobject[]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_idintegerrequired
- entities[].statusanyrequiredOne of: open, soft_closed, closed.
- entities[].module_statusobjectrequired
- entities[].closed_atstring | null (date-time)required
- entities[].closed_by_idinteger | nullrequired
- rollupobjectPresent with `entities`: active entities closed out of the active entities listed.
- rollup.closed_entitiesintegerrequired
- rollup.total_entitiesintegerrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, read-only workspace, an entity outside the grant's entities, or (without entity_id) an entity-restricted grant404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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_balancesRebuild 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- reasonstringrequired
Response · 200 · object
- correctedintegerrequiredSnapshot rows that differed from the lines
- rowsintegerrequiredSnapshot rows written
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed (reason missing)
Example request
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"
}'