Banking
Reconcile statements, forecast cash and review ACH payment exceptions. 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 Banking guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/ach/monitoringACH fraud-monitoring evidence - GET
/rest/v1.0/companies/{company_id}/accounting/ach/noticesACH returns and NOCs - POST
/rest/v1.0/companies/{company_id}/accounting/ach/noticesImport an ACH return/NOC file - POST
/rest/v1.0/companies/{company_id}/accounting/ach/notices/{id}/resolveResolve a manual NOC - POST
/rest/v1.0/companies/{company_id}/accounting/ach/notices/apply_nocsApply NOCs - POST
/rest/v1.0/companies/{company_id}/accounting/ach/prenotesGenerate a prenote file - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accountsList bank and card accounts - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accountsCreate a bank account - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}Show a bank account - PATCH
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}Update a bank account - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/activity_previewInspect one sandbox card activity response without persistence - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/bank_changeApprove or reject a pending bank number change - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/inboxMatching inbox - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/inbox/accept_highAccept all High matches - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/outstandingOutstanding items - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_payGenerate a positive pay file - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_pay/batchesList positive pay batches - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_pay/batches/{batch_id}/regenerateRegenerate a positive pay batch - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/receipt_captureFirst receipt submissions needed for existing native card charge lines - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/reconciliationsList reconciliations - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/reconciliationsStart a reconciliation - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/registerAccount register - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/revealReveal bank numbers - GET
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/statement_importsList statement imports - POST
/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/statement_importsImport a statement - GET
/rest/v1.0/companies/{company_id}/accounting/banking/cash_forecastCash forecast - GET
/rest/v1.0/companies/{company_id}/accounting/banking/cash_positionCash position - POST
/rest/v1.0/companies/{company_id}/accounting/banking/checks/{id}/stopStop payment on a check - GET
/rest/v1.0/companies/{company_id}/accounting/banking/feedsList live bank feed connections - POST
/rest/v1.0/companies/{company_id}/accounting/banking/feedsLink a bank (exchange a Link public token) - GET
/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}Show a live bank feed connection - DELETE
/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}Disconnect a live bank feed - PATCH
/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}/accountsMap feed accounts to bank accounts - POST
/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}/syncSync a live bank feed now - POST
/rest/v1.0/companies/{company_id}/accounting/banking/feeds/link_tokenCreate a bank Link token - GET
/rest/v1.0/companies/{company_id}/accounting/banking/receipt_reviewsList pending independent card receipt reviews - GET
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Show a reconciliation - PATCH
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Tick lines / change the statement balance - DELETE
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Cancel an in-progress reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/finishFinish a reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/reviewReview a finished reconciliation - POST
/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/undoUndo a reconciliation - GET
/rest/v1.0/companies/{company_id}/accounting/banking/rulesList bank rules - POST
/rest/v1.0/companies/{company_id}/accounting/banking/rulesCreate a bank rule - PATCH
/rest/v1.0/companies/{company_id}/accounting/banking/rules/{id}Update a bank rule - DELETE
/rest/v1.0/companies/{company_id}/accounting/banking/rules/{id}Delete a bank rule - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/create_transactionCreate from a statement line - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/feed_note/clearMark a bank feed note reviewed - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/ignoreIgnore a statement line - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/matchMatch a statement line - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/restoreRestore an ignored statement line - POST
/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/unmatchUnmatch a statement line - GET
/rest/v1.0/companies/{company_id}/accounting/banking/transactionsList cash documents - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactionsRecord and post a cash document - GET
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}Show a cash document - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/approveRelease or approve a pending cash document - GET
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/attachmentsList attachments on a bank transaction - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/attachmentsAttach a file to a bank transaction - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/check_printCheck print data - GET
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidenceRead retained receipt evidence under bank-account scope - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidenceSubmit line evidence for independent review - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidence/reviewRecord immutable independent review; exact reviewer/outcome/reason retries replay - POST
/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/voidVoid a cash document
Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/ach/monitoringACH fraud-monitoring evidence
Needs manage_vendor_banking. Evidence for Nacha's risk-based fraud monitoring (non-consumer Originators, effective 2026-06-22) over a window: controls in force, vendor and employee bank-account changes and NOC applications, prenote and block records, returns by code (unauthorized R05/R07/R10/R29 counted), NOC timeliness and the notices. Masks only. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)queryrequired
- tostring (date)queryrequired
Response · 200 · object
- fromstring (date)required
- tostring (date)required
- controlsobjectrequired
- bank_changesobject[]required
- accountsobject[]required
- returnsobjectrequired
- nocsobjectrequired
- noticesobject[]required
- notices[].idintegerrequired
- notices[].kindstringrequiredOne of: return, noc.
- notices[].codestringrequiredR-code (return) or C-code (NOC)
- notices[].original_tracestringrequired
- notices[].trace_numberstring | null
- notices[].id_numberstringrequiredIdentification number of the original entry: V<vendor id> for AP, the employee number for payroll
- notices[].amountstringrequired
- notices[].received_datestring (date)required
- notices[].due_datestring | null (date)NOC: six banking days after receipt (Nacha Rule 2.12.1)
- notices[].party_kindstring | nullOne of: vendor, employee, null.
- notices[].party_idinteger | null
- notices[].ap_payment_idinteger | null
- notices[].pay_check_idinteger | null
- notices[].entry_idinteger | null
- notices[].statusstringrequiredOne of: open, applied, manual, unmatched.
- notices[].messagestring | null
- notices[].applied_atstring | null (date-time)
- notices[].applied_by_idinteger | null
- notices[].imported_by_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/monitoring" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/ach/noticesACH returns and NOCs
Needs manage_vendor_banking. Newest first, up to 500; filter with status (open, applied, manual, unmatched). Corrected NOC data stays encrypted and is never returned. Newest first, paged in the database with the caller's entity scope applied (Total, Per-Page and Link headers). Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- statusanyqueryOnly notices in this status; any other value is 422. One of: open, applied, manual, unmatched.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- kindstringrequiredOne of: return, noc.
- codestringrequiredR-code (return) or C-code (NOC)
- original_tracestringrequired
- trace_numberstring | null
- id_numberstringrequiredIdentification number of the original entry: V<vendor id> for AP, the employee number for payroll
- amountstringrequired
- received_datestring (date)required
- due_datestring | null (date)NOC: six banking days after receipt (Nacha Rule 2.12.1)
- party_kindstring | nullOne of: vendor, employee, null.
- party_idinteger | null
- ap_payment_idinteger | null
- pay_check_idinteger | null
- entry_idinteger | null
- statusstringrequiredOne of: open, applied, manual, unmatched.
- messagestring | null
- applied_atstring | null (date-time)
- applied_by_idinteger | null
- imported_by_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/notices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/ach/noticesImport an ACH return/NOC file
Needs manage_vendor_banking (plus release_payments for AP returns, payroll_run for payroll returns). A NACHA return/COR file (entries with addenda 99/98) or a bank CSV (code, original_trace, id_number, amount, corrected_data, optional trace_number). A return on an AP payment reverses it dated received_date (closed period refused), reopens its bills with an ach_returned hold and, for R02/R03/R04/R07/R10/R12/R14/R15/R16/R20/R23/R29, blocks that bank account; a return on a paycheck posts Dr payroll cash / Cr payroll clearing (net pay owed again); a returned prenote blocks the account. NOCs are queued with their six-banking-day due date. Idempotent: notices already imported are counted in skipped. Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403. A grant with neither manage_vendor_banking nor payroll_run (for example a view-only role) gets 403 before anything is written, even for a file whose notices were all imported already, and so does a read-only workspace.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- ach_importobjectrequired
- ach_import.formatstringrequiredOne of: nacha, csv.
- ach_import.contentstringrequired
- ach_import.received_datestring (date)required
Response · 201 · object
- noticesobject[]required
- notices[].idintegerrequired
- notices[].kindstringrequired
- notices[].codestringrequired
- notices[].statusstringrequired
- notices[].messagestring | null
- skippedintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace409ach_trace_ambiguous, ach_return_not_posted422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/notices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"ach_import": {
"format": "nacha",
"content": "string",
"received_date": "2026-11-01"
}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/ach/notices/{id}/resolveResolve a manual NOC
Needs manage_vendor_banking. Marks a C04/C06/C07 NOC (status manual) applied after the bank record was corrected by hand; the importer can't resolve it (403 sod_noc). Needs step-up (a token needs the accounting:step_up scope, 403 step_up_required). Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403. A grant with neither manage_vendor_banking nor payroll_run (for example a view-only role) gets 403 before anything is written, even for a file whose notices were all imported already, and so does a read-only workspace.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- resolveobjectrequired
- resolve.reasonstringrequired
Response · 200 · object
- idintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace404Not a manual NOC in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/notices/1/resolve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"resolve": {
"reason": "string"
}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/ach/notices/apply_nocsApply NOCs
Needs manage_vendor_banking (payroll_run for employee NOCs). Applies the open C01/C02/C03/C05 NOCs named in ids (required, at least one: there is no apply-all; an empty list is 422 noc_ids_required) to the vendor or employee bank record and records the corrected account as verified, so the next file pays it. Needs step-up (a token needs the accounting:step_up scope, 403 step_up_required). The importer can't apply (403 sod_noc). Audited per notice (noc_applied) with masks only; the response carries each notice's masked old -> new routing and account last 4 (changes). Requires the accounting:write scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403. A grant with neither manage_vendor_banking nor payroll_run (for example a view-only role) gets 403 before anything is written, even for a file whose notices were all imported already, and so does a read-only workspace.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- applyobjectrequired
- apply.idsinteger[]required
Response · 200 · object
- appliedinteger[]required
- changesobject[]required
- changes[].idinteger
- changes[].party_kindstringOne of: vendor, employee.
- changes[].party_idinteger
- changes[].routing_last4string[]
- changes[].account_last4string[]
- changes[].account_typestring[]
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace404An id is not an open NOC409noc_no_account422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/notices/apply_nocs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"apply": {
"ids": []
}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/ach/prenotesGenerate a prenote file
Vendors need manage_vendor_banking and bank_account_id (the ODFI); employees need payroll_run and view_payroll_pii over every entity. Zero-dollar prenote entries (transaction code 23/33) for every ACH vendor or direct-deposit employee whose current account has no prenote, verification or block; vendor batches use the SEC code from bank_account_ownership. Records the settlement date and the earliest live date (third banking day after, Nacha Rules 2.6). 422 nothing_to_prenote when none is due. Returns the NACHA text with X-Prenote-Count and X-Earliest-Live-Date headers. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- prenoteobjectrequired
- prenote.kindstringrequiredOne of: vendor, employee.
- prenote.effective_datestring (date)required
- prenote.bank_account_idinteger | null
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties (sod_noc), wrong company, or read-only workspace404Bank account not found422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ach/prenotes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"prenote": {
"kind": "vendor",
"effective_date": "2026-11-01"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accountsList bank and card accounts
Bank, savings, money market, cash and credit card registers, each tied to one GL account. Bank numbers are masked. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- activestringqueryFilter by active One of: true, false.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- entity_idinteger | nullrequired
- gl_account_idintegerrequired
- gl_account_numberstringrequired
- gl_account_namestringrequired
- institutionstring | nullrequired
- account_number_maskedstring | nullrequired****1234; full numbers only via /reveal
- routing_number_maskedstring | nullrequired
- currencystringrequiredAlways the company base currency.
- is_activebooleanrequired
- next_check_numberinteger | nullrequired
- receipt_required_overstring | nullrequired
- match_window_daysintegerrequired
- low_balance_thresholdstring | nullrequired
- has_csv_mappingbooleanrequired
- positive_pay_optionsobject | nullrequiredPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- created_atstring (date-time)required
- updated_atstring (date-time)required
- pending_bank_changeobject | nullrequiredA requested account/routing number change waiting for a second manage_vendor_banking user (POST .../bank_change). Masked values only.
- pending_bank_change.requested_by_idintegerrequired
- pending_bank_change.changesobject[]required
- pending_bank_change.change_hashstringrequiredSend back with the decision; a change replaced since you reviewed it is refused (409).
- feedobject | nullLive bank feed mapping (null when not fed).
- feed.connection_idinteger
- feed.feed_account_idstring | null
- feed.start_datestring | null (date)
- feed.institution_namestring | null
- feed.statusstring | null
- feed.last_success_atstring | null (date-time)
- feed.healthobject | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accountsCreate a bank account
Links an existing GL account (bank/cash, or credit_card for cards) or creates one (create_gl_account). Needs manage_coa; bank numbers need manage_vendor_banking. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- bank_accountobjectrequired
- bank_account.namestringrequired
- bank_account.kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- bank_account.gl_account_idinteger | null
- bank_account.create_gl_accountboolean
- bank_account.entity_idinteger | null
- bank_account.institutionstring | null
- bank_account.account_numberstring | null4–17 digits; needs manage_vendor_banking; encrypted at rest
- bank_account.routing_numberstring | null9 digits; needs manage_vendor_banking
- bank_account.currencystringISO 4217 code. Must equal the company base currency (AcctSettings.baseCurrency); any other value is refused with 422 until multi-currency exists. Defaults to the base currency.
- bank_account.is_activeboolean
- bank_account.next_check_numberinteger | null
- bank_account.receipt_required_overstring | null
- bank_account.match_window_daysinteger
- bank_account.low_balance_thresholdstring | null
- bank_account.csv_mappingobject | null
- bank_account.csv_mapping.datestring | integerrequired
- bank_account.csv_mapping.descriptionstring | integerrequired
- bank_account.csv_mapping.amountstring | integer
- bank_account.csv_mapping.debitstring | integer
- bank_account.csv_mapping.creditstring | integer
- bank_account.csv_mapping.referencestring | integer
- bank_account.csv_mapping.check_numberstring | integer
- bank_account.csv_mapping.balancestring | integer
- bank_account.csv_mapping.date_formatstringOne of: YYYYMMDD, MMDDYYYY, MMDDYY, YYMMDD, MM/DD/YYYY, YYYY-MM-DD.
- bank_account.csv_mapping.signstringOne of: deposit_positive, withdrawal_positive.
- bank_account.csv_mapping.has_headerboolean
- bank_account.csv_mapping.skip_rowsinteger
- bank_account.csv_mapping.delimiterstring
- bank_account.positive_pay_optionsobject | nullPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
Response · 201 · object
- idintegerrequired
- namestringrequired
- kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- entity_idinteger | nullrequired
- gl_account_idintegerrequired
- gl_account_numberstringrequired
- gl_account_namestringrequired
- institutionstring | nullrequired
- account_number_maskedstring | nullrequired****1234; full numbers only via /reveal
- routing_number_maskedstring | nullrequired
- currencystringrequiredAlways the company base currency.
- is_activebooleanrequired
- next_check_numberinteger | nullrequired
- receipt_required_overstring | nullrequired
- match_window_daysintegerrequired
- low_balance_thresholdstring | nullrequired
- has_csv_mappingbooleanrequired
- positive_pay_optionsobject | nullrequiredPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- created_atstring (date-time)required
- updated_atstring (date-time)required
- pending_bank_changeobject | nullrequiredA requested account/routing number change waiting for a second manage_vendor_banking user (POST .../bank_change). Masked values only.
- pending_bank_change.requested_by_idintegerrequired
- pending_bank_change.changesobject[]required
- pending_bank_change.change_hashstringrequiredSend back with the decision; a change replaced since you reviewed it is refused (409).
- feedobject | nullLive bank feed mapping (null when not fed).
- feed.connection_idinteger
- feed.feed_account_idstring | null
- feed.start_datestring | null (date)
- feed.institution_namestring | null
- feed.statusstring | null
- feed.last_success_atstring | null (date-time)
- feed.healthobject | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"bank_account": {
"name": "string",
"kind": "checking"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}Show a bank account
One bank account with masked numbers. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- entity_idinteger | nullrequired
- gl_account_idintegerrequired
- gl_account_numberstringrequired
- gl_account_namestringrequired
- institutionstring | nullrequired
- account_number_maskedstring | nullrequired****1234; full numbers only via /reveal
- routing_number_maskedstring | nullrequired
- currencystringrequiredAlways the company base currency.
- is_activebooleanrequired
- next_check_numberinteger | nullrequired
- receipt_required_overstring | nullrequired
- match_window_daysintegerrequired
- low_balance_thresholdstring | nullrequired
- has_csv_mappingbooleanrequired
- positive_pay_optionsobject | nullrequiredPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- created_atstring (date-time)required
- updated_atstring (date-time)required
- pending_bank_changeobject | nullrequiredA requested account/routing number change waiting for a second manage_vendor_banking user (POST .../bank_change). Masked values only.
- pending_bank_change.requested_by_idintegerrequired
- pending_bank_change.changesobject[]required
- pending_bank_change.change_hashstringrequiredSend back with the decision; a change replaced since you reviewed it is refused (409).
- feedobject | nullLive bank feed mapping (null when not fed).
- feed.connection_idinteger
- feed.feed_account_idstring | null
- feed.start_datestring | null (date)
- feed.institution_namestring | null
- feed.statusstring | null
- feed.last_success_atstring | null (date-time)
- feed.healthobject | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
PATCH/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}Update a bank account
Name, institution, controls, CSV mapping, check numbering. Account and routing numbers need manage_vendor_banking and are not applied: they become pending_bank_change (audited bank_change_requested) until a second manage_vendor_banking user approves them via POST .../bank_change. entity_id can't change once the account's GL account has journal lines (422). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- bank_accountobjectrequired
- bank_account.namestring
- bank_account.kindstringOne of: checking, savings, money_market, credit_card, cash.
- bank_account.gl_account_idinteger | null
- bank_account.create_gl_accountboolean
- bank_account.entity_idinteger | null
- bank_account.institutionstring | null
- bank_account.account_numberstring | null4–17 digits; needs manage_vendor_banking; encrypted at rest
- bank_account.routing_numberstring | null9 digits; needs manage_vendor_banking
- bank_account.currencystringISO 4217 code. Must equal the company base currency (AcctSettings.baseCurrency); any other value is refused with 422 until multi-currency exists. Defaults to the base currency.
- bank_account.is_activeboolean
- bank_account.next_check_numberinteger | null
- bank_account.receipt_required_overstring | null
- bank_account.match_window_daysinteger
- bank_account.low_balance_thresholdstring | null
- bank_account.csv_mappingobject | null
- bank_account.csv_mapping.datestring | integerrequired
- bank_account.csv_mapping.descriptionstring | integerrequired
- bank_account.csv_mapping.amountstring | integer
- bank_account.csv_mapping.debitstring | integer
- bank_account.csv_mapping.creditstring | integer
- bank_account.csv_mapping.referencestring | integer
- bank_account.csv_mapping.check_numberstring | integer
- bank_account.csv_mapping.balancestring | integer
- bank_account.csv_mapping.date_formatstringOne of: YYYYMMDD, MMDDYYYY, MMDDYY, YYMMDD, MM/DD/YYYY, YYYY-MM-DD.
- bank_account.csv_mapping.signstringOne of: deposit_positive, withdrawal_positive.
- bank_account.csv_mapping.has_headerboolean
- bank_account.csv_mapping.skip_rowsinteger
- bank_account.csv_mapping.delimiterstring
- bank_account.positive_pay_optionsobject | nullPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
Response · 200 · object
- idintegerrequired
- namestringrequired
- kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- entity_idinteger | nullrequired
- gl_account_idintegerrequired
- gl_account_numberstringrequired
- gl_account_namestringrequired
- institutionstring | nullrequired
- account_number_maskedstring | nullrequired****1234; full numbers only via /reveal
- routing_number_maskedstring | nullrequired
- currencystringrequiredAlways the company base currency.
- is_activebooleanrequired
- next_check_numberinteger | nullrequired
- receipt_required_overstring | nullrequired
- match_window_daysintegerrequired
- low_balance_thresholdstring | nullrequired
- has_csv_mappingbooleanrequired
- positive_pay_optionsobject | nullrequiredPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- created_atstring (date-time)required
- updated_atstring (date-time)required
- pending_bank_changeobject | nullrequiredA requested account/routing number change waiting for a second manage_vendor_banking user (POST .../bank_change). Masked values only.
- pending_bank_change.requested_by_idintegerrequired
- pending_bank_change.changesobject[]required
- pending_bank_change.change_hashstringrequiredSend back with the decision; a change replaced since you reviewed it is refused (409).
- feedobject | nullLive bank feed mapping (null when not fed).
- feed.connection_idinteger
- feed.feed_account_idstring | null
- feed.start_datestring | null (date)
- feed.institution_namestring | null
- feed.statusstring | null
- feed.last_success_atstring | null (date-time)
- feed.healthobject | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"bank_account": {}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/activity_previewInspect one sandbox card activity response without persistence
Requires accounting:read token scope, manageIntegrations and bankReconcile, accounting MFA and whole-account entity access. Mapping is a transient operator assertion. Source polarity is preserved, never interpreted as statement direction. No provider calls, imports, matches, receipts, jobs or postings. Supported settlement exponents: USD/CAD/EUR/GBP=2, JPY=0, KWD=3; other currencies excluded. No local duplicate identity inferred.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- sandbox_confirmedbooleanrequired
- external_entity_idstringrequired
- entity_idintegerrequired
- currencystringrequired
- source_pagestringrequiredOne selected sandbox transaction response JSON page, at most 256 KiB UTF-8 and 100 data rows. entity_amount and merchant_amount are currency/value integer minor-unit objects.
Response · 200 · object
- accountobjectrequired
- account.idinteger
- account.company_idinteger
- account.entity_idinteger
- account.gl_account_idinteger
- account.currencystring
- account.namestring
- external_entity_idstringrequired
- rowsobject[]required
- rows[].rowintegerrequired
- rows[].external_idstring | nullrequired
- rows[].statestring | nullrequired
- rows[].settlement_datestring | nullrequired
- rows[].merchantstring | nullrequired
- rows[].settlementobject | nullrequired
- rows[].merchant_amountobject | nullrequired
- rows[].statusstringrequiredOne of: evidence_only, excluded, duplicate, conflict.
- rows[].reasonsstring[]required
- countsobjectrequired
- counts.rowsinteger
- counts.evidence_onlyinteger
- counts.excludedinteger
- counts.duplicateinteger
- counts.conflictinteger
- has_morebooleanrequired
- statement_directionstringrequired
- existing_record_identitystringrequired
- actions_availablebooleanrequired
Errors
400Malformed JSON request401Authentication required403Scope or authority denied404Account outside access409Target account changed413Request above 512 KiB or response page above 256 KiB415JSON Content-Type required422Invalid mapping, input, page or target account
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/activity_preview" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"sandbox_confirmed": true,
"external_entity_id": "string",
"entity_id": 1,
"currency": "string",
"source_page": "string"
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/bank_changeApprove or reject a pending bank number change
A manage_vendor_banking user other than the requester applies or discards pending_bank_change. change_hash must match the change reviewed (409 stale_change otherwise). Audited as bank_changed or bank_change_rejected. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionstringrequiredOne of: approve, reject.
- change_hashstringrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- entity_idinteger | nullrequired
- gl_account_idintegerrequired
- gl_account_numberstringrequired
- gl_account_namestringrequired
- institutionstring | nullrequired
- account_number_maskedstring | nullrequired****1234; full numbers only via /reveal
- routing_number_maskedstring | nullrequired
- currencystringrequiredAlways the company base currency.
- is_activebooleanrequired
- next_check_numberinteger | nullrequired
- receipt_required_overstring | nullrequired
- match_window_daysintegerrequired
- low_balance_thresholdstring | nullrequired
- has_csv_mappingbooleanrequired
- positive_pay_optionsobject | nullrequiredPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- created_atstring (date-time)required
- updated_atstring (date-time)required
- pending_bank_changeobject | nullrequiredA requested account/routing number change waiting for a second manage_vendor_banking user (POST .../bank_change). Masked values only.
- pending_bank_change.requested_by_idintegerrequired
- pending_bank_change.changesobject[]required
- pending_bank_change.change_hashstringrequiredSend back with the decision; a change replaced since you reviewed it is refused (409).
- feedobject | nullLive bank feed mapping (null when not fed).
- feed.connection_idinteger
- feed.feed_account_idstring | null
- feed.start_datestring | null (date)
- feed.institution_namestring | null
- feed.statusstring | null
- feed.last_success_atstring | null (date-time)
- feed.healthobject | null
Errors
401Missing or invalid bearer token403No access, missing manage_vendor_banking, or you requested this change404Not found409The pending change was replaced after review422Validation error, or no pending change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/bank_change" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"decision": "approve",
"change_hash": "string"
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/inboxMatching inbox
Statement lines with one suggestion each: a match (source match; confidence high = amount + reference/payee/check number agree, medium = unique amount or a combination, low = several candidates) or a bank rule. Each book item is offered to one line only. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- statusstringqueryDefault unmatched One of: unmatched, matched, ignored, all.
Response · 200 · object
- bank_account_idintegerrequired
- statement_balancestring | nullrequired
- statement_datestring | null (date)required
- countsobjectrequired
- counts.allintegerrequired
- counts.suggestedintegerrequired
- counts.highintegerrequired
- counts.ruleintegerrequired
- counts.noneintegerrequired
- linesobject[]required
- lines[].idintegerrequired
- lines[].bank_account_idintegerrequired
- lines[].import_idintegerrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstringrequired
- lines[].referencestring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].bank_txn_idstring | nullrequired
- lines[].type_codestring | nullrequired
- lines[].statusstringrequiredOne of: unmatched, matched, ignored.
- lines[].match_sourcestring | nullrequired
- lines[].match_confidencestring | nullrequired
- lines[].rule_idinteger | nullrequired
- lines[].matched_atstring | null (date-time)required
- lines[].journal_line_idsinteger[]required
- lines[].suggestionobject | nullrequired
- lines[].feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
- totalintegerrequiredStatement lines matching the status filter
- truncatedbooleanrequiredTrue when more lines match than the inbox shows (oldest 1000 first); match or ignore some to see the rest
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/inbox" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/inbox/accept_highAccept all High matches
Matches every high-confidence suggestion on the account (book lines become cleared, not reconciled). Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- matchedintegerrequired
- totalstringrequiredDecimal string, 2 dp
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/inbox/accept_high" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/outstandingOutstanding items
Deposits in transit and outstanding payments as of a date, with the proof book balance = reconciled and void + outstanding (difference 0.00). The item lists are paginated (Total counts both lists); totals always cover every outstanding line. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- as_ofstring (date)queryDefault today
- pageintegerqueryPage (1-based)
- per_pageintegerqueryItems per page
Response · 200 · object
- bank_account_idintegerrequired
- as_ofstring (date)required
- deposits_in_transitobject[]required
- deposits_in_transit[].journal_line_idintegerrequired
- deposits_in_transit[].entry_numberstring | nullrequired
- deposits_in_transit[].datestring (date)required
- deposits_in_transit[].amountstringrequiredDecimal string, 2 dp
- deposits_in_transit[].descriptionstring | nullrequired
- deposits_in_transit[].bank_transaction_idinteger | nullrequired
- deposits_in_transit[].check_numberstring | nullrequired
- deposits_in_transit[].reconcile_statestringrequiredOne of: n, c.
- deposits_in_transit[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- deposits_in_transit[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- outstanding_paymentsobject[]required
- outstanding_payments[].journal_line_idintegerrequired
- outstanding_payments[].entry_numberstring | nullrequired
- outstanding_payments[].datestring (date)required
- outstanding_payments[].amountstringrequiredDecimal string, 2 dp
- outstanding_payments[].descriptionstring | nullrequired
- outstanding_payments[].bank_transaction_idinteger | nullrequired
- outstanding_payments[].check_numberstring | nullrequired
- outstanding_payments[].reconcile_statestringrequiredOne of: n, c.
- outstanding_payments[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- outstanding_payments[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- totalsobjectrequired
- totals.deposits_in_transitstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.reconciled_and_voidstringrequiredDecimal string, 2 dp
- totals.outstanding_netstringrequiredDecimal string, 2 dp
- totals.book_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totalintegerrequiredOutstanding lines across both lists (all pages)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/outstanding" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_payGenerate a positive pay file
CSV issue file of checks not yet sent plus voids of checks the bank already has. Generated on demand, never stored; marks the checks sent unless dry_run. A dry run returns counts and totals only (content is empty: the file carries the decrypted account number). Pending checks are not included until released. Needs release_payments; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- positive_payobject
- positive_pay.dry_runboolean
Response · 200 · object
- batch_idinteger | nullrequiredThe batch this file sent (null for a dry run or an empty file); regenerate it via .../positive_pay/batches/{batch_id}/regenerate
- file_namestringrequired
- contentstringrequiredCSV issue file (full account number); never stored
- dry_runbooleanrequired
- item_countintegerrequired
- issued_countintegerrequired
- void_countintegerrequired
- issued_totalstringrequiredDecimal string, 2 dp
- void_totalstringrequiredDecimal string, 2 dp
- check_numbersstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/positive_pay" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"positive_pay": {}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_pay/batchesList positive pay batches
Positive pay files sent from this account (banking and AP run files), newest first: counts and totals only. Needs release_payments. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- bank_account_idintegerrequired
- sourcestringrequiredOne of: banking, ap_run.
- ap_run_idinteger | nullrequired
- issued_countintegerrequired
- void_countintegerrequired
- issued_totalstringrequiredDecimal string, 2 dp
- void_totalstringrequiredDecimal string, 2 dp
- created_by_idintegerrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/positive_pay/batches" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/positive_pay/batches/{batch_id}/regenerateRegenerate a positive pay batch
Rebuilds a sent batch (for a lost download): the same checks with the status each was sent with, under the original file name. Marks nothing. A batch holds only the rows it marked first (an AP run file that repeated rows an earlier file sent regenerates without them), and the current account number and file options are used. Needs release_payments; audited as positive_pay_regenerated. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- batch_idintegerpathrequired
Response · 200 · object
- batch_idintegerrequired
- file_namestringrequired
- contentstringrequiredThe batch's CSV, rebuilt (full account number); never stored
- item_countintegerrequired
- check_numbersstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/positive_pay/batches/1/regenerate" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/receipt_captureFirst receipt submissions needed for existing native card charge lines
Read only. Requires accounting:read token scope, bankReconcile and whole-account access; project-scoped grants refused. Non-void card charges strictly above the current Decimal account threshold with no submission history. Legacy assertions do not exclude work. Scoped ascending line-ID cursor; no counts. Final common authorization/state snapshot; 409 if changed. No import, matching or financial writes.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- afterintegerquery
- per_pageintegerquery
Response · 200 · object
- accountobjectrequired
- account.idinteger
- account.company_idinteger
- account.gl_account_idinteger
- account.entity_idinteger | null
- account.namestring
- account.currencystring
- account.receipt_required_overstring | null
- itemsobject[]required
- items[].line_idintegerrequired
- items[].line_nointegerrequired
- items[].transaction_idintegerrequired
- items[].transaction_numberstringrequired
- items[].transaction_statusstringrequired
- items[].amountstringrequired
- items[].hrefstringrequired
- items[].transaction_datestring (date)required
- items[].payeestring | nullrequired
- items[].legacy_has_receiptbooleanrequired
- per_pageintegerrequired
- next_afterinteger | nullrequired
Errors
401Authentication required403Scope/authority denied404Account outside access409Work changed; reload422Invalid query or inactive/non-card account
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/receipt_capture" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/reconciliationsList reconciliations
Sessions for the account, latest statement first. Paginated. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- pageintegerqueryPage (1-based)
- per_pageintegerqueryItems per page
Response · 200 · object[]
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/reconciliations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/reconciliationsStart a reconciliation
Beginning balance = the sum of reconciled lines; lines already cleared on or before the statement date are pre-ticked. One session in progress per account; the date must follow the last finished one. Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reconciliationobjectrequired
- reconciliation.statement_datestring (date)required
- reconciliation.statement_ending_balancestringrequiredDecimal string, 2 dp
Response · 201 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/reconciliations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reconciliation": {
"statement_date": "2026-11-01",
"statement_ending_balance": "0.00"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/registerAccount register
Posted lines on the account's GL account, newest first, with a running balance and the reconcile state (n new, c cleared, y reconciled and locked, v void). Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- fromstring (date)queryFrom date
- tostring (date)queryTo date
- pageintegerqueryPage (1-based)
- per_pageintegerqueryItems per page
Response · 200 · object[]
- journal_line_idintegerrequired
- entry_idintegerrequired
- entry_numberstring | nullrequired
- datestring (date)required
- descriptionstring | nullrequired
- memostring | nullrequired
- source_typestringrequired
- source_idinteger | nullrequired
- bank_transaction_idinteger | nullrequired
- bank_transaction_numberstring | nullrequired
- check_numberstring | nullrequired
- amountstringrequiredDecimal string, 2 dp
- depositstring | nullrequired
- paymentstring | nullrequired
- balancestringrequiredDecimal string, 2 dp
- reconcile_statestringrequiredOne of: n, c, y, v.
- ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/register" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/revealReveal bank numbers
Full account and routing numbers. manage_vendor_banking only; writes a pii_revealed audit event. Not cached. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- account_numberstring | nullrequired
- routing_numberstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/reveal" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/statement_importsList statement imports
Statement files imported into this account, newest first. Paginated (default 100 per page). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- pageintegerqueryPage (1-based)
- per_pageintegerqueryItems per page
Response · 200 · object[]
- idintegerrequired
- bank_account_idintegerrequired
- formatstringrequiredOne of: csv, ofx, bai2, camt053, feed.
- file_namestring | nullrequired
- statement_startstring | null (date)required
- statement_endstring | null (date)required
- opening_balancestring | nullrequired
- closing_balancestring | nullrequired
- line_countintegerrequired
- duplicate_countintegerrequired
- warningsstring[]required
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/statement_imports" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/accounts/{id}/statement_importsImport a statement
Parses CSV (with a column mapping), OFX/QFX, BAI2 or camt.053 through the shared statement parsers. The same file can't be imported twice (409); lines already imported (bank id, else a line hash) are skipped and counted. Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- statement_importobjectrequired
- statement_import.formatstringrequiredOne of: csv, ofx, qfx, bai2, camt053.
- statement_import.file_namestring | null
- statement_import.contentstringrequired
- statement_import.csv_mappingobject
- statement_import.csv_mapping.datestring | integerrequired
- statement_import.csv_mapping.descriptionstring | integerrequired
- statement_import.csv_mapping.amountstring | integer
- statement_import.csv_mapping.debitstring | integer
- statement_import.csv_mapping.creditstring | integer
- statement_import.csv_mapping.referencestring | integer
- statement_import.csv_mapping.check_numberstring | integer
- statement_import.csv_mapping.balancestring | integer
- statement_import.csv_mapping.date_formatstringOne of: YYYYMMDD, MMDDYYYY, MMDDYY, YYMMDD, MM/DD/YYYY, YYYY-MM-DD.
- statement_import.csv_mapping.signstringOne of: deposit_positive, withdrawal_positive.
- statement_import.csv_mapping.has_headerboolean
- statement_import.csv_mapping.skip_rowsinteger
- statement_import.csv_mapping.delimiterstring
- statement_import.positive_pay_optionsobject | nullPositive pay layout: CSV (format csv or omitted: columns, dateFormat, header, statusCodes) or fixed-width (format fixed with template: recordLength, dateFormat, statusCodes, detail/header/trailer fields of source, start, length, align, pad, value).
- statement_import.save_mappingboolean
Response · 201 · object
- idintegerrequired
- bank_account_idintegerrequired
- formatstringrequiredOne of: csv, ofx, bai2, camt053, feed.
- file_namestring | nullrequired
- statement_startstring | null (date)required
- statement_endstring | null (date)required
- opening_balancestring | nullrequired
- closing_balancestring | nullrequired
- line_countintegerrequired
- duplicate_countintegerrequired
- warningsstring[]required
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/accounts/1/statement_imports" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"statement_import": {
"format": "csv",
"content": "string"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/cash_forecastCash forecast
Weekly projection of the cash (non-card) accounts: opening book balance plus postdated cash lines, recurring journals touching cash, and (unless trend=false) the trailing 13-week run rate excluding transfers. Each flow names its source. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)queryDefault today
- weeksintegerquery1–52, default 13
- trendstringqueryInclude run rate One of: true, false.
- open_itemsstringqueryInclude open AP bills (due date), draft payment runs (pay date), open AR (due date plus ar_lag_days) and payroll (unposted runs and each pay group's next regular runs); default true One of: true, false.
- ar_lag_daysintegerqueryDays after the due date AR is expected to collect; default 0
Response · 200 · object
- as_ofstring (date)required
- openingstringrequiredDecimal string, 2 dp
- closingstringrequiredDecimal string, 2 dp
- floorstring | nullrequired
- trailing_netstringrequiredDecimal string, 2 dp
- low_pointobject | nullrequired
- low_point.week_endstring (date)required
- low_point.balancestringrequiredDecimal string, 2 dp
- accountsobject[]required
- accounts[].idintegerrequired
- accounts[].namestringrequired
- weeksobject[]required
- weeks[].week_startstring (date)required
- weeks[].week_endstring (date)required
- weeks[].openingstringrequiredDecimal string, 2 dp
- weeks[].inflowsstringrequiredDecimal string, 2 dp
- weeks[].outflowsstringrequiredDecimal string, 2 dp
- weeks[].netstringrequiredDecimal string, 2 dp
- weeks[].closingstringrequiredDecimal string, 2 dp
- weeks[].below_floorbooleanrequired
- weeks[].flowsobject[]required
- explainobject[]required
- explain[].labelstringrequired
- explain[].valuestringrequired
- explain[].formulastringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/cash_forecast" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/cash_positionCash position
Per account: book, reconciled and cleared balances, outstanding items, last reconciliation and statement, lines to match; totals for cash and cards owed. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)queryDefault today
Response · 200 · object
- as_ofstring (date)required
- totalsobjectrequired
- totals.cashstringrequiredDecimal string, 2 dp
- totals.cards_owedstringrequiredDecimal string, 2 dp
- totals.net_cashstringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.unmatchedintegerrequired
- accountsobject[]required
- accounts[].bank_account_idintegerrequired
- accounts[].namestringrequired
- accounts[].kindstringrequiredOne of: checking, savings, money_market, credit_card, cash.
- accounts[].gl_account_numberstringrequired
- accounts[].account_number_maskedstring | nullrequired
- accounts[].book_balancestringrequiredDecimal string, 2 dp
- accounts[].reconciled_balancestringrequiredDecimal string, 2 dp
- accounts[].cleared_balancestringrequiredDecimal string, 2 dp
- accounts[].outstanding_depositsstringrequiredDecimal string, 2 dp
- accounts[].outstanding_paymentsstringrequiredDecimal string, 2 dp
- accounts[].last_reconciliationobject | nullrequired
- accounts[].reconciliation_in_progress_idinteger | nullrequired
- accounts[].last_statementobject | nullrequired
- accounts[].unmatched_countintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/cash_position" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/checks/{id}/stopStop payment on a check
Marks an issued check in the register (banking, AP or payroll) as stopped; the next positive pay file sends it to the bank with the stop status. The books do not change: void or reissue the check to move the money. release_payments; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- stopobjectrequired
- stop.reasonstringrequired
Response · 200 · object
- idintegerrequired
- check_numberstringrequired
- bank_account_idintegerrequired
- statusstringrequired
- amountstring | nullrequiredNull for a payroll check (net pay stays with payroll).
- payeestring | nullrequiredNull for a payroll check.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Check not found422The check is not issued, or validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/checks/1/stop" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"stop": {
"reason": "string"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/feedsList live bank feed connections
Connections in the grant's entity scope (a connection without an entity is visible to all-entity grants only). enabled is false when feeds are not configured on this server. Entity-wide: a project-scoped grant gets 403. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- enabledbooleanrequired
- connectionsobject[]required
- connections[].idintegerrequired
- connections[].providerstringrequiredOne of: plaid, fake.
- connections[].entity_idinteger | nullrequired
- connections[].institution_namestring | nullrequired
- connections[].statusstringrequiredOne of: active, login_required, expiring, revoked, error, disconnected.
- connections[].status_detailstring | nullrequired
- connections[].healthobjectrequired
- connections[].new_accounts_availablebooleanrequired
- connections[].accountsobject[]required
- connections[].bank_accountsobject[]required
- connections[].last_sync_atstring | null (date-time)required
- connections[].last_success_atstring | null (date-time)required
- connections[].consecutive_failuresintegerrequired
- connections[].last_errorstring | nullrequired
- connections[].last_statsobjectrequiredCounts from the last successful sync: added, modified, removed, pending_skipped, unmapped, before_start, exceptions.
- connections[].created_atstring (date-time)required
- connections[].updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/feedsLink a bank (exchange a Link public token)
Exchanges the provider Link public token and stores the connection; the access token is encrypted, bound to the row and never returned. Needs manage_integrations and bank_reconcile. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- public_tokenstringrequired
- entity_idinteger | null
- institution_namestring | null
Response · 201 · object
- idintegerrequired
- providerstringrequiredOne of: plaid, fake.
- entity_idinteger | nullrequired
- institution_namestring | nullrequired
- statusstringrequiredOne of: active, login_required, expiring, revoked, error, disconnected.
- status_detailstring | nullrequired
- healthobjectrequired
- health.statestringrequiredOne of: live, stale, reconnect, expiring, error, pending, disconnected.
- health.labelstringrequired
- new_accounts_availablebooleanrequired
- accountsobject[]required
- accounts[].idstringrequired
- accounts[].namestringrequired
- accounts[].maskstring | nullrequired
- accounts[].typestringrequired
- accounts[].subtypestring | nullrequired
- accounts[].currencystring | nullrequiredProvider ISO currency; unknown or unofficial currency cannot be mapped.
- bank_accountsobject[]required
- bank_accounts[].idintegerrequired
- bank_accounts[].namestringrequired
- bank_accounts[].feed_account_idstring | nullrequired
- bank_accounts[].start_datestring | null (date)required
- last_sync_atstring | null (date-time)required
- last_success_atstring | null (date-time)required
- consecutive_failuresintegerrequired
- last_errorstring | nullrequired
- last_statsobjectrequiredCounts from the last successful sync: added, modified, removed, pending_skipped, unmapped, before_start, exceptions.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace409Conflict (state, duplicate, already linked or already fed, or the start date reaches reconciled history)422Validation error503Live bank feeds are not configured on this server (PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV), or encryption is not configured
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"public_token": "string"
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}Show a live bank feed connection
Entity-wide: a project-scoped grant gets 403. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- providerstringrequiredOne of: plaid, fake.
- entity_idinteger | nullrequired
- institution_namestring | nullrequired
- statusstringrequiredOne of: active, login_required, expiring, revoked, error, disconnected.
- status_detailstring | nullrequired
- healthobjectrequired
- health.statestringrequiredOne of: live, stale, reconnect, expiring, error, pending, disconnected.
- health.labelstringrequired
- new_accounts_availablebooleanrequired
- accountsobject[]required
- accounts[].idstringrequired
- accounts[].namestringrequired
- accounts[].maskstring | nullrequired
- accounts[].typestringrequired
- accounts[].subtypestring | nullrequired
- accounts[].currencystring | nullrequiredProvider ISO currency; unknown or unofficial currency cannot be mapped.
- bank_accountsobject[]required
- bank_accounts[].idintegerrequired
- bank_accounts[].namestringrequired
- bank_accounts[].feed_account_idstring | nullrequired
- bank_accounts[].start_datestring | null (date)required
- last_sync_atstring | null (date-time)required
- last_success_atstring | null (date-time)required
- consecutive_failuresintegerrequired
- last_errorstring | nullrequired
- last_statsobjectrequiredCounts from the last successful sync: added, modified, removed, pending_skipped, unmapped, before_start, exceptions.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
DELETE/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}Disconnect a live bank feed
Removes the Item at the provider (best effort), forgets the token and cursor, sets status disconnected and unmaps its bank accounts. Statement lines stay. Needs manage_integrations and bank_reconcile. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- providerstringrequiredOne of: plaid, fake.
- entity_idinteger | nullrequired
- institution_namestring | nullrequired
- statusstringrequiredOne of: active, login_required, expiring, revoked, error, disconnected.
- status_detailstring | nullrequired
- healthobjectrequired
- health.statestringrequiredOne of: live, stale, reconnect, expiring, error, pending, disconnected.
- health.labelstringrequired
- new_accounts_availablebooleanrequired
- accountsobject[]required
- accounts[].idstringrequired
- accounts[].namestringrequired
- accounts[].maskstring | nullrequired
- accounts[].typestringrequired
- accounts[].subtypestring | nullrequired
- accounts[].currencystring | nullrequiredProvider ISO currency; unknown or unofficial currency cannot be mapped.
- bank_accountsobject[]required
- bank_accounts[].idintegerrequired
- bank_accounts[].namestringrequired
- bank_accounts[].feed_account_idstring | nullrequired
- bank_accounts[].start_datestring | null (date)required
- last_sync_atstring | null (date-time)required
- last_success_atstring | null (date-time)required
- consecutive_failuresintegerrequired
- last_errorstring | nullrequired
- last_statsobjectrequiredCounts from the last successful sync: added, modified, removed, pending_skipped, unmapped, before_start, exceptions.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
PATCH/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}/accountsMap feed accounts to bank accounts
Map, remap or unmap (bank_account_id null) each provider account. start_date is the first day the feed owns (default: the day after the account's latest statement line, else 30 days ago); it may not be on or before the last finished reconciliation (409). A bank account fed by another connection is refused (409); one outside the connection's entity is 404. Mapping queues a sync. Needs manage_integrations and bank_reconcile. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- mappingsobject[]required
- mappings[].feed_account_idstringrequired
- mappings[].bank_account_idinteger | nullrequired
- mappings[].start_datestring (date)
Response · 200 · object
- idintegerrequired
- providerstringrequiredOne of: plaid, fake.
- entity_idinteger | nullrequired
- institution_namestring | nullrequired
- statusstringrequiredOne of: active, login_required, expiring, revoked, error, disconnected.
- status_detailstring | nullrequired
- healthobjectrequired
- health.statestringrequiredOne of: live, stale, reconnect, expiring, error, pending, disconnected.
- health.labelstringrequired
- new_accounts_availablebooleanrequired
- accountsobject[]required
- accounts[].idstringrequired
- accounts[].namestringrequired
- accounts[].maskstring | nullrequired
- accounts[].typestringrequired
- accounts[].subtypestring | nullrequired
- accounts[].currencystring | nullrequiredProvider ISO currency; unknown or unofficial currency cannot be mapped.
- bank_accountsobject[]required
- bank_accounts[].idintegerrequired
- bank_accounts[].namestringrequired
- bank_accounts[].feed_account_idstring | nullrequired
- bank_accounts[].start_datestring | null (date)required
- last_sync_atstring | null (date-time)required
- last_success_atstring | null (date-time)required
- consecutive_failuresintegerrequired
- last_errorstring | nullrequired
- last_statsobjectrequiredCounts from the last successful sync: added, modified, removed, pending_skipped, unmapped, before_start, exceptions.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found409Conflict (state, duplicate, already linked or already fed, or the start date reaches reconciled history)422Validation error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds/1/accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"mappings": [
{
"feed_account_id": "string",
"bank_account_id": 1
}
]
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/feeds/{id}/syncSync a live bank feed now
Queues a sync job (one per connection per minute; never syncs inline). New posted transactions become statement lines in the matching inbox; pending ones are skipped. Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 202 · object
- job_idintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found409Conflict (state, duplicate, already linked or already fed, or the start date reaches reconciled history)503Live bank feeds are not configured on this server (PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV), or encryption is not configured
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds/1/sync" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/feeds/link_tokenCreate a bank Link token
A provider Link token for a new connection, or update mode (reconnect after login_required, or add accounts) with connection_id. Needs manage_integrations and bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- connection_idinteger
Response · 200 · object
- link_tokenstringrequired
- expires_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found409Conflict (state, duplicate, already linked or already fed, or the start date reaches reconciled history)503Live bank feeds are not configured on this server (PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV), or encryption is not configured
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/feeds/link_token" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"connection_id": 1
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/receipt_reviewsList pending independent card receipt reviews
Requires accounting:read and live bankReconcile. Excludes project-scoped grants and inaccessible, shared or mixed-entity accounts according to the existing bank artifact policy. Scope and independence precede keyset pagination. Includes stale pending submissions for explicit rejection; never mutates financial state. No total count is exposed.
Parameters
- company_idintegerpathrequired
- afterintegerqueryExclusive submission ID cursor from next_after.
- per_pageintegerquery
Response · 200 · object
- itemsobject[]required
- items[].submission_idintegerrequired
- items[].transaction_idintegerrequired
- items[].transaction_numberstringrequired
- items[].line_idintegerrequired
- items[].line_nointeger | nullrequired
- items[].amountstring | nullrequired
- items[].currencystringrequired
- items[].bank_account_namestringrequired
- items[].submitted_atstring (date-time)required
- items[].evidence_typestringrequiredOne of: receipt, exception.
- items[].statusstringrequiredOne of: pending, stale.
- items[].review_urlstringrequiredExact submission anchor on the existing authorized transaction detail.
- items[].attachmentobject | nullrequired
- per_pageintegerrequired
- next_afterinteger | nullrequired
Errors
403Accounting read scope, bankReconcile or entity-wide authority missing.409Eligibility changed while loading; reload the queue.422Invalid cursor or page size.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/receipt_reviews" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Show a reconciliation
The session with its lines (in progress: every candidate with a cleared flag; finished: the locked items) and totals with an explain trace. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409The session links a line that is not a valid bank ledger line for it (another account or tenant, dated after the statement, not posted, or in the wrong reconcile state). Cancel an in-progress session (DELETE) or undo a finished one to recover.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
PATCH/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Tick lines / change the statement balance
clear / unclear journal line ids (n ↔ c) and the statement ending balance, while in progress. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reconciliationobjectrequired
- reconciliation.statement_ending_balancestringDecimal string, 2 dp
- reconciliation.clearinteger[]
- reconciliation.unclearinteger[]
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock). A 409 also means the session links an invalid bank ledger line (another account or tenant, dated after the statement, not posted, or in the wrong reconcile state); cancel it (DELETE) to recover.422Validation error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reconciliation": {}
}'Accounting / Banking
DELETE/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}Cancel an in-progress reconciliation
Drops the ticks; matched lines stay cleared. Requires the accounting:write scope. Also the recovery path for a session with invalid ledger links: those links are dropped without changing the lines they point at, and the audit entry lists them.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/finishFinish a reconciliation
Only at a difference of 0.00, or with adjustment_reason, which posts an adjustment entry (to adjustment_account_id or SUSPENSE). The adjustment is refused (422) above settings.recon_adjustment_limit, or, when that is null, at or above require_approval_above (any difference when both are null): record the difference as a bank transaction, which a second person approves at or above the threshold, clear it, then finish. Every ticked line becomes reconciled (y) and is locked; the database refuses any later change to it outside an undo. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- finishobject
- finish.adjustment_reasonstring
- finish.adjustment_account_idinteger | null
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock). A 409 also means the session links an invalid bank ledger line (another account or tenant, dated after the statement, not posted, or in the wrong reconcile state); cancel it (DELETE) to recover.422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1/finish" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"finish": {}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/reviewReview a finished reconciliation
Independent sign-off of a finished reconciliation by a user with close_period or approve_journal who did not finish it (403 for the finisher). Sets reviewed_by_id and reviewed_at and is audited. 409 when the session is not finished or is already reviewed. Close readiness blocks (reconciliation_unreviewed) on a finished, unreviewed reconciliation dated in the period. No request body. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Not finished, already reviewed, or changed concurrently
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1/review" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/reconciliations/{id}/undoUndo a reconciliation
Controller only (close_period), latest finished session only. Reconciled lines go back to cleared. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- undoobjectrequired
- undo.reasonstringrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- statement_datestring (date)required
- statement_ending_balancestringrequiredDecimal string, 2 dp
- beginning_balancestringrequiredDecimal string, 2 dp
- statusstringrequiredOne of: in_progress, finished, undone.
- cleared_balancestring | nullrequired
- outstanding_depositsstring | nullrequired
- outstanding_paymentsstring | nullrequired
- book_balancestring | nullrequired
- adjustment_entry_idinteger | nullrequired
- adjustment_reasonstring | nullrequired
- started_by_idintegerrequired
- finished_atstring | null (date-time)required
- finished_by_idinteger | nullrequired
- undone_atstring | null (date-time)required
- undone_by_idinteger | nullrequired
- undo_reasonstring | nullrequired
- created_atstring (date-time)required
- totalsobjectrequired
- totals.beginning_balancestringrequiredDecimal string, 2 dp
- totals.cleared_depositsstringrequiredDecimal string, 2 dp
- totals.cleared_paymentsstringrequiredDecimal string, 2 dp
- totals.cleared_balancestringrequiredDecimal string, 2 dp
- totals.statement_ending_balancestringrequiredDecimal string, 2 dp
- totals.differencestringrequiredDecimal string, 2 dp
- totals.outstanding_depositsstringrequiredDecimal string, 2 dp
- totals.outstanding_paymentsstringrequiredDecimal string, 2 dp
- totals.explainobject[]required
- linesobject[]required
- lines[].journal_line_idintegerrequired
- lines[].entry_idintegerrequired
- lines[].entry_numberstring | nullrequired
- lines[].datestring (date)required
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].descriptionstring | nullrequired
- lines[].bank_transaction_idinteger | nullrequired
- lines[].bank_transaction_numberstring | nullrequired
- lines[].check_numberstring | nullrequired
- lines[].clearedbooleanrequired
- lines[].matchedbooleanrequired
- lines[].reconcile_statestringrequiredOne of: n, c, y, v.
- lines[].ap_payment_idinteger | nullrequiredAP payment behind the line (sourced from an AP payment run); check_number and description come from it
- lines[].linkstring | nullrequiredApp path to the source document (bank transaction or AP payment run)
- warningsstring[]requiredFor example: the statement ending balance differs from the closing balance of a statement imported for the same date.
- reviewed_by_idinteger | nullrequiredIndependent reviewer (close_period or approve_journal, never the finisher).
- reviewed_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock). A 409 also means the session links an invalid bank ledger line (another account or tenant, dated after the statement, not posted, or in the wrong reconcile state); undo still succeeds for a finished session and drops those links, naming them in the audit entry.422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/reconciliations/1/undo" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"undo": {
"reason": "string"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/rulesList bank rules
Rules in priority order. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- bank_account_idinteger | nullrequired
- priorityintegerrequired
- is_activebooleanrequired
- directionstringrequiredOne of: in, out, any.
- description_containsstringrequired
- amount_minstring | nullrequired
- amount_maxstring | nullrequired
- account_idintegerrequired
- project_idinteger | nullrequired
- cost_code_idinteger | nullrequired
- vendor_idinteger | nullrequired
- memostring | nullrequired
- times_appliedintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/rules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/rulesCreate a bank rule
Text match (case-insensitive) plus direction and amount band, coding to a postable non-control account. Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- bank_ruleobjectrequired
- bank_rule.namestringrequired
- bank_rule.bank_account_idinteger | null
- bank_rule.priorityinteger
- bank_rule.is_activeboolean
- bank_rule.directionstringOne of: in, out, any.
- bank_rule.description_containsstringrequired
- bank_rule.amount_minstring | null
- bank_rule.amount_maxstring | null
- bank_rule.account_idintegerrequired
- bank_rule.project_idinteger | null
- bank_rule.cost_code_idinteger | null
- bank_rule.cost_type_idinteger | null
- bank_rule.vendor_idinteger | null
- bank_rule.memostring | null
Response · 201 · object
- idintegerrequired
- namestringrequired
- bank_account_idinteger | nullrequired
- priorityintegerrequired
- is_activebooleanrequired
- directionstringrequiredOne of: in, out, any.
- description_containsstringrequired
- amount_minstring | nullrequired
- amount_maxstring | nullrequired
- account_idintegerrequired
- project_idinteger | nullrequired
- cost_code_idinteger | nullrequired
- vendor_idinteger | nullrequired
- memostring | nullrequired
- times_appliedintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/rules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"bank_rule": {
"name": "string",
"description_contains": "string",
"account_id": 1
}
}'Accounting / Banking
PATCH/rest/v1.0/companies/{company_id}/accounting/banking/rules/{id}Update a bank rule
Any rule field. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- bank_ruleobjectrequired
- bank_rule.namestring
- bank_rule.bank_account_idinteger | null
- bank_rule.priorityinteger
- bank_rule.is_activeboolean
- bank_rule.directionstringOne of: in, out, any.
- bank_rule.description_containsstring
- bank_rule.amount_minstring | null
- bank_rule.amount_maxstring | null
- bank_rule.account_idinteger
- bank_rule.project_idinteger | null
- bank_rule.cost_code_idinteger | null
- bank_rule.cost_type_idinteger | null
- bank_rule.vendor_idinteger | null
- bank_rule.memostring | null
Response · 200 · object
- idintegerrequired
- namestringrequired
- bank_account_idinteger | nullrequired
- priorityintegerrequired
- is_activebooleanrequired
- directionstringrequiredOne of: in, out, any.
- description_containsstringrequired
- amount_minstring | nullrequired
- amount_maxstring | nullrequired
- account_idintegerrequired
- project_idinteger | nullrequired
- cost_code_idinteger | nullrequired
- vendor_idinteger | nullrequired
- memostring | nullrequired
- times_appliedintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found422Validation error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/rules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"bank_rule": {}
}'Accounting / Banking
DELETE/rest/v1.0/companies/{company_id}/accounting/banking/rules/{id}Delete a bank rule
Lines it matched keep their match. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/rules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/create_transactionCreate from a statement line
Records the document the bank line represents (deposit/withdrawal, or card charge/credit), posts it, matches it, and optionally saves a bank rule from the coding. At or above the journal approval threshold the document is held as pending_approval and the line stays unmatched until a second person approves it (approval matches it); creating again from that line is refused with 409. A single line defaults to the full amount. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- createobjectrequired
- create.payeestring | null
- create.memostring | null
- create.rule_idinteger | null
- create.linesobject[]required
- create.lines[].account_idintegerrequired
- create.lines[].amountstringDecimal string, 2 dp
- create.lines[].memostring | null
- create.lines[].project_idinteger | null
- create.lines[].cost_code_idinteger | null
- create.lines[].cost_type_idinteger | null
- create.lines[].vendor_idinteger | null
- create.lines[].customer_idinteger | null
- create.lines[].equipment_idinteger | null
- create.lines[].has_receiptboolean
- create.lines[].reportable_1099booleanChecks and withdrawals to a 1099 vendor: false keeps the line off the 1099. Default true.
- create.save_ruleobject
- create.save_rule.namestringrequired
- create.save_rule.description_containsstringrequired
Response · 201 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/create_transaction" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"create": {
"lines": [
{
"account_id": 1
}
]
}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/feed_note/clearMark a bank feed note reviewed
Clears the note the live feed left on a matched line it changed or removed. Needs bank_reconcile. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- import_idintegerrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- descriptionstringrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- bank_txn_idstring | nullrequired
- type_codestring | nullrequired
- statusstringrequiredOne of: unmatched, matched, ignored.
- match_sourcestring | nullrequired
- match_confidencestring | nullrequired
- rule_idinteger | nullrequired
- matched_atstring | null (date-time)required
- journal_line_idsinteger[]required
- feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (project-scoped grants are refused), wrong company, or read-only workspace404Not found
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/feed_note/clear" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/ignoreIgnore a statement line
Moves an unmatched line out of the inbox. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- import_idintegerrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- descriptionstringrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- bank_txn_idstring | nullrequired
- type_codestring | nullrequired
- statusstringrequiredOne of: unmatched, matched, ignored.
- match_sourcestring | nullrequired
- match_confidencestring | nullrequired
- rule_idinteger | nullrequired
- matched_atstring | null (date-time)required
- journal_line_idsinteger[]required
- feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/ignore" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/matchMatch a statement line
Matches one or more book lines (posted, on the account, not reconciled or void, not matched elsewhere) whose total equals the bank amount to the cent. Book lines become cleared. Needs bank_reconcile. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- matchobjectrequired
- match.journal_line_idsinteger[]required
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- import_idintegerrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- descriptionstringrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- bank_txn_idstring | nullrequired
- type_codestring | nullrequired
- statusstringrequiredOne of: unmatched, matched, ignored.
- match_sourcestring | nullrequired
- match_confidencestring | nullrequired
- rule_idinteger | nullrequired
- matched_atstring | null (date-time)required
- journal_line_idsinteger[]required
- feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/match" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"match": {
"journal_line_ids": []
}
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/restoreRestore an ignored statement line
Puts the line back in the inbox. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- import_idintegerrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- descriptionstringrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- bank_txn_idstring | nullrequired
- type_codestring | nullrequired
- statusstringrequiredOne of: unmatched, matched, ignored.
- match_sourcestring | nullrequired
- match_confidencestring | nullrequired
- rule_idinteger | nullrequired
- matched_atstring | null (date-time)required
- journal_line_idsinteger[]required
- feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/restore" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/statement_lines/{id}/unmatchUnmatch a statement line
Refused with 409 when a matched book line is reconciled (the lock). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bank_account_idintegerrequired
- import_idintegerrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- descriptionstringrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- bank_txn_idstring | nullrequired
- type_codestring | nullrequired
- statusstringrequiredOne of: unmatched, matched, ignored.
- match_sourcestring | nullrequired
- match_confidencestring | nullrequired
- rule_idinteger | nullrequired
- matched_atstring | null (date-time)required
- journal_line_idsinteger[]required
- feed_notestring | nullrequiredSet when the live feed changed or removed this line after it was matched; cleared by Mark reviewed or unmatch.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/statement_lines/1/unmatch" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/transactionsList cash documents
Deposits, checks, withdrawals, transfers and card charges/credits. Filters: filters[bank_account_id], filters[kind], filters[status]; from/to; search (number, payee, memo, check #). Paginated. Delta sync: updated_since and/or cursor return changes in ascending (updated_at, id) order with Next-Cursor. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)queryFrom date
- tostring (date)queryTo date
- searchstringquerySearch
- pageintegerqueryPage (1-based)
- per_pageintegerqueryItems per page
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation error
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactionsRecord and post a cash document
Posts one CM journal entry (idempotent on the document id), or holds the document as pending_approval with no posting until a second person approves it (POST .../approve): checks always (release by a different release_payments user), deposits, withdrawals and card documents at or above the journal approval threshold. Transfers between the company's own accounts follow the transfer policy (settings transfer_approval_cross_entity, default true, and transfer_approval_above, null = require_approval_above when set): a transfer between entities or at or above the amount is held for release by a different release_payments user; others post at once. Checks take the account's next check number unless one is given, need a payee, and need release_payments; the others need bank_reconcile. Coding lines must total the amount and can't use control accounts or other bank registers. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- bank_transactionobjectrequired
- bank_transaction.bank_account_idintegerrequired
- bank_transaction.kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- bank_transaction.datestring (date)required
- bank_transaction.amountstringrequiredDecimal string, 2 dp
- bank_transaction.payeestring | null
- bank_transaction.payee_vendor_idinteger | null
- bank_transaction.memostring | null
- bank_transaction.referencestring | null
- bank_transaction.check_numberstring | null
- bank_transaction.to_bank_account_idinteger | null
- bank_transaction.linesobject[]
- bank_transaction.lines[].account_idintegerrequired
- bank_transaction.lines[].amountstringrequiredDecimal string, 2 dp
- bank_transaction.lines[].memostring | null
- bank_transaction.lines[].project_idinteger | null
- bank_transaction.lines[].cost_code_idinteger | null
- bank_transaction.lines[].cost_type_idinteger | null
- bank_transaction.lines[].vendor_idinteger | null
- bank_transaction.lines[].customer_idinteger | null
- bank_transaction.lines[].equipment_idinteger | null
- bank_transaction.lines[].has_receiptboolean
- bank_transaction.lines[].reportable_1099booleanChecks and withdrawals to a 1099 vendor: false keeps the line off the 1099. Default true.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"bank_transaction": {
"bank_account_id": 1,
"kind": "deposit",
"date": "2026-11-01",
"amount": "0.00"
}
}'Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}Show a cash document
One document with its coding lines; card charges flag receipt_missing above the account's threshold. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/approveRelease or approve a pending cash document
Posts a cash document that is waiting for a second person (status pending_approval): a check or transfer needs release_payments, any other kind approve_journal. Refused with 403 for the user who created it (segregation of duties) and 409 when it is not pending. Checks are always held for release; deposits, withdrawals and card documents are held at or above the journal approval threshold (settings.require_approval_above; null holds every one). Approval registers the check for positive pay and matches the statement line it was created from. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/approve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/attachmentsList attachments on a bank transaction
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/attachmentsAttach a file to a bank transaction
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 bank_reconcile and the parent's entity scope. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/check_printCheck print data
MICR line, amount in words and stub for a check. Decrypts the bank numbers: release_payments only, audited, not cached. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- check_numberstringrequired
- datestring (date)required
- amountstringrequired
- amount_numericstringrequired
- amount_wordsstringrequired
- payee_linestringrequired
- payee_addressstring[]required
- memostring | nullrequired
- legendstring | nullrequired
- microbjectrequired
- micr.textstringrequired
- micr.font_textstringrequired
- stubobject[]required
- stub[].referencestringrequired
- stub[].datestring (date)
- stub[].grossstringrequired
- stub[].discountstringrequired
- stub[].netstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/check_print" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
GET/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidenceRead retained receipt evidence under bank-account scope
Read only. Requires accounting:read token scope and view access to the card account. Lists the card charge lines with their latest submission status and full submission history; never mutates financial state.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- transaction_idintegerrequired
- attachmentsobject[]required
- attachments[].idintegerrequired
- attachments[].namestringrequired
- linesobject[]required
- lines[].line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].legacy_has_receiptbooleanrequiredUnverified legacy assertion; independent of reviewed evidence.
- lines[].statusstringrequiredOne of: unsubmitted, pending, verified, exception_approved, rejected, stale.
- lines[].receipt_requiredbooleanrequired
- lines[].historyobject[]required
Errors
403Token scope, grant or independence refused.404Source, account, line or attachment not accessible.409Stale evidence, pending submission or conflicting retry.422Invalid input or non-card transaction.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/receipt_evidence" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidenceSubmit line evidence for independent review
Requires accounting:write token scope and bankReconcile on the card account. Attaches an uploaded receipt (or an exception reason) to one card charge line for independent review. request_key in the body makes retries safe: the same key and evidence returns the first submission, a different payload under the same key is refused (409). Creates no posting and does not change approval, void or reconciliation state.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- request_keystring (uuid)requiredSame actor and exact payload replay the prior submission; reused with a different payload returns 409.
- line_idintegerrequired
- attachment_idinteger | nullrequired
- exception_reasonstring | nullrequired
Response · 201 · object
- submission_idintegerrequired
Errors
403Token scope, grant or independence refused.404Source, account, line or attachment not accessible.409Stale evidence, pending submission or conflicting retry.422Invalid input or non-card transaction.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/receipt_evidence" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"request_key": "00000000-0000-4000-8000-000000000000",
"line_id": 1,
"attachment_id": 1,
"exception_reason": "string"
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/receipt_evidence/reviewRecord immutable independent review; exact reviewer/outcome/reason retries replay
Requires accounting:write token scope and bankReconcile on the card account. The reviewer must be independent of the charge creator, the submitter and the uploader. Decisions are immutable: an exact retry returns the recorded decision, anything else is refused (409). Creates no posting.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- submission_idintegerrequired
- outcomestringrequiredOne of: verified, exception_approved, rejected.
- reasonstringrequired
Response · 200 · object
- decision_idintegerrequired
- outcomestringrequiredOne of: verified, exception_approved, rejected.
Errors
403Token scope, grant or independence refused.404Source, account, line or attachment not accessible.409Stale evidence, pending submission or conflicting retry.422Invalid input or non-card transaction.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/receipt_evidence/review" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"submission_id": 1,
"outcome": "verified",
"reason": "string"
}'Accounting / Banking
POST/rest/v1.0/companies/{company_id}/accounting/banking/transactions/{id}/voidVoid a cash document
Posts the reversing entry on the void date (an open period; a check from a closed month voids in the current one) and flags both bank lines void. Refused with 409 when the bank line is reconciled (the lock) or matched to a statement line. Requires the accounting:write scope. A pending_approval document is voided without any posting (withdrawn or rejected).
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: deposit, check, withdrawal, transfer, card_charge, card_credit.
- statusstringrequiredOne of: pending_approval, posted, void.
- bank_account_idintegerrequired
- bank_account_namestringrequired
- datestring (date)required
- amountstringrequiredDecimal string, 2 dp
- payeestring | nullrequired
- payee_vendor_idinteger | nullrequired
- memostring | nullrequired
- referencestring | nullrequired
- check_numberstring | nullrequired
- to_bank_account_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- void_journal_entry_idinteger | nullrequired
- void_datestring | null (date)required
- void_reasonstring | nullrequired
- voided_atstring | null (date-time)required
- statement_line_idinteger | nullrequired
- approved_by_idinteger | nullrequiredThe second person who released the check or approved the document; null when posted below the threshold.
- approved_atstring | null (date-time)required
- positive_pay_issued_atstring | null (date-time)required
- positive_pay_void_atstring | null (date-time)required
- receipt_missingbooleanrequired
- linesobject[]required
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].amountstringrequiredDecimal string, 2 dp
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].vendor_idinteger | nullrequired
- lines[].customer_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].has_receiptbooleanrequired
- lines[].reportable_1099boolean
- lines[].receipt_missingbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found409Conflict (state, duplicate, or the reconciliation lock)422Validation error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/banking/transactions/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'