Journal Entries
Prepare, approve, post and reverse journals, recurring entries and allocations. 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 Journal Entries guide for the workflow.
- POST
/rest/v1.0/companies/{company_id}/accounting/allocation_runsPost an allocation run - POST
/rest/v1.0/companies/{company_id}/accounting/allocation_runs/{id}/reverseReverse an allocation run - GET
/rest/v1.0/companies/{company_id}/accounting/journal_entriesList journal entries - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entriesCreate a draft journal entry - GET
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Show a journal entry - PATCH
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Update a draft journal entry - DELETE
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Delete a draft journal entry - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/approveApprove a journal entry - GET
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsList attachments on a journal entry - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsAttach a file to a journal entry - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/postPost a journal entry - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/rejectReject a journal entry (return to the preparer) - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/reverseReverse a posted journal entry - POST
/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/submitSubmit a journal entry for approval - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/forecastUpcoming amortization forecast - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/roll_forwardPrepaid and deferred revenue roll-forward - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/runsList amortization runs - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/runsPrepare an amortization run - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}Show an amortization run - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/decisionApprove and post, or cancel, a prepared run - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/reverseReverse a posted run - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesList prepaid and deferred revenue schedules - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesCreate a schedule, or defer an AP bill line - GET
/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}Show a schedule with its versions - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/modificationsModify or cancel a schedule - POST
/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/voidVoid a schedule entered by mistake - GET
/rest/v1.0/companies/{company_id}/accounting/recurring_journalsList recurring journals - POST
/rest/v1.0/companies/{company_id}/accounting/recurring_journalsCreate a recurring journal - GET
/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Show a recurring journal - PATCH
/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Update a recurring journal - DELETE
/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Delete a recurring journal - POST
/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}/approveApprove a recurring journal
Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/allocation_runsPost an allocation run
Spreads amount (the pool) across job targets by basis with largest-remainder rounding, so the shares always add up to the pool. Posts one balanced JC entry (source allocation_run): a debit per target on its account_id (else target_account_id) tagged with the target project and optional cost code, and a credit to pool_account_id. A negative pool swaps the sides. Job-cost accounts write job cost rows. fixed_pct bases must total 100. Control accounts are refused. The pool account must be an expense, cost of revenue or other expense account and every target account a job cost account (422 otherwise). At or above the approval threshold (settings require_approval_above; null = every amount), or when an active journal_entry approval rule matches, the run is not posted: it is saved as a pending_approval journal entry with its approval route and answered 202. A second person approves it (journal_entries/{id}/approve; the preparer cannot) and a close_period holder posts it (journal_entries/{id}/post). Needs close_period. 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
- datestring (date)required
- memostringrequired
- entity_idinteger | null
- basisanyrequiredOne of: labor_hours, labor_cost, direct_cost, units, fixed_pct.
- amountstringrequiredPool, a non-zero decimal string with at most two places
- pool_account_idintegerrequired
- target_account_idintegerrequired
- auto_reverse_datestring | null (date)
- pool_dimension_value_idsarray | nullUser-defined dimension values on the pool (credit) line.
- targetsobject[]required
- targets[].project_idintegerrequired
- targets[].basisstringrequiredNon-negative decimal string (hours, cost, units or percent)
- targets[].account_idinteger | null
- targets[].cost_code_idinteger | null
- targets[].dimension_value_idsarray | nullUser-defined dimension values on this target's line (e.g. the job's region or division).
Response · 201 · object
- 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
- allocationobject
- allocation.poolstring
- allocation.basis_totalstring
- allocation.sharesobject[]
- pending_approvalbooleanfalse: posted now
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/allocation_runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"date": "2026-11-01",
"memo": "string",
"basis": "labor_hours",
"amount": "0.00",
"pool_account_id": 1,
"target_account_id": 1,
"targets": [
{
"project_id": 1,
"basis": "string"
}
]
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/allocation_runs/{id}/reverseReverse an allocation run
id is the allocation run's journal entry id (journal_entry.id from POST allocation_runs). Posts the mirror entry on date; the reversal writes negating job cost rows. Repeating the call returns the same reversal. Needs post_journal and close_period; at or above the approval threshold the reverser must hold approve_journal and must not have prepared the run. An entry of any other source is 404. Emits accounting.journal_entry.reversed. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reversalobjectrequired
- reversal.datestring (date)required
- 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/allocation_runs/1/reverse" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reversal": {
"date": "2026-11-01"
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/journal_entriesList journal entries
Journal entries newest first. Filter with filters[status], filters[journal], filters[source_type], filters[entity_id], filters[period_id], filters[account_id], filters[project_id], a from/to posting-date range, or search (number or memo). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- filters[status]stringquerydraft, pending_approval, posted, reversed
- filters[journal]stringqueryGJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP
- filters[source_type]stringquerye.g. manual, recurring, reversal
- filters[entity_id]stringqueryEntity ids
- filters[period_id]stringqueryPeriod ids
- filters[account_id]stringqueryEntries with a line on these accounts
- filters[project_id]stringqueryEntries with a line on these projects
- fromstring (date)queryPosting date on or after
- tostring (date)queryPosting date on or before
- searchstringqueryNumber or memo
- pageintegerquery
- per_pageintegerquery
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · 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
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/journal_entries" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entriesCreate a draft journal entry
Saves a manual entry as a draft. Each line has either a debit or a credit (never both), and may carry dimensions (project, cost code, cost type, vendor, customer, department, ...). Drafts may be unbalanced; balance, open period, account and dimension rules are enforced at submit and post. Control accounts (AP, AR, retainage) post only from their subledgers. Needs post_journal. 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
- journal_entryobjectrequired
- journal_entry.entity_idinteger | null
- journal_entry.posting_datestring (date)required
- journal_entry.document_datestring | null (date)
- journal_entry.memostring | null
- journal_entry.auto_reverse_datestring | null (date)
- journal_entry.auto_reversebooleantrue: auto-reverse on the first day of the next period (the accrual default); false clears it. Overrides auto_reverse_date.
- journal_entry.auto_reverse_reasonstring | nullRequired (422 auto_reverse_reason_required) for an auto_reverse_date other than the first day of the next period, unless the preparer holds close_period; recorded in the audit trail.
- journal_entry.intercompanybooleanPost in the IC journal; lines in other entities get generated due-to/due-from lines from each entity intercompany account map (422 when an entity has no map).
- journal_entry.linesobject[]required
- journal_entry.lines[].account_idintegerrequired
- journal_entry.lines[].debitstring | numberNon-negative amount, at most 2 dp; a string is preferred
- journal_entry.lines[].creditstring | numberNon-negative amount, at most 2 dp; a string is preferred
- journal_entry.lines[].memostring | null
- journal_entry.lines[].entity_idinteger | null
- journal_entry.lines[].counterparty_entity_idinteger | nullIntercompany lines: the other entity (must differ from the line's entity).
- journal_entry.lines[].project_idinteger | null
- journal_entry.lines[].cost_code_idinteger | null
- journal_entry.lines[].cost_type_idinteger | null
- journal_entry.lines[].vendor_idinteger | null
- journal_entry.lines[].customer_idinteger | null
- journal_entry.lines[].employee_idinteger | null
- journal_entry.lines[].equipment_idinteger | null
- journal_entry.lines[].department_idinteger | null
- journal_entry.lines[].quantitystring | null
- journal_entry.lines[].unitstring | null
- journal_entry.lines[].billableboolean
- journal_entry.lines[].dimension_value_idsarray | nullCustom dimension values (dimension value ids of this company).
- journal_entry.noncashbooleanASC 230-10-50-3 noncash investing or financing transaction (e.g. equipment bought with a note): left out of the cash flow statement and listed in its noncash schedule. Refused (422) when a line is on a bank or cash account; a reversal inherits it.
- journal_entry.adjustingbooleanPost into the fiscal year's adjusting period (period 13): posting_date must be the fiscal year's last day, the year must have period 13 (POST .../fiscal_years/{id}/adjusting_period), the entry cannot be intercompany, and posting needs close_period. Exempt from later closed periods; in a year-end closed year the post re-closes the year's earnings with a new year_end_close revision in period 13.
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 company409Conflict, 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/journal_entries" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"journal_entry": {
"posting_date": "2026-11-01",
"lines": [
{
"account_id": 1
}
]
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Show a journal entry
Header, lines with account numbers, totals and a balanced flag. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · 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
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/journal_entries/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
PATCH/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Update a draft journal entry
Edits a draft or pending entry; lines replaces every line. Any edit returns a pending entry to draft and clears its approval. Posted entries are immutable. Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- journal_entryobjectrequired
- journal_entry.entity_idinteger | null
- journal_entry.posting_datestring (date)
- journal_entry.document_datestring | null (date)
- journal_entry.memostring | null
- journal_entry.auto_reverse_datestring | null (date)
- journal_entry.auto_reversebooleantrue: auto-reverse on the first day of the next period (the accrual default); false clears it. Overrides auto_reverse_date.
- journal_entry.auto_reverse_reasonstring | nullRequired (422 auto_reverse_reason_required) for an auto_reverse_date other than the first day of the next period, unless the preparer holds close_period; recorded in the audit trail.
- journal_entry.intercompanybooleanPost in the IC journal; lines in other entities get generated due-to/due-from lines from each entity intercompany account map (422 when an entity has no map).
- journal_entry.linesobject[]
- journal_entry.lines[].account_idintegerrequired
- journal_entry.lines[].debitstring | numberNon-negative amount, at most 2 dp; a string is preferred
- journal_entry.lines[].creditstring | numberNon-negative amount, at most 2 dp; a string is preferred
- journal_entry.lines[].memostring | null
- journal_entry.lines[].entity_idinteger | null
- journal_entry.lines[].counterparty_entity_idinteger | nullIntercompany lines: the other entity (must differ from the line's entity).
- journal_entry.lines[].project_idinteger | null
- journal_entry.lines[].cost_code_idinteger | null
- journal_entry.lines[].cost_type_idinteger | null
- journal_entry.lines[].vendor_idinteger | null
- journal_entry.lines[].customer_idinteger | null
- journal_entry.lines[].employee_idinteger | null
- journal_entry.lines[].equipment_idinteger | null
- journal_entry.lines[].department_idinteger | null
- journal_entry.lines[].quantitystring | null
- journal_entry.lines[].unitstring | null
- journal_entry.lines[].billableboolean
- journal_entry.lines[].dimension_value_idsarray | nullCustom dimension values (dimension value ids of this company).
- journal_entry.noncashbooleanASC 230-10-50-3 noncash investing or financing transaction (e.g. equipment bought with a note): left out of the cash flow statement and listed in its noncash schedule. Refused (422) when a line is on a bank or cash account; a reversal inherits it.
- journal_entry.adjustingbooleanPost into the fiscal year's adjusting period (period 13): posting_date must be the fiscal year's last day, the year must have period 13 (POST .../fiscal_years/{id}/adjusting_period), the entry cannot be intercompany, and posting needs close_period. Exempt from later closed periods; in a year-end closed year the post re-closes the year's earnings with a new year_end_close revision in period 13.
Response · 200 · 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 PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/journal_entries/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"journal_entry": {}
}'Accounting / Journal Entries
DELETE/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Delete a draft journal entry
Removes a draft or pending entry. Posted entries cannot be deleted; reverse them. Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/journal_entries/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/approveApprove a journal entry
Records one approval on a pending entry's route. Submit resolves the route from the lowest-priority active journal_entry approval rule matching the entry (amount, entities, projects; N-of-M groups); with none, one approve_journal user approves. Delegates may act within an active delegation. The vote that completes the route stamps approved_by_id, which posting needs at or above the approval threshold. Segregation of duties: a user who prepared or edited the entry can't approve it (403); one vote per user (409 already_approved); a caller not on the current step gets 403 approver_role_required. In small-team SoD mode (settings sod_mode) a maker may approve their own document by sending approve.reason; the event is audited as self_approved and listed by approvals/self_approved. Needs approve_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- approveobject
- approve.reasonstringRequired only to approve your own document in small-team SoD mode (422 self_approval_reason_required); the approval is flagged self_approved.
Response · 200 · 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 company409Conflict (already approved)422Validation 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/journal_entries/1/approve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"approve": {}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsList attachments on a journal entry
Oldest first. Needs view_ledger and the parent's entity scope. 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/journal_entries/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsAttach a file to a journal entry
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs post_journal and the parent'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/journal_entries/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/postPost a journal entry
Posts a draft or pending entry to the ledger and assigns its JE-YYYY-##### number. Entries at or above the settings approval threshold must be approved by a second person first. An entry routed by a journal_entry approval rule must complete that route first, whatever the threshold (422). Writes job cost rows for job-cost lines, an audit record in the same transaction, and emits accounting.journal_entry.posted (ids and links only). Needs post_journal. Requires the accounting:write scope. An unapproved entry is refused (422) at or above the approval threshold, and also below it when an active journal_entry approval rule matches the entry as it stands at post time (a draft never submitted, or edited after a reject, must be submitted and approved first). An approval any of whose voters (each approved route step, or the final approver) has since lost approve_journal (or the entities on the lines) no longer counts: the entry is treated as unapproved and the approval is cleared. Allocation run and year-end close entries also need close_period.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · 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/journal_entries/1/post" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/rejectReject a journal entry (return to the preparer)
Needs approve_journal and every line's entity. A pending_approval entry returns to draft; its approval route is spent, so resubmission routes afresh. The reason is required and audited (action rejected). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rejectobjectrequired
- reject.reasonstringrequired
Response · 200 · 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
401Missing or invalid bearer token403No accounting access, missing permission, or wrong company404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/journal_entries/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reject": {
"reason": "string"
}
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/reverseReverse a posted journal entry
Posts a mirror entry (debits and credits swapped) on date, links the two both ways and marks the original reversed. Repeating the call returns the same reversal. Entries from a subledger document reverse through that document instead. At or above the approval threshold, or when an active journal_entry approval rule matches the original (amount, entities, projects, vendor risk) at any amount, the reverser must hold approve_journal and not be one of its authors (403); under a rule they also fill the rule's route as its approver (403 approver_role_required when no slot fits), and a route needing more than one approval is refused (422): enter the reversing entry as a journal entry and submit it. Needs post_journal. Emits accounting.journal_entry.reversed. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reversalobjectrequired
- reversal.datestring (date)required
- 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/journal_entries/1/reverse" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reversal": {
"date": "2026-11-01"
}
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/submitSubmit a journal entry for approval
Validates the draft in full (balanced per entity, postable active accounts, required dimensions, open period) and moves it to pending_approval. An intercompany entry (journal IC) gets its generated due-to/due-from lines stored now (line source_type intercompany, total updated), so approvers see the entry as it will post; editing the draft drops them and the next submit regenerates them. Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · 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/journal_entries/1/submit" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/forecastUpcoming amortization forecast
Scheduled prepaid amortization and deferred revenue recognition by recognition account and month for months months (1-36, default 12) from from (YYYY-MM, default this month), from the schedules in force; overdue is what is scheduled before from and not yet posted. Noncash (cash_impact none): the payments were cash when the bill or receipt was. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstringquery
- monthsintegerquery
- entity_idintegerquery
Response · 200 · object
- fromstringrequired
- periodsstring[]required
- rowsobject[]required
- rows[].kindanyrequiredOne of: prepaid, deferred_revenue.
- rows[].account_idintegerrequired
- rows[].account_numberstring | nullrequired
- rows[].account_namestring | nullrequired
- rows[].overduestringrequired
- rows[].monthsstring[]required
- totalsobjectrequired
- totals.prepaidstring[]required
- totals.deferred_revenuestring[]required
- cash_impactanyrequired
Errors
401Missing or invalid bearer token403No accounting access, a project-scoped grant or wrong company404Entity outside the grant422Invalid from or months
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/forecast" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/roll_forwardPrepaid and deferred revenue roll-forward
Per balance account, in its normal direction, for from..to: opening (GL) + additions (funding, deferred bill lines, other increases) − amortization (posted runs net of reversals) + adjustments (amount changes, cancellations, voids, other decreases) = closing (GL), with the subledger balance and the difference; foots checks the identity and ties that every account foots and agrees with the subledger. Per schedule: opening, posted amortization and closing from the subledger. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)queryrequired
- tostring (date)queryrequired
- entity_idintegerquery
Response · 200 · object
- fromstring (date)required
- tostring (date)required
- entity_idinteger | nullrequired
- accountsobject[]required
- accounts[].account_idintegerrequired
- accounts[].account_numberstringrequired
- accounts[].account_namestringrequired
- accounts[].normal_balanceanyrequiredOne of: debit, credit.
- accounts[].openingstringrequired
- accounts[].additionsstringrequired
- accounts[].amortizationstringrequired
- accounts[].adjustmentsstringrequired
- accounts[].closingstringrequired
- accounts[].subledgerstringrequired
- accounts[].differencestringrequired
- accounts[].footsbooleanrequired
- totalsobjectrequired
- totals.openingstringrequired
- totals.additionsstringrequired
- totals.amortizationstringrequired
- totals.adjustmentsstringrequired
- totals.closingstringrequired
- totals.subledgerstringrequired
- totals.differencestringrequired
- tiesbooleanrequired
- schedulesobject[]required
- schedules[].idintegerrequired
- schedules[].numberstringrequired
- schedules[].namestringrequired
- schedules[].kindanyrequiredOne of: prepaid, deferred_revenue.
- schedules[].balance_account_idintegerrequired
- schedules[].openingstringrequired
- schedules[].amortization_postedstringrequired
- schedules[].closingstringrequired
Errors
401Missing or invalid bearer token403No accounting access, a project-scoped grant or wrong company404Entity outside the grant422from and to missing or invalid
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/roll_forward" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/runsList amortization runs
Runs of the grant's entities, latest period first (at most 200). Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- period_idintegerquery
- entity_idintegerquery
Response · 200 · object[]
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- statusanyrequiredOne of: prepared, posted, cancelled, superseded, reversed.
- evidence_hashstringrequired
- total_expensestringrequired
- total_revenuestringrequired
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].numberstringrequired
- items[].namestringrequired
- items[].kindanyrequiredOne of: prepaid, deferred_revenue.
- items[].targetstringrequired
- items[].postedstringrequired
- items[].amountstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].schedule_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].memostringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- unchangedbooleanPrepare responses only: true when the prepared run with the same evidence is returned
Errors
401Missing or invalid bearer token403No accounting access, a project-scoped grant, outside the entity scope or wrong company422Invalid query
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/runsPrepare an amortization run
Needs post_journal. Computes, for every schedule of the entity funded by the period end, the cumulative scheduled amortization through the period less what is posted, and stores the lines without posting (201). The same evidence returns the prepared run (200, unchanged true); changed evidence supersedes it. Refused (409) when a posted run covers the period and entity; (422) for a non-calendar-month or closed period, when a later period's run is posted, or when nothing is due. A second user approves it. Audited. Honors Idempotency-Key. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- prepaid_runobjectrequired
- prepaid_run.period_idintegerrequired
- prepaid_run.entity_idintegerrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- statusanyrequiredOne of: prepared, posted, cancelled, superseded, reversed.
- evidence_hashstringrequired
- total_expensestringrequired
- total_revenuestringrequired
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].numberstringrequired
- items[].namestringrequired
- items[].kindanyrequiredOne of: prepaid, deferred_revenue.
- items[].targetstringrequired
- items[].postedstringrequired
- items[].amountstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].schedule_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].memostringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- unchangedbooleanPrepare responses only: true when the prepared run with the same evidence is returned
Errors
401Missing or invalid bearer token403Missing post_journal, a project-scoped grant, outside the entity scope or wrong company404Period or entity not found409Already posted for the period and entity422Invalid body, closed or non-calendar period, a later run posted, or nothing due
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"prepaid_run": {
"period_id": 1,
"entity_id": 1
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}Show an amortization run
The run with its items and lines. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- statusanyrequiredOne of: prepared, posted, cancelled, superseded, reversed.
- evidence_hashstringrequired
- total_expensestringrequired
- total_revenuestringrequired
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].numberstringrequired
- items[].namestringrequired
- items[].kindanyrequiredOne of: prepaid, deferred_revenue.
- items[].targetstringrequired
- items[].postedstringrequired
- items[].amountstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].schedule_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].memostringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- unchangedbooleanPrepare responses only: true when the prepared run with the same evidence is returned
Errors
401Missing or invalid bearer token403No accounting access, a project-scoped grant or wrong company404Not found or outside the entity scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/decisionApprove and post, or cancel, a prepared run
approve needs approve_journal and is refused (403) for the preparer; the run is recomputed and refused (409) if schedules or postings moved; the entry posts on the period end with both users recorded. cancel needs post_journal and a reason. A repeat returns the run. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionanyrequiredOne of: approve, cancel.
- decision.reasonstring | null
Response · 200 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- statusanyrequiredOne of: prepared, posted, cancelled, superseded, reversed.
- evidence_hashstringrequired
- total_expensestringrequired
- total_revenuestringrequired
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].numberstringrequired
- items[].namestringrequired
- items[].kindanyrequiredOne of: prepaid, deferred_revenue.
- items[].targetstringrequired
- items[].postedstringrequired
- items[].amountstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].schedule_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].memostringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- unchangedbooleanPrepare responses only: true when the prepared run with the same evidence is returned
Errors
401Missing or invalid bearer token403Missing approve_journal (post_journal to cancel), the preparer approving, a project-scoped grant or wrong company404Not found or outside the entity scope409Not prepared any more, or the evidence moved422Invalid body or a closed period
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/runs/1/decision" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"decision": {
"action": "approve"
}
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/reverseReverse a posted run
Needs approve_journal. Reverses the run's entry on date with a reason; the period and entity can then be run again, and the next run catches the schedules up. A repeat with the same date and reason returns the run. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reversalobjectrequired
- reversal.datestring (date)required
- reversal.reasonstringrequired
Response · 201 · object
- idintegerrequired
- period_idintegerrequired
- entity_idintegerrequired
- statusanyrequiredOne of: prepared, posted, cancelled, superseded, reversed.
- evidence_hashstringrequired
- total_expensestringrequired
- total_revenuestringrequired
- itemsobject[]required
- items[].schedule_idintegerrequired
- items[].numberstringrequired
- items[].namestringrequired
- items[].kindanyrequiredOne of: prepaid, deferred_revenue.
- items[].targetstringrequired
- items[].postedstringrequired
- items[].amountstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].schedule_idintegerrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- lines[].dimension_value_idsarray | nullrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].memostringrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- approved_by_idinteger | nullrequired
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- unchangedbooleanPrepare responses only: true when the prepared run with the same evidence is returned
Errors
401Missing or invalid bearer token403Missing approve_journal, a project-scoped grant or wrong company404Not found or outside the entity scope409Not posted, or reversed differently422Invalid body or a closed period
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/runs/1/reverse" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reversal": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesList prepaid and deferred revenue schedules
Schedules of the grant's entities, newest start first (at most 500), with posted amortization and the unamortized balance as of as_of (default today in the company's time zone). Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- kindanyqueryOne of: prepaid, deferred_revenue.
- statusanyqueryOne of: active, cancelled, voided.
- entity_idintegerquery
- as_ofstring (date)query
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- namestringrequired
- kindanyrequiredOne of: prepaid, deferred_revenue.
- categoryanyrequiredOne of: insurance, bond, rent, software, maintenance_contract, other.
- entity_idintegerrequired
- vendor_idinteger | nullrequired
- customer_idinteger | nullrequired
- balance_account_idintegerrequired
- recognition_account_idintegerrequired
- department_idinteger | nullrequired
- dimension_value_idsinteger[]required
- allocationsobject[]required
- allocations[].project_idinteger | nullrequired
- allocations[].cost_code_idinteger | nullrequired
- allocations[].cost_type_idinteger | nullrequired
- allocations[].percentstringrequired
- methodanyrequiredOne of: daily, monthly, custom.
- start_datestring (date)required
- original_amountstringrequired
- original_end_datestring (date)required
- amountstringrequiredThe amount of the version in force
- end_datestring (date)requiredThe last day of coverage of the version in force
- funding_modeanyrequiredOne of: entry, existing, ap_bill_line.
- funding_datestring (date)required
- funding_offset_account_idinteger | nullrequired
- funding_entry_idinteger | nullrequired
- ap_bill_idinteger | nullrequired
- ap_bill_line_idinteger | nullrequired
- statusanyrequiredOne of: active, cancelled, voided.
- current_versionintegerrequired
- cancelled_onstring | null (date)required
- voided_onstring | null (date)required
- void_reasonstring | nullrequired
- void_entry_idinteger | nullrequired
- memostring | nullrequired
- as_ofstring (date)required
- amortization_postedstringrequired
- scheduled_through_as_ofstringrequired
- unposted_through_as_ofstringrequired
- balancestringrequiredUnamortized balance the subledger expects on as_of (normal direction)
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- schedule_versionintegerDetail responses: the version whose months `schedule` shows
- scheduleobject[]
- schedule[].periodstringrequired
- schedule[].amountstringrequired
- versionsobject[]
- versions[].versionintegerrequired
- versions[].kindanyrequiredOne of: original, term_change, amount_change, cancel.
- versions[].policyanyrequiredOne of: prospective, catch_up, null.
- versions[].effective_datestring (date)required
- versions[].amountstringrequired
- versions[].end_datestring (date)required
- versions[].recognized_beforestringrequired
- versions[].balance_deltastringrequired
- versions[].refund_amountstringrequired
- versions[].refund_account_idinteger | nullrequired
- versions[].offset_account_idinteger | nullrequired
- versions[].entry_idinteger | nullrequired
- versions[].reasonstringrequired
- versions[].created_by_idintegerrequired
- versions[].created_atstring (date-time)required
- versions[].monthsobject[]required
Errors
401Missing or invalid bearer token403No accounting access, a project-scoped grant, outside the entity scope or wrong company422Invalid query
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/schedules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesCreate a schedule, or defer an AP bill line
Needs post_journal. Manual: funding_mode entry (default) posts Dr balance / Cr funding_offset_account_id (Dr offset / Cr balance for deferred revenue) on funding_date (default the start date); existing records a balance already on the account (an opening balance). From a posted AP bill line (ap_bill_line_id): a line coded to the prepaid account funds the schedule itself (deferred in full); a line coded to an expense is reclassified to the prepaid account on funding_date (default the bill's posting date). Accounts default by category (1330 insurance and bonds, 1340 others; 6300, 5520, 6200, 6240, 6250 expense; 4150 revenue for deferred revenue). The funding date must be in a period open for the entity. preview: true returns the months and the funding lines and writes nothing (200). Audited. Honors Idempotency-Key. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- scheduleobjectrequired
- schedule.namestringrequired
- schedule.kindanyrequiredOne of: prepaid, deferred_revenue.
- schedule.categoryanyrequiredOne of: insurance, bond, rent, software, maintenance_contract, other.
- schedule.entity_idinteger | null
- schedule.vendor_idinteger | null
- schedule.customer_idinteger | null
- schedule.amountstringRequired unless deferring a bill line (default: the line with its use tax)
- schedule.start_datestring (date)required
- schedule.end_datestring (date)required
- schedule.methodanyrequiredOne of: daily, monthly, custom.
- schedule.percentsobject[]
- schedule.percents[].periodstringrequired
- schedule.percents[].percentstringrequired
- schedule.balance_account_idinteger | null
- schedule.recognition_account_idinteger | null
- schedule.department_idinteger | null
- schedule.dimension_value_idsinteger[]
- schedule.allocationsobject[]
- schedule.allocations[].project_idinteger | null
- schedule.allocations[].cost_code_idinteger | null
- schedule.allocations[].cost_type_idinteger | null
- schedule.allocations[].percentstringrequired
- schedule.funding_modeanyOne of: entry, existing.
- schedule.funding_datestring (date)
- schedule.funding_offset_account_idinteger | null
- schedule.ap_bill_line_idinteger | null
- schedule.memostring
- schedule.previewboolean
Response · 200 · object
- previewanyrequired
- kindanyrequiredOne of: prepaid, deferred_revenue.
- entity_idintegerrequired
- amountstringrequired
- balance_account_idintegerrequired
- recognition_account_idintegerrequired
- funding_modeanyrequiredOne of: entry, existing, ap_bill_line.
- funding_datestring (date)required
- funding_linesobject[]required
- funding_lines[].account_idintegerrequired
- funding_lines[].debitstringrequired
- funding_lines[].creditstringrequired
- funding_lines[].project_idinteger | nullrequired
- funding_lines[].cost_code_idinteger | nullrequired
- funding_lines[].cost_type_idinteger | nullrequired
- funding_lines[].memostring | nullrequired
- scheduleobject[]required
- schedule[].periodstringrequired
- schedule[].amountstringrequired
Errors
401Missing or invalid bearer token403Missing post_journal, a project-scoped grant, outside the entity scope or wrong company404Bill line not found409The bill line is already deferred422Invalid body, accounts, allocation or terms, or a closed period
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/schedules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"schedule": {
"name": "string",
"kind": "prepaid",
"category": "insurance",
"start_date": "2026-11-01",
"end_date": "2026-11-01",
"method": "daily"
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}Show a schedule with its versions
The schedule, its months in force (or of version, 0 = original) and every version. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- versionintegerquery
- as_ofstring (date)query
Response · 200 · object
- idintegerrequired
- numberstringrequired
- namestringrequired
- kindanyrequiredOne of: prepaid, deferred_revenue.
- categoryanyrequiredOne of: insurance, bond, rent, software, maintenance_contract, other.
- entity_idintegerrequired
- vendor_idinteger | nullrequired
- customer_idinteger | nullrequired
- balance_account_idintegerrequired
- recognition_account_idintegerrequired
- department_idinteger | nullrequired
- dimension_value_idsinteger[]required
- allocationsobject[]required
- allocations[].project_idinteger | nullrequired
- allocations[].cost_code_idinteger | nullrequired
- allocations[].cost_type_idinteger | nullrequired
- allocations[].percentstringrequired
- methodanyrequiredOne of: daily, monthly, custom.
- start_datestring (date)required
- original_amountstringrequired
- original_end_datestring (date)required
- amountstringrequiredThe amount of the version in force
- end_datestring (date)requiredThe last day of coverage of the version in force
- funding_modeanyrequiredOne of: entry, existing, ap_bill_line.
- funding_datestring (date)required
- funding_offset_account_idinteger | nullrequired
- funding_entry_idinteger | nullrequired
- ap_bill_idinteger | nullrequired
- ap_bill_line_idinteger | nullrequired
- statusanyrequiredOne of: active, cancelled, voided.
- current_versionintegerrequired
- cancelled_onstring | null (date)required
- voided_onstring | null (date)required
- void_reasonstring | nullrequired
- void_entry_idinteger | nullrequired
- memostring | nullrequired
- as_ofstring (date)required
- amortization_postedstringrequired
- scheduled_through_as_ofstringrequired
- unposted_through_as_ofstringrequired
- balancestringrequiredUnamortized balance the subledger expects on as_of (normal direction)
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- schedule_versionintegerDetail responses: the version whose months `schedule` shows
- scheduleobject[]
- schedule[].periodstringrequired
- schedule[].amountstringrequired
- versionsobject[]
- versions[].versionintegerrequired
- versions[].kindanyrequiredOne of: original, term_change, amount_change, cancel.
- versions[].policyanyrequiredOne of: prospective, catch_up, null.
- versions[].effective_datestring (date)required
- versions[].amountstringrequired
- versions[].end_datestring (date)required
- versions[].recognized_beforestringrequired
- versions[].balance_deltastringrequired
- versions[].refund_amountstringrequired
- versions[].refund_account_idinteger | nullrequired
- versions[].offset_account_idinteger | nullrequired
- versions[].entry_idinteger | nullrequired
- versions[].reasonstringrequired
- versions[].created_by_idintegerrequired
- versions[].created_atstring (date-time)required
- versions[].monthsobject[]required
Errors
400Unknown version401Missing or invalid bearer token403No accounting access, a project-scoped grant or wrong company404Not found or outside the entity scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/schedules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/modificationsModify or cancel a schedule
Needs post_journal. Appends a version that keeps every month before the effective month. term_change (new_end_date) and amount_change (new_amount and offset_account_id; optional new_end_date) are prospective by default (the balance left at the effective date spreads over the revised remaining window) or catch_up (the revised terms from the start, the difference in the effective month). cancel stops amortization at the effective date and posts the unamortized balance: refund_amount to refund_account_id, the rest written off to the recognition account. Monthly and custom schedules change on the first of a month. Refused for a cancelled or voided schedule (409), when amortization is posted on or after the effective date (409; reverse that run), and for a closed period (422). preview: true writes nothing (200). Audited. Honors Idempotency-Key. 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
- modificationobjectrequired
- modification.kindanyrequiredOne of: term_change, amount_change, cancel.
- modification.effective_datestring (date)required
- modification.reasonstringrequired
- modification.policyanyOne of: prospective, catch_up.
- modification.new_end_datestring (date)
- modification.new_amountstring
- modification.percentsobject[]
- modification.percents[].periodstringrequired
- modification.percents[].percentstringrequired
- modification.offset_account_idinteger | null
- modification.refund_amountstring
- modification.refund_account_idinteger | null
- modification.previewboolean
Response · 200 · object
- previewanyrequired
- versionintegerrequired
- amountstringrequired
- end_datestring (date)required
- recognized_beforestringrequired
- balance_deltastringrequired
- removedstringrequired
- refund_amountstringrequired
- write_offstringrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].debitstringrequired
- lines[].creditstringrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].memostring | nullrequired
- scheduleobject[]required
- schedule[].periodstringrequired
- schedule[].amountstringrequired
Errors
401Missing or invalid bearer token403Missing post_journal, a project-scoped grant or wrong company404Not found or outside the entity scope409Cancelled or voided, or amortization posted on or after the effective date422Invalid body or terms, or a closed period
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/schedules/1/modifications" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"modification": {
"kind": "term_change",
"effective_date": "2026-11-01",
"reason": "string"
}
}'Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/voidVoid a schedule entered by mistake
Needs post_journal. Reverses the funding entry (if any) on date. Refused (409) once amortization is posted (reverse the runs first) or after a modification (cancel instead). A repeat with the same date and reason returns the schedule. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- namestringrequired
- kindanyrequiredOne of: prepaid, deferred_revenue.
- categoryanyrequiredOne of: insurance, bond, rent, software, maintenance_contract, other.
- entity_idintegerrequired
- vendor_idinteger | nullrequired
- customer_idinteger | nullrequired
- balance_account_idintegerrequired
- recognition_account_idintegerrequired
- department_idinteger | nullrequired
- dimension_value_idsinteger[]required
- allocationsobject[]required
- allocations[].project_idinteger | nullrequired
- allocations[].cost_code_idinteger | nullrequired
- allocations[].cost_type_idinteger | nullrequired
- allocations[].percentstringrequired
- methodanyrequiredOne of: daily, monthly, custom.
- start_datestring (date)required
- original_amountstringrequired
- original_end_datestring (date)required
- amountstringrequiredThe amount of the version in force
- end_datestring (date)requiredThe last day of coverage of the version in force
- funding_modeanyrequiredOne of: entry, existing, ap_bill_line.
- funding_datestring (date)required
- funding_offset_account_idinteger | nullrequired
- funding_entry_idinteger | nullrequired
- ap_bill_idinteger | nullrequired
- ap_bill_line_idinteger | nullrequired
- statusanyrequiredOne of: active, cancelled, voided.
- current_versionintegerrequired
- cancelled_onstring | null (date)required
- voided_onstring | null (date)required
- void_reasonstring | nullrequired
- void_entry_idinteger | nullrequired
- memostring | nullrequired
- as_ofstring (date)required
- amortization_postedstringrequired
- scheduled_through_as_ofstringrequired
- unposted_through_as_ofstringrequired
- balancestringrequiredUnamortized balance the subledger expects on as_of (normal direction)
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- schedule_versionintegerDetail responses: the version whose months `schedule` shows
- scheduleobject[]
- schedule[].periodstringrequired
- schedule[].amountstringrequired
- versionsobject[]
- versions[].versionintegerrequired
- versions[].kindanyrequiredOne of: original, term_change, amount_change, cancel.
- versions[].policyanyrequiredOne of: prospective, catch_up, null.
- versions[].effective_datestring (date)required
- versions[].amountstringrequired
- versions[].end_datestring (date)required
- versions[].recognized_beforestringrequired
- versions[].balance_deltastringrequired
- versions[].refund_amountstringrequired
- versions[].refund_account_idinteger | nullrequired
- versions[].offset_account_idinteger | nullrequired
- versions[].entry_idinteger | nullrequired
- versions[].reasonstringrequired
- versions[].created_by_idintegerrequired
- versions[].created_atstring (date-time)required
- versions[].monthsobject[]required
Errors
401Missing or invalid bearer token403Missing post_journal, a project-scoped grant or wrong company404Not found or outside the entity scope409Amortization posted, modified, or voided differently422Invalid body or a closed period
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/prepaids/schedules/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/recurring_journalsList recurring journals
Recurring journal templates in the caller's entities, active first by next run date. Paginated (page/per_page; Total and Link headers). Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- namestringrequired
- memostring | nullrequired
- journalstringrequired
- frequencyanyrequiredOne of: weekly, monthly, quarterly, yearly.
- intervalintegerrequired
- day_of_monthinteger | nullrequired
- start_datestring (date)required
- end_datestring | null (date)required
- next_run_datestring (date)required
- last_run_datestring | null (date)required
- reverse_after_daysinteger | nullrequired
- auto_postbooleanrequired
- is_activebooleanrequired
- created_by_idintegerrequired
- approved_by_idinteger | nullrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- linesobject[]required
- lines[].dimension_value_idsarray | nullUser-defined dimension values carried onto each generated entry's line.
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- last_errorstring | nullrequiredLast scheduler refusal or skip: `blocked_soft_close: ...` (an auto-post occurrence waits in a soft-closed period), `skipped_closed: ...` (occurrences in hard-closed periods were skipped) or the failure message; null after a clean run.
- last_error_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/recurring_journals" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/recurring_journalsCreate a recurring journal
Saves a template that generates a journal entry on each run date (daily scheduler, as of today in the company time zone). Lines must balance. Starts unapproved; an auto_post template posts only after a second person approves it, and generates drafts until then. Needs post_journal. 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
- recurring_journalobjectrequired
- recurring_journal.entity_idinteger | null
- recurring_journal.namestringrequired
- recurring_journal.memostring | null
- recurring_journal.frequencyanyOne of: weekly, monthly, quarterly, yearly.
- recurring_journal.intervalinteger
- recurring_journal.day_of_monthinteger | null
- recurring_journal.start_datestring (date)required
- recurring_journal.end_datestring | null (date)
- recurring_journal.reverse_after_daysinteger | null
- recurring_journal.auto_postboolean
- recurring_journal.is_activeboolean
- recurring_journal.linesobject[]required
- recurring_journal.lines[].account_idintegerrequired
- recurring_journal.lines[].debitstring | number
- recurring_journal.lines[].creditstring | number
- recurring_journal.lines[].memostring | null
- recurring_journal.lines[].project_idinteger | null
- recurring_journal.lines[].cost_code_idinteger | null
- recurring_journal.lines[].cost_type_idinteger | null
- recurring_journal.lines[].department_idinteger | null
- recurring_journal.lines[].dimension_value_idsarray | nullCustom dimension values (dimension value ids of this company), copied onto each generated entry's line.
Response · 201 · object
- idintegerrequired
- entity_idintegerrequired
- namestringrequired
- memostring | nullrequired
- journalstringrequired
- frequencyanyrequiredOne of: weekly, monthly, quarterly, yearly.
- intervalintegerrequired
- day_of_monthinteger | nullrequired
- start_datestring (date)required
- end_datestring | null (date)required
- next_run_datestring (date)required
- last_run_datestring | null (date)required
- reverse_after_daysinteger | nullrequired
- auto_postbooleanrequired
- is_activebooleanrequired
- created_by_idintegerrequired
- approved_by_idinteger | nullrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- linesobject[]required
- lines[].dimension_value_idsarray | nullUser-defined dimension values carried onto each generated entry's line.
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- last_errorstring | nullrequiredLast scheduler refusal or skip: `blocked_soft_close: ...` (an auto-post occurrence waits in a soft-closed period), `skipped_closed: ...` (occurrences in hard-closed periods were skipped) or the failure message; null after a clean run.
- last_error_atstring | null (date-time)required
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/recurring_journals" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"recurring_journal": {
"name": "string",
"start_date": "2026-11-01",
"lines": [
{
"account_id": 1
}
]
}
}'Accounting / Journal Entries
GET/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Show a recurring journal
One template with its lines. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- namestringrequired
- memostring | nullrequired
- journalstringrequired
- frequencyanyrequiredOne of: weekly, monthly, quarterly, yearly.
- intervalintegerrequired
- day_of_monthinteger | nullrequired
- start_datestring (date)required
- end_datestring | null (date)required
- next_run_datestring (date)required
- last_run_datestring | null (date)required
- reverse_after_daysinteger | nullrequired
- auto_postbooleanrequired
- is_activebooleanrequired
- created_by_idintegerrequired
- approved_by_idinteger | nullrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- linesobject[]required
- lines[].dimension_value_idsarray | nullUser-defined dimension values carried onto each generated entry's line.
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- last_errorstring | nullrequiredLast scheduler refusal or skip: `blocked_soft_close: ...` (an auto-post occurrence waits in a soft-closed period), `skipped_closed: ...` (occurrences in hard-closed periods were skipped) or the failure message; null after a clean run.
- last_error_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/recurring_journals/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
PATCH/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Update a recurring journal
Edits a template. Any edit clears its approval, so an auto_post template needs a second-person re-approval before it posts again. Sending lines replaces them. The start date is fixed once the template has run. Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- recurring_journalobjectrequired
- recurring_journal.entity_idinteger | null
- recurring_journal.namestring
- recurring_journal.memostring | null
- recurring_journal.frequencyanyOne of: weekly, monthly, quarterly, yearly.
- recurring_journal.intervalinteger
- recurring_journal.day_of_monthinteger | null
- recurring_journal.start_datestring (date)
- recurring_journal.end_datestring | null (date)
- recurring_journal.reverse_after_daysinteger | null
- recurring_journal.auto_postboolean
- recurring_journal.is_activeboolean
- recurring_journal.linesobject[]
- recurring_journal.lines[].account_idintegerrequired
- recurring_journal.lines[].debitstring | number
- recurring_journal.lines[].creditstring | number
- recurring_journal.lines[].memostring | null
- recurring_journal.lines[].project_idinteger | null
- recurring_journal.lines[].cost_code_idinteger | null
- recurring_journal.lines[].cost_type_idinteger | null
- recurring_journal.lines[].department_idinteger | null
- recurring_journal.lines[].dimension_value_idsarray | nullCustom dimension values (dimension value ids of this company), copied onto each generated entry's line.
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- namestringrequired
- memostring | nullrequired
- journalstringrequired
- frequencyanyrequiredOne of: weekly, monthly, quarterly, yearly.
- intervalintegerrequired
- day_of_monthinteger | nullrequired
- start_datestring (date)required
- end_datestring | null (date)required
- next_run_datestring (date)required
- last_run_datestring | null (date)required
- reverse_after_daysinteger | nullrequired
- auto_postbooleanrequired
- is_activebooleanrequired
- created_by_idintegerrequired
- approved_by_idinteger | nullrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- linesobject[]required
- lines[].dimension_value_idsarray | nullUser-defined dimension values carried onto each generated entry's line.
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- last_errorstring | nullrequiredLast scheduler refusal or skip: `blocked_soft_close: ...` (an auto-post occurrence waits in a soft-closed period), `skipped_closed: ...` (occurrences in hard-closed periods were skipped) or the failure message; null after a clean run.
- last_error_atstring | null (date-time)required
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 PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/recurring_journals/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"recurring_journal": {}
}'Accounting / Journal Entries
DELETE/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Delete a recurring journal
Removes a template that never generated an entry; otherwise deactivate it (is_active false). Needs post_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/recurring_journals/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Journal Entries
POST/rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}/approveApprove a recurring journal
Records a second-person approval. The creator and every editor of the template can never approve it (403). Needs approve_journal. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- namestringrequired
- memostring | nullrequired
- journalstringrequired
- frequencyanyrequiredOne of: weekly, monthly, quarterly, yearly.
- intervalintegerrequired
- day_of_monthinteger | nullrequired
- start_datestring (date)required
- end_datestring | null (date)required
- next_run_datestring (date)required
- last_run_datestring | null (date)required
- reverse_after_daysinteger | nullrequired
- auto_postbooleanrequired
- is_activebooleanrequired
- created_by_idintegerrequired
- approved_by_idinteger | nullrequired
- total_amountstringrequiredDecimal amount as a string, 2 dp
- linesobject[]required
- lines[].dimension_value_idsarray | nullUser-defined dimension values carried onto each generated entry's line.
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].debitstringrequiredDecimal amount as a string, 2 dp
- lines[].creditstringrequiredDecimal amount as a string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].department_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- last_errorstring | nullrequiredLast scheduler refusal or skip: `blocked_soft_close: ...` (an auto-post occurrence waits in a soft-closed period), `skipped_closed: ...` (occurrences in hard-closed periods were skipped) or the failure message; null after a clean run.
- last_error_atstring | null (date-time)required
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/recurring_journals/1/approve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"