Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · Books and controls

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.

32 operationsCompany moduleAll Accounting apps →
  1. POST /rest/v1.0/companies/{company_id}/accounting/allocation_runsPost an allocation run
  2. POST /rest/v1.0/companies/{company_id}/accounting/allocation_runs/{id}/reverseReverse an allocation run
  3. GET /rest/v1.0/companies/{company_id}/accounting/journal_entriesList journal entries
  4. POST /rest/v1.0/companies/{company_id}/accounting/journal_entriesCreate a draft journal entry
  5. GET /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Show a journal entry
  6. PATCH /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Update a draft journal entry
  7. DELETE /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}Delete a draft journal entry
  8. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/approveApprove a journal entry
  9. GET /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsList attachments on a journal entry
  10. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/attachmentsAttach a file to a journal entry
  11. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/postPost a journal entry
  12. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/rejectReject a journal entry (return to the preparer)
  13. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/reverseReverse a posted journal entry
  14. POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/submitSubmit a journal entry for approval
  15. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/forecastUpcoming amortization forecast
  16. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/roll_forwardPrepaid and deferred revenue roll-forward
  17. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/runsList amortization runs
  18. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/runsPrepare an amortization run
  19. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}Show an amortization run
  20. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/decisionApprove and post, or cancel, a prepared run
  21. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/runs/{id}/reverseReverse a posted run
  22. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesList prepaid and deferred revenue schedules
  23. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/schedulesCreate a schedule, or defer an AP bill line
  24. GET /rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}Show a schedule with its versions
  25. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/modificationsModify or cancel a schedule
  26. POST /rest/v1.0/companies/{company_id}/accounting/prepaids/schedules/{id}/voidVoid a schedule entered by mistake
  27. GET /rest/v1.0/companies/{company_id}/accounting/recurring_journalsList recurring journals
  28. POST /rest/v1.0/companies/{company_id}/accounting/recurring_journalsCreate a recurring journal
  29. GET /rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Show a recurring journal
  30. PATCH /rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Update a recurring journal
  31. DELETE /rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}Delete a recurring journal
  32. 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_runs

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

v1.0Implemented

Parameters

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

Request body

  • date
    string (date)required
  • memo
    stringrequired
  • entity_id
    integer | null
  • basis
    anyrequired
    One of: labor_hours, labor_cost, direct_cost, units, fixed_pct.
  • amount
    stringrequired
    Pool, a non-zero decimal string with at most two places
  • pool_account_id
    integerrequired
  • target_account_id
    integerrequired
  • auto_reverse_date
    string | null (date)
  • pool_dimension_value_ids
    array | null
    User-defined dimension values on the pool (credit) line.
  • targets
    object[]required
  • targets[].project_id
    integerrequired
  • targets[].basis
    stringrequired
    Non-negative decimal string (hours, cost, units or percent)
  • targets[].account_id
    integer | null
  • targets[].cost_code_id
    integer | null
  • targets[].dimension_value_ids
    array | null
    User-defined dimension values on this target's line (e.g. the job's region or division).

Response · 201 · object

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

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reversal
    objectrequired
  • reversal.date
    string (date)required
  • reversal.reason
    string | null

Response · 201 · object

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

Errors

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

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • filters[status]
    stringquery
    draft, pending_approval, posted, reversed
  • filters[journal]
    stringquery
    GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP
  • filters[source_type]
    stringquery
    e.g. manual, recurring, reversal
  • filters[entity_id]
    stringquery
    Entity ids
  • filters[period_id]
    stringquery
    Period ids
  • filters[account_id]
    stringquery
    Entries with a line on these accounts
  • filters[project_id]
    stringquery
    Entries with a line on these projects
  • from
    string (date)query
    Posting date on or after
  • to
    string (date)query
    Posting date on or before
  • search
    stringquery
    Number or memo
  • page
    integerquery
  • per_page
    integerquery
  • updated_since
    string (date-time)query
    Delta 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.
  • cursor
    stringquery
    Opaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.

Response · 200 · object[]

  • id
    integerrequired
  • number
    string | nullrequired
    JE-YYYY-#####, assigned on posting
  • status
    anyrequired
    One of: draft, pending_approval, posted, reversed.
  • journal
    anyrequired
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • entity_id
    integerrequired
  • period_id
    integerrequired
  • posting_date
    string (date)required
  • document_date
    string | null (date)required
  • memo
    string | nullrequired
  • source_type
    stringrequired
  • source_id
    integer | nullrequired
  • source_revision
    integerrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • currency
    stringrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • posted_by_id
    integer | nullrequired
  • posted_at
    string | null (date-time)required
  • reverses_id
    integer | nullrequired
  • reversed_by_id
    integer | nullrequired
  • auto_reverse_date
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

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

Example request

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

Accounting / Journal Entries

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

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

v1.0Implemented

Parameters

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

Request body

  • journal_entry
    objectrequired
  • journal_entry.entity_id
    integer | null
  • journal_entry.posting_date
    string (date)required
  • journal_entry.document_date
    string | null (date)
  • journal_entry.memo
    string | null
  • journal_entry.auto_reverse_date
    string | null (date)
  • journal_entry.auto_reverse
    boolean
    true: auto-reverse on the first day of the next period (the accrual default); false clears it. Overrides auto_reverse_date.
  • journal_entry.auto_reverse_reason
    string | null
    Required (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.intercompany
    boolean
    Post 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.lines
    object[]required
  • journal_entry.lines[].account_id
    integerrequired
  • journal_entry.lines[].debit
    string | number
    Non-negative amount, at most 2 dp; a string is preferred
  • journal_entry.lines[].credit
    string | number
    Non-negative amount, at most 2 dp; a string is preferred
  • journal_entry.lines[].memo
    string | null
  • journal_entry.lines[].entity_id
    integer | null
  • journal_entry.lines[].counterparty_entity_id
    integer | null
    Intercompany lines: the other entity (must differ from the line's entity).
  • journal_entry.lines[].project_id
    integer | null
  • journal_entry.lines[].cost_code_id
    integer | null
  • journal_entry.lines[].cost_type_id
    integer | null
  • journal_entry.lines[].vendor_id
    integer | null
  • journal_entry.lines[].customer_id
    integer | null
  • journal_entry.lines[].employee_id
    integer | null
  • journal_entry.lines[].equipment_id
    integer | null
  • journal_entry.lines[].department_id
    integer | null
  • journal_entry.lines[].quantity
    string | null
  • journal_entry.lines[].unit
    string | null
  • journal_entry.lines[].billable
    boolean
  • journal_entry.lines[].dimension_value_ids
    array | null
    Custom dimension values (dimension value ids of this company).
  • journal_entry.noncash
    boolean
    ASC 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.adjusting
    boolean
    Post 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

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

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

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

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Request body

  • journal_entry
    objectrequired
  • journal_entry.entity_id
    integer | null
  • journal_entry.posting_date
    string (date)
  • journal_entry.document_date
    string | null (date)
  • journal_entry.memo
    string | null
  • journal_entry.auto_reverse_date
    string | null (date)
  • journal_entry.auto_reverse
    boolean
    true: auto-reverse on the first day of the next period (the accrual default); false clears it. Overrides auto_reverse_date.
  • journal_entry.auto_reverse_reason
    string | null
    Required (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.intercompany
    boolean
    Post 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.lines
    object[]
  • journal_entry.lines[].account_id
    integerrequired
  • journal_entry.lines[].debit
    string | number
    Non-negative amount, at most 2 dp; a string is preferred
  • journal_entry.lines[].credit
    string | number
    Non-negative amount, at most 2 dp; a string is preferred
  • journal_entry.lines[].memo
    string | null
  • journal_entry.lines[].entity_id
    integer | null
  • journal_entry.lines[].counterparty_entity_id
    integer | null
    Intercompany lines: the other entity (must differ from the line's entity).
  • journal_entry.lines[].project_id
    integer | null
  • journal_entry.lines[].cost_code_id
    integer | null
  • journal_entry.lines[].cost_type_id
    integer | null
  • journal_entry.lines[].vendor_id
    integer | null
  • journal_entry.lines[].customer_id
    integer | null
  • journal_entry.lines[].employee_id
    integer | null
  • journal_entry.lines[].equipment_id
    integer | null
  • journal_entry.lines[].department_id
    integer | null
  • journal_entry.lines[].quantity
    string | null
  • journal_entry.lines[].unit
    string | null
  • journal_entry.lines[].billable
    boolean
  • journal_entry.lines[].dimension_value_ids
    array | null
    Custom dimension values (dimension value ids of this company).
  • journal_entry.noncash
    boolean
    ASC 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.adjusting
    boolean
    Post 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

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

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed (field errors) or the ledger refused the change (message list)

Example request

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

Accounting / Journal Entries

POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/approve

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

v1.0Implemented

Parameters

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

Request body

  • approve
    object
  • approve.reason
    string
    Required 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

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

Errors

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

Example request

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

List attachments on a journal entry

Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

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

Errors

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

Example request

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

Accounting / Journal Entries

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

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

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

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

Errors

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

Example request

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

Accounting / Journal Entries

POST /rest/v1.0/companies/{company_id}/accounting/journal_entries/{id}/reject

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

v1.0Implemented

Parameters

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

Request body

  • reject
    objectrequired
  • reject.reason
    stringrequired

Response · 200 · object

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

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reversal
    objectrequired
  • reversal.date
    string (date)required
  • reversal.reason
    string | null

Response · 201 · object

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

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

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

Errors

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

Example request

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

Accounting / Journal Entries

GET /rest/v1.0/companies/{company_id}/accounting/prepaids/forecast

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • from
    stringrequired
  • periods
    string[]required
  • rows
    object[]required
  • rows[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • rows[].account_id
    integerrequired
  • rows[].account_number
    string | nullrequired
  • rows[].account_name
    string | nullrequired
  • rows[].overdue
    stringrequired
  • rows[].months
    string[]required
  • totals
    objectrequired
  • totals.prepaid
    string[]required
  • totals.deferred_revenue
    string[]required
  • cash_impact
    anyrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant or wrong company
  • 404Entity outside the grant
  • 422Invalid from or months

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • from
    string (date)queryrequired
  • to
    string (date)queryrequired
  • entity_id
    integerquery

Response · 200 · object

  • from
    string (date)required
  • to
    string (date)required
  • entity_id
    integer | nullrequired
  • accounts
    object[]required
  • accounts[].account_id
    integerrequired
  • accounts[].account_number
    stringrequired
  • accounts[].account_name
    stringrequired
  • accounts[].normal_balance
    anyrequired
    One of: debit, credit.
  • accounts[].opening
    stringrequired
  • accounts[].additions
    stringrequired
  • accounts[].amortization
    stringrequired
  • accounts[].adjustments
    stringrequired
  • accounts[].closing
    stringrequired
  • accounts[].subledger
    stringrequired
  • accounts[].difference
    stringrequired
  • accounts[].foots
    booleanrequired
  • totals
    objectrequired
  • totals.opening
    stringrequired
  • totals.additions
    stringrequired
  • totals.amortization
    stringrequired
  • totals.adjustments
    stringrequired
  • totals.closing
    stringrequired
  • totals.subledger
    stringrequired
  • totals.difference
    stringrequired
  • ties
    booleanrequired
  • schedules
    object[]required
  • schedules[].id
    integerrequired
  • schedules[].number
    stringrequired
  • schedules[].name
    stringrequired
  • schedules[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • schedules[].balance_account_id
    integerrequired
  • schedules[].opening
    stringrequired
  • schedules[].amortization_posted
    stringrequired
  • schedules[].closing
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant or wrong company
  • 404Entity outside the grant
  • 422from and to missing or invalid

Example request

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

List amortization runs

Runs of the grant's entities, latest period first (at most 200). Needs view_ledger. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • status
    anyrequired
    One of: prepared, posted, cancelled, superseded, reversed.
  • evidence_hash
    stringrequired
  • total_expense
    stringrequired
  • total_revenue
    stringrequired
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].number
    stringrequired
  • items[].name
    stringrequired
  • items[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • items[].target
    stringrequired
  • items[].posted
    stringrequired
  • items[].amount
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].schedule_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].memo
    stringrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • unchanged
    boolean
    Prepare responses only: true when the prepared run with the same evidence is returned

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant, outside the entity scope or wrong company
  • 422Invalid query

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • prepaid_run
    objectrequired
  • prepaid_run.period_id
    integerrequired
  • prepaid_run.entity_id
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • status
    anyrequired
    One of: prepared, posted, cancelled, superseded, reversed.
  • evidence_hash
    stringrequired
  • total_expense
    stringrequired
  • total_revenue
    stringrequired
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].number
    stringrequired
  • items[].name
    stringrequired
  • items[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • items[].target
    stringrequired
  • items[].posted
    stringrequired
  • items[].amount
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].schedule_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].memo
    stringrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • unchanged
    boolean
    Prepare responses only: true when the prepared run with the same evidence is returned

Errors

  • 401Missing or invalid bearer token
  • 403Missing post_journal, a project-scoped grant, outside the entity scope or wrong company
  • 404Period or entity not found
  • 409Already posted for the period and entity
  • 422Invalid body, closed or non-calendar period, a later run posted, or nothing due

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • status
    anyrequired
    One of: prepared, posted, cancelled, superseded, reversed.
  • evidence_hash
    stringrequired
  • total_expense
    stringrequired
  • total_revenue
    stringrequired
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].number
    stringrequired
  • items[].name
    stringrequired
  • items[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • items[].target
    stringrequired
  • items[].posted
    stringrequired
  • items[].amount
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].schedule_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].memo
    stringrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • unchanged
    boolean
    Prepare responses only: true when the prepared run with the same evidence is returned

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.action
    anyrequired
    One of: approve, cancel.
  • decision.reason
    string | null

Response · 200 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • status
    anyrequired
    One of: prepared, posted, cancelled, superseded, reversed.
  • evidence_hash
    stringrequired
  • total_expense
    stringrequired
  • total_revenue
    stringrequired
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].number
    stringrequired
  • items[].name
    stringrequired
  • items[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • items[].target
    stringrequired
  • items[].posted
    stringrequired
  • items[].amount
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].schedule_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].memo
    stringrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • unchanged
    boolean
    Prepare responses only: true when the prepared run with the same evidence is returned

Errors

  • 401Missing or invalid bearer token
  • 403Missing approve_journal (post_journal to cancel), the preparer approving, a project-scoped grant or wrong company
  • 404Not found or outside the entity scope
  • 409Not prepared any more, or the evidence moved
  • 422Invalid body or a closed period

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reversal
    objectrequired
  • reversal.date
    string (date)required
  • reversal.reason
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • period_id
    integerrequired
  • entity_id
    integerrequired
  • status
    anyrequired
    One of: prepared, posted, cancelled, superseded, reversed.
  • evidence_hash
    stringrequired
  • total_expense
    stringrequired
  • total_revenue
    stringrequired
  • items
    object[]required
  • items[].schedule_id
    integerrequired
  • items[].number
    stringrequired
  • items[].name
    stringrequired
  • items[].kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • items[].target
    stringrequired
  • items[].posted
    stringrequired
  • items[].amount
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].schedule_id
    integerrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • lines[].dimension_value_ids
    array | nullrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].memo
    stringrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | null (date-time)required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • unchanged
    boolean
    Prepare responses only: true when the prepared run with the same evidence is returned

Errors

  • 401Missing or invalid bearer token
  • 403Missing approve_journal, a project-scoped grant or wrong company
  • 404Not found or outside the entity scope
  • 409Not posted, or reversed differently
  • 422Invalid body or a closed period

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • kind
    anyquery
    One of: prepaid, deferred_revenue.
  • status
    anyquery
    One of: active, cancelled, voided.
  • entity_id
    integerquery
  • as_of
    string (date)query

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • category
    anyrequired
    One of: insurance, bond, rent, software, maintenance_contract, other.
  • entity_id
    integerrequired
  • vendor_id
    integer | nullrequired
  • customer_id
    integer | nullrequired
  • balance_account_id
    integerrequired
  • recognition_account_id
    integerrequired
  • department_id
    integer | nullrequired
  • dimension_value_ids
    integer[]required
  • allocations
    object[]required
  • allocations[].project_id
    integer | nullrequired
  • allocations[].cost_code_id
    integer | nullrequired
  • allocations[].cost_type_id
    integer | nullrequired
  • allocations[].percent
    stringrequired
  • method
    anyrequired
    One of: daily, monthly, custom.
  • start_date
    string (date)required
  • original_amount
    stringrequired
  • original_end_date
    string (date)required
  • amount
    stringrequired
    The amount of the version in force
  • end_date
    string (date)required
    The last day of coverage of the version in force
  • funding_mode
    anyrequired
    One of: entry, existing, ap_bill_line.
  • funding_date
    string (date)required
  • funding_offset_account_id
    integer | nullrequired
  • funding_entry_id
    integer | nullrequired
  • ap_bill_id
    integer | nullrequired
  • ap_bill_line_id
    integer | nullrequired
  • status
    anyrequired
    One of: active, cancelled, voided.
  • current_version
    integerrequired
  • cancelled_on
    string | null (date)required
  • voided_on
    string | null (date)required
  • void_reason
    string | nullrequired
  • void_entry_id
    integer | nullrequired
  • memo
    string | nullrequired
  • as_of
    string (date)required
  • amortization_posted
    stringrequired
  • scheduled_through_as_of
    stringrequired
  • unposted_through_as_of
    stringrequired
  • balance
    stringrequired
    Unamortized balance the subledger expects on as_of (normal direction)
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • schedule_version
    integer
    Detail responses: the version whose months `schedule` shows
  • schedule
    object[]
  • schedule[].period
    stringrequired
  • schedule[].amount
    stringrequired
  • versions
    object[]
  • versions[].version
    integerrequired
  • versions[].kind
    anyrequired
    One of: original, term_change, amount_change, cancel.
  • versions[].policy
    anyrequired
    One of: prospective, catch_up, null.
  • versions[].effective_date
    string (date)required
  • versions[].amount
    stringrequired
  • versions[].end_date
    string (date)required
  • versions[].recognized_before
    stringrequired
  • versions[].balance_delta
    stringrequired
  • versions[].refund_amount
    stringrequired
  • versions[].refund_account_id
    integer | nullrequired
  • versions[].offset_account_id
    integer | nullrequired
  • versions[].entry_id
    integer | nullrequired
  • versions[].reason
    stringrequired
  • versions[].created_by_id
    integerrequired
  • versions[].created_at
    string (date-time)required
  • versions[].months
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant, outside the entity scope or wrong company
  • 422Invalid query

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • schedule
    objectrequired
  • schedule.name
    stringrequired
  • schedule.kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • schedule.category
    anyrequired
    One of: insurance, bond, rent, software, maintenance_contract, other.
  • schedule.entity_id
    integer | null
  • schedule.vendor_id
    integer | null
  • schedule.customer_id
    integer | null
  • schedule.amount
    string
    Required unless deferring a bill line (default: the line with its use tax)
  • schedule.start_date
    string (date)required
  • schedule.end_date
    string (date)required
  • schedule.method
    anyrequired
    One of: daily, monthly, custom.
  • schedule.percents
    object[]
  • schedule.percents[].period
    stringrequired
  • schedule.percents[].percent
    stringrequired
  • schedule.balance_account_id
    integer | null
  • schedule.recognition_account_id
    integer | null
  • schedule.department_id
    integer | null
  • schedule.dimension_value_ids
    integer[]
  • schedule.allocations
    object[]
  • schedule.allocations[].project_id
    integer | null
  • schedule.allocations[].cost_code_id
    integer | null
  • schedule.allocations[].cost_type_id
    integer | null
  • schedule.allocations[].percent
    stringrequired
  • schedule.funding_mode
    any
    One of: entry, existing.
  • schedule.funding_date
    string (date)
  • schedule.funding_offset_account_id
    integer | null
  • schedule.ap_bill_line_id
    integer | null
  • schedule.memo
    string
  • schedule.preview
    boolean

Response · 200 · object

  • preview
    anyrequired
  • kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • entity_id
    integerrequired
  • amount
    stringrequired
  • balance_account_id
    integerrequired
  • recognition_account_id
    integerrequired
  • funding_mode
    anyrequired
    One of: entry, existing, ap_bill_line.
  • funding_date
    string (date)required
  • funding_lines
    object[]required
  • funding_lines[].account_id
    integerrequired
  • funding_lines[].debit
    stringrequired
  • funding_lines[].credit
    stringrequired
  • funding_lines[].project_id
    integer | nullrequired
  • funding_lines[].cost_code_id
    integer | nullrequired
  • funding_lines[].cost_type_id
    integer | nullrequired
  • funding_lines[].memo
    string | nullrequired
  • schedule
    object[]required
  • schedule[].period
    stringrequired
  • schedule[].amount
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing post_journal, a project-scoped grant, outside the entity scope or wrong company
  • 404Bill line not found
  • 409The bill line is already deferred
  • 422Invalid body, accounts, allocation or terms, or a closed period

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • category
    anyrequired
    One of: insurance, bond, rent, software, maintenance_contract, other.
  • entity_id
    integerrequired
  • vendor_id
    integer | nullrequired
  • customer_id
    integer | nullrequired
  • balance_account_id
    integerrequired
  • recognition_account_id
    integerrequired
  • department_id
    integer | nullrequired
  • dimension_value_ids
    integer[]required
  • allocations
    object[]required
  • allocations[].project_id
    integer | nullrequired
  • allocations[].cost_code_id
    integer | nullrequired
  • allocations[].cost_type_id
    integer | nullrequired
  • allocations[].percent
    stringrequired
  • method
    anyrequired
    One of: daily, monthly, custom.
  • start_date
    string (date)required
  • original_amount
    stringrequired
  • original_end_date
    string (date)required
  • amount
    stringrequired
    The amount of the version in force
  • end_date
    string (date)required
    The last day of coverage of the version in force
  • funding_mode
    anyrequired
    One of: entry, existing, ap_bill_line.
  • funding_date
    string (date)required
  • funding_offset_account_id
    integer | nullrequired
  • funding_entry_id
    integer | nullrequired
  • ap_bill_id
    integer | nullrequired
  • ap_bill_line_id
    integer | nullrequired
  • status
    anyrequired
    One of: active, cancelled, voided.
  • current_version
    integerrequired
  • cancelled_on
    string | null (date)required
  • voided_on
    string | null (date)required
  • void_reason
    string | nullrequired
  • void_entry_id
    integer | nullrequired
  • memo
    string | nullrequired
  • as_of
    string (date)required
  • amortization_posted
    stringrequired
  • scheduled_through_as_of
    stringrequired
  • unposted_through_as_of
    stringrequired
  • balance
    stringrequired
    Unamortized balance the subledger expects on as_of (normal direction)
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • schedule_version
    integer
    Detail responses: the version whose months `schedule` shows
  • schedule
    object[]
  • schedule[].period
    stringrequired
  • schedule[].amount
    stringrequired
  • versions
    object[]
  • versions[].version
    integerrequired
  • versions[].kind
    anyrequired
    One of: original, term_change, amount_change, cancel.
  • versions[].policy
    anyrequired
    One of: prospective, catch_up, null.
  • versions[].effective_date
    string (date)required
  • versions[].amount
    stringrequired
  • versions[].end_date
    string (date)required
  • versions[].recognized_before
    stringrequired
  • versions[].balance_delta
    stringrequired
  • versions[].refund_amount
    stringrequired
  • versions[].refund_account_id
    integer | nullrequired
  • versions[].offset_account_id
    integer | nullrequired
  • versions[].entry_id
    integer | nullrequired
  • versions[].reason
    stringrequired
  • versions[].created_by_id
    integerrequired
  • versions[].created_at
    string (date-time)required
  • versions[].months
    object[]required

Errors

  • 400Unknown version
  • 401Missing or invalid bearer token
  • 403No accounting access, a project-scoped grant or wrong company
  • 404Not found or outside the entity scope

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • modification
    objectrequired
  • modification.kind
    anyrequired
    One of: term_change, amount_change, cancel.
  • modification.effective_date
    string (date)required
  • modification.reason
    stringrequired
  • modification.policy
    any
    One of: prospective, catch_up.
  • modification.new_end_date
    string (date)
  • modification.new_amount
    string
  • modification.percents
    object[]
  • modification.percents[].period
    stringrequired
  • modification.percents[].percent
    stringrequired
  • modification.offset_account_id
    integer | null
  • modification.refund_amount
    string
  • modification.refund_account_id
    integer | null
  • modification.preview
    boolean

Response · 200 · object

  • preview
    anyrequired
  • version
    integerrequired
  • amount
    stringrequired
  • end_date
    string (date)required
  • recognized_before
    stringrequired
  • balance_delta
    stringrequired
  • removed
    stringrequired
  • refund_amount
    stringrequired
  • write_off
    stringrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
  • lines[].credit
    stringrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].memo
    string | nullrequired
  • schedule
    object[]required
  • schedule[].period
    stringrequired
  • schedule[].amount
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing post_journal, a project-scoped grant or wrong company
  • 404Not found or outside the entity scope
  • 409Cancelled or voided, or amortization posted on or after the effective date
  • 422Invalid body or terms, or a closed period

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • void
    objectrequired
  • void.date
    string (date)required
  • void.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: prepaid, deferred_revenue.
  • category
    anyrequired
    One of: insurance, bond, rent, software, maintenance_contract, other.
  • entity_id
    integerrequired
  • vendor_id
    integer | nullrequired
  • customer_id
    integer | nullrequired
  • balance_account_id
    integerrequired
  • recognition_account_id
    integerrequired
  • department_id
    integer | nullrequired
  • dimension_value_ids
    integer[]required
  • allocations
    object[]required
  • allocations[].project_id
    integer | nullrequired
  • allocations[].cost_code_id
    integer | nullrequired
  • allocations[].cost_type_id
    integer | nullrequired
  • allocations[].percent
    stringrequired
  • method
    anyrequired
    One of: daily, monthly, custom.
  • start_date
    string (date)required
  • original_amount
    stringrequired
  • original_end_date
    string (date)required
  • amount
    stringrequired
    The amount of the version in force
  • end_date
    string (date)required
    The last day of coverage of the version in force
  • funding_mode
    anyrequired
    One of: entry, existing, ap_bill_line.
  • funding_date
    string (date)required
  • funding_offset_account_id
    integer | nullrequired
  • funding_entry_id
    integer | nullrequired
  • ap_bill_id
    integer | nullrequired
  • ap_bill_line_id
    integer | nullrequired
  • status
    anyrequired
    One of: active, cancelled, voided.
  • current_version
    integerrequired
  • cancelled_on
    string | null (date)required
  • voided_on
    string | null (date)required
  • void_reason
    string | nullrequired
  • void_entry_id
    integer | nullrequired
  • memo
    string | nullrequired
  • as_of
    string (date)required
  • amortization_posted
    stringrequired
  • scheduled_through_as_of
    stringrequired
  • unposted_through_as_of
    stringrequired
  • balance
    stringrequired
    Unamortized balance the subledger expects on as_of (normal direction)
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • schedule_version
    integer
    Detail responses: the version whose months `schedule` shows
  • schedule
    object[]
  • schedule[].period
    stringrequired
  • schedule[].amount
    stringrequired
  • versions
    object[]
  • versions[].version
    integerrequired
  • versions[].kind
    anyrequired
    One of: original, term_change, amount_change, cancel.
  • versions[].policy
    anyrequired
    One of: prospective, catch_up, null.
  • versions[].effective_date
    string (date)required
  • versions[].amount
    stringrequired
  • versions[].end_date
    string (date)required
  • versions[].recognized_before
    stringrequired
  • versions[].balance_delta
    stringrequired
  • versions[].refund_amount
    stringrequired
  • versions[].refund_account_id
    integer | nullrequired
  • versions[].offset_account_id
    integer | nullrequired
  • versions[].entry_id
    integer | nullrequired
  • versions[].reason
    stringrequired
  • versions[].created_by_id
    integerrequired
  • versions[].created_at
    string (date-time)required
  • versions[].months
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403Missing post_journal, a project-scoped grant or wrong company
  • 404Not found or outside the entity scope
  • 409Amortization posted, modified, or voided differently
  • 422Invalid body or a closed period

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • name
    stringrequired
  • memo
    string | nullrequired
  • journal
    stringrequired
  • frequency
    anyrequired
    One of: weekly, monthly, quarterly, yearly.
  • interval
    integerrequired
  • day_of_month
    integer | nullrequired
  • start_date
    string (date)required
  • end_date
    string | null (date)required
  • next_run_date
    string (date)required
  • last_run_date
    string | null (date)required
  • reverse_after_days
    integer | nullrequired
  • auto_post
    booleanrequired
  • is_active
    booleanrequired
  • created_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • lines
    object[]required
  • lines[].dimension_value_ids
    array | null
    User-defined dimension values carried onto each generated entry's line.
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • last_error
    string | nullrequired
    Last 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_at
    string | null (date-time)required

Errors

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

Example request

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

Accounting / Journal Entries

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

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

v1.0Implemented

Parameters

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

Request body

  • recurring_journal
    objectrequired
  • recurring_journal.entity_id
    integer | null
  • recurring_journal.name
    stringrequired
  • recurring_journal.memo
    string | null
  • recurring_journal.frequency
    any
    One of: weekly, monthly, quarterly, yearly.
  • recurring_journal.interval
    integer
  • recurring_journal.day_of_month
    integer | null
  • recurring_journal.start_date
    string (date)required
  • recurring_journal.end_date
    string | null (date)
  • recurring_journal.reverse_after_days
    integer | null
  • recurring_journal.auto_post
    boolean
  • recurring_journal.is_active
    boolean
  • recurring_journal.lines
    object[]required
  • recurring_journal.lines[].account_id
    integerrequired
  • recurring_journal.lines[].debit
    string | number
  • recurring_journal.lines[].credit
    string | number
  • recurring_journal.lines[].memo
    string | null
  • recurring_journal.lines[].project_id
    integer | null
  • recurring_journal.lines[].cost_code_id
    integer | null
  • recurring_journal.lines[].cost_type_id
    integer | null
  • recurring_journal.lines[].department_id
    integer | null
  • recurring_journal.lines[].dimension_value_ids
    array | null
    Custom dimension values (dimension value ids of this company), copied onto each generated entry's line.

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • name
    stringrequired
  • memo
    string | nullrequired
  • journal
    stringrequired
  • frequency
    anyrequired
    One of: weekly, monthly, quarterly, yearly.
  • interval
    integerrequired
  • day_of_month
    integer | nullrequired
  • start_date
    string (date)required
  • end_date
    string | null (date)required
  • next_run_date
    string (date)required
  • last_run_date
    string | null (date)required
  • reverse_after_days
    integer | nullrequired
  • auto_post
    booleanrequired
  • is_active
    booleanrequired
  • created_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • lines
    object[]required
  • lines[].dimension_value_ids
    array | null
    User-defined dimension values carried onto each generated entry's line.
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • last_error
    string | nullrequired
    Last 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_at
    string | null (date-time)required

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • name
    stringrequired
  • memo
    string | nullrequired
  • journal
    stringrequired
  • frequency
    anyrequired
    One of: weekly, monthly, quarterly, yearly.
  • interval
    integerrequired
  • day_of_month
    integer | nullrequired
  • start_date
    string (date)required
  • end_date
    string | null (date)required
  • next_run_date
    string (date)required
  • last_run_date
    string | null (date)required
  • reverse_after_days
    integer | nullrequired
  • auto_post
    booleanrequired
  • is_active
    booleanrequired
  • created_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • lines
    object[]required
  • lines[].dimension_value_ids
    array | null
    User-defined dimension values carried onto each generated entry's line.
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • last_error
    string | nullrequired
    Last 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_at
    string | null (date-time)required

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Request body

  • recurring_journal
    objectrequired
  • recurring_journal.entity_id
    integer | null
  • recurring_journal.name
    string
  • recurring_journal.memo
    string | null
  • recurring_journal.frequency
    any
    One of: weekly, monthly, quarterly, yearly.
  • recurring_journal.interval
    integer
  • recurring_journal.day_of_month
    integer | null
  • recurring_journal.start_date
    string (date)
  • recurring_journal.end_date
    string | null (date)
  • recurring_journal.reverse_after_days
    integer | null
  • recurring_journal.auto_post
    boolean
  • recurring_journal.is_active
    boolean
  • recurring_journal.lines
    object[]
  • recurring_journal.lines[].account_id
    integerrequired
  • recurring_journal.lines[].debit
    string | number
  • recurring_journal.lines[].credit
    string | number
  • recurring_journal.lines[].memo
    string | null
  • recurring_journal.lines[].project_id
    integer | null
  • recurring_journal.lines[].cost_code_id
    integer | null
  • recurring_journal.lines[].cost_type_id
    integer | null
  • recurring_journal.lines[].department_id
    integer | null
  • recurring_journal.lines[].dimension_value_ids
    array | null
    Custom dimension values (dimension value ids of this company), copied onto each generated entry's line.

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • name
    stringrequired
  • memo
    string | nullrequired
  • journal
    stringrequired
  • frequency
    anyrequired
    One of: weekly, monthly, quarterly, yearly.
  • interval
    integerrequired
  • day_of_month
    integer | nullrequired
  • start_date
    string (date)required
  • end_date
    string | null (date)required
  • next_run_date
    string (date)required
  • last_run_date
    string | null (date)required
  • reverse_after_days
    integer | nullrequired
  • auto_post
    booleanrequired
  • is_active
    booleanrequired
  • created_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • lines
    object[]required
  • lines[].dimension_value_ids
    array | null
    User-defined dimension values carried onto each generated entry's line.
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • last_error
    string | nullrequired
    Last 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_at
    string | null (date-time)required

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 422Validation failed (field errors) or the ledger refused the change (message list)

Example request

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

Accounting / Journal Entries

POST /rest/v1.0/companies/{company_id}/accounting/recurring_journals/{id}/approve

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • name
    stringrequired
  • memo
    string | nullrequired
  • journal
    stringrequired
  • frequency
    anyrequired
    One of: weekly, monthly, quarterly, yearly.
  • interval
    integerrequired
  • day_of_month
    integer | nullrequired
  • start_date
    string (date)required
  • end_date
    string | null (date)required
  • next_run_date
    string (date)required
  • last_run_date
    string | null (date)required
  • reverse_after_days
    integer | nullrequired
  • auto_post
    booleanrequired
  • is_active
    booleanrequired
  • created_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • total_amount
    stringrequired
    Decimal amount as a string, 2 dp
  • lines
    object[]required
  • lines[].dimension_value_ids
    array | null
    User-defined dimension values carried onto each generated entry's line.
  • lines[].id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].account_id
    integerrequired
  • lines[].debit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].credit
    stringrequired
    Decimal amount as a string, 2 dp
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].cost_type_id
    integer | nullrequired
  • lines[].department_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • last_error
    string | nullrequired
    Last 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_at
    string | null (date-time)required

Errors

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

Example request

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

Ask the OS

Reading this page

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

Suggested

    AI · may be imperfect · sample data where shown

    Open file