Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · Setup and administration

Accounting Imports

Stage supported imports and connections, validate and reconcile before cutover. 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 Accounting Imports guide for the workflow.

11 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/integrations/connectionsList ERP connections with health and recent sync runs
  2. POST /rest/v1.0/companies/{company_id}/accounting/integrations/connectionsCreate an ERP connection (manageIntegrations)
  3. POST /rest/v1.0/companies/{company_id}/accounting/integrations/connections/{id}/syncQueue a sync pull (live API connections); it stages coa, vendors and open_ap import runs
  4. GET /rest/v1.0/companies/{company_id}/accounting/integrations/exports/journalsExport posted journals as an ERP import file
  5. GET /rest/v1.0/companies/{company_id}/accounting/integrations/importsList imports
  6. POST /rest/v1.0/companies/{company_id}/accounting/integrations/importsUpload CSV and persist validation preview
  7. GET /rest/v1.0/companies/{company_id}/accounting/integrations/imports/{id}Read preview, results and history
  8. POST /rest/v1.0/companies/{company_id}/accounting/integrations/imports/{id}Map, reconcile, approve/apply or reverse an imported entry
  9. GET /rest/v1.0/companies/{company_id}/accounting/integrations/inboxIntegration error inbox: sync run errors and blocked or failed import runs
  10. POST /rest/v1.0/companies/{company_id}/accounting/integrations/parallel_runParallel run: compare a source system trial balance with the posted trial balance on the same date
  11. GET /rest/v1.0/companies/{company_id}/accounting/integrations/sync_runs/{id}Get a sync run

Accounting / Accounting Imports

GET /rest/v1.0/companies/{company_id}/accounting/integrations/connections

List ERP connections with health and recent sync runs

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • provider
    anyrequired
    One of: qbo, spectrum, sage300cre, intacct, foundation, csv.
  • provider_label
    stringrequired
  • mode
    anyrequired
    live_api pulls over the vendor API (QuickBooks Online only); file_import sources sync by uploading their export files. One of: live_api, file_import.
  • name
    stringrequired
  • status
    anyrequired
    One of: active, error, disconnected.
  • external_tenant
    string | nullrequired
  • authorized
    booleanrequired
    OAuth tokens are stored (encrypted, row-bound); they are never returned.
  • config
    objectrequired
  • last_sync_at
    string | nullrequired
  • last_error
    string | nullrequired
  • health
    anyrequired
    One of: ok, error, needs_authorization, never_synced.
  • runs
    object[]required
    Latest five sync runs.
  • runs[].id
    integerrequired
  • runs[].status
    anyrequired
    One of: queued, running, succeeded, failed.
  • runs[].started_at
    string | nullrequired
  • runs[].finished_at
    string | nullrequired
  • runs[].stats
    objectrequired
  • runs[].errors
    object[]required
  • runs[].import_run_ids
    integer[]required
    Staged import runs; they apply through the normal two-person import review.
  • runs[].created_at
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 422Validation failed

Example request

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

Accounting / Accounting Imports

POST /rest/v1.0/companies/{company_id}/accounting/integrations/connections

Create an ERP connection (manageIntegrations)

Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • entity_id
    integerrequired
  • provider
    anyrequired
    One of: qbo, spectrum, sage300cre, intacct, foundation, csv.
  • name
    stringrequired
  • external_tenant
    string
    QBO realm id.
  • config
    object
  • config.environment
    any
    One of: production, sandbox.
  • config.as_of
    string (date)
    Cut-over date; without it a sync stages masters only.
  • config.retainage_payable_account_ids
    string[]

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • provider
    anyrequired
    One of: qbo, spectrum, sage300cre, intacct, foundation, csv.
  • provider_label
    stringrequired
  • mode
    anyrequired
    live_api pulls over the vendor API (QuickBooks Online only); file_import sources sync by uploading their export files. One of: live_api, file_import.
  • name
    stringrequired
  • status
    anyrequired
    One of: active, error, disconnected.
  • external_tenant
    string | nullrequired
  • authorized
    booleanrequired
    OAuth tokens are stored (encrypted, row-bound); they are never returned.
  • config
    objectrequired
  • last_sync_at
    string | nullrequired
  • last_error
    string | nullrequired
  • health
    anyrequired
    One of: ok, error, needs_authorization, never_synced.
  • runs
    object[]required
    Latest five sync runs.
  • runs[].id
    integerrequired
  • runs[].status
    anyrequired
    One of: queued, running, succeeded, failed.
  • runs[].started_at
    string | nullrequired
  • runs[].finished_at
    string | nullrequired
  • runs[].stats
    objectrequired
  • runs[].errors
    object[]required
  • runs[].import_run_ids
    integer[]required
    Staged import runs; they apply through the normal two-person import review.
  • runs[].created_at
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/integrations/connections" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": 1,
  "provider": "qbo",
  "name": "string"
}'

Accounting / Accounting Imports

POST /rest/v1.0/companies/{company_id}/accounting/integrations/connections/{id}/sync

Queue a sync pull (live API connections); it stages coa, vendors and open_ap import runs

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 202 · object

  • id
    integerrequired
  • status
    anyrequired
    One of: queued, running, succeeded, failed.
  • started_at
    string | nullrequired
  • finished_at
    string | nullrequired
  • stats
    objectrequired
  • errors
    object[]required
  • errors[].entity
    stringrequired
  • errors[].id
    string | nullrequired
  • errors[].message
    stringrequired
  • import_run_ids
    integer[]required
    Staged import runs; they apply through the normal two-person import review.
  • created_at
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 422Validation failed

Example request

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

Accounting / Accounting Imports

GET /rest/v1.0/companies/{company_id}/accounting/integrations/exports/journals

Export posted journals as an ERP import file

Needs view_ledger; a project-scoped (project_manager_view) grant gets 403. Posted entries (reversed originals and their reversals) with posting dates in [from, to], optionally one journal (journal=AP exports AP) and one entity, in the caller's entity scope. The debit_credit and signed_amount files end with Entity (code) and Department columns, since one file can mix entities. Job-coded lines carry Project (project number, else name), Cost Code (full code) and Cost Type (code); the QBO template's Name column carries the line's vendor or customer, Location the entity code and Class the project (or department, qbo_class). Every entry balances before the file is written; text cells are formula-escaped and amounts are exact. Up to 20,000 lines; rate limited per user across all app instances (429 with Retry-After). Each export is audited. A target export that races another export to the same target is 409; export again. Requires the accounting:read scope; with target, the accounting:write scope (it records what was sent).

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • from
    string (date)query
    Posting date range; required unless since_last or batch_id is sent.
  • to
    string (date)query
    Posting date range; required unless since_last or batch_id is sent.
  • format
    anyquery
    One of: debit_credit, signed_amount, qbo_journal.
  • journal
    anyquery
    One of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
  • entity_id
    integerquery
  • target
    stringquery
    A named feed (another ERP running alongside). Each posted entry is exported to a target once: entries already sent to it are left out, and the new ones are recorded as an export batch (X-Export-Batch-Id). Needs the accounting:write scope and the manageIntegrations grant (403 otherwise); a read-only workspace is refused.
  • since_last
    anyquery
    With target: every posted entry not yet exported to it, whatever its posting date, oldest post first, up to the line cap (call again for the rest). An entry posted late with a back date is never missed. One of: true, false.
  • batch_id
    integerquery
    Download a recorded batch again (for a lost response), exactly as it was exported: its stored format and qbo_class are used, not the ones sent.
  • qbo_class
    anyquery
    What the qbo_journal Class column carries. Location is the entity code. One of: project, department, none.

Response · 200 · string

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No ledger access or wrong company
  • 422Invalid range, entity outside scope, or more than 20,000 lines
  • 429Export rate limit

Example request

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

Accounting / Accounting Imports

GET /rest/v1.0/companies/{company_id}/accounting/integrations/imports

List imports

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id Import runs carry opening balances and open AP/AR documents, so project-scoped (project_manager_view) grants get 403 on every import read.
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
  • company_id
    stringpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • source_namespace
    stringrequired
  • kind
    anyrequired
    One of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
  • status
    anyrequired
    One of: queued, blocked, preview, reconciled, applying, applied.
  • created_at
    stringrequired
  • prepared_by_id
    integerrequired

Errors

  • 401Authentication required
  • 403Permission, entity scope or segregation of duties denied
  • 404Import not found in company
  • 409Preview changed; reload and reconcile
  • 413Request too large
  • 422Validation or reconciliation failed
  • 500Operation failed; no partial import committed

Example request

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

Accounting / Accounting Imports

POST /rest/v1.0/companies/{company_id}/accounting/integrations/imports

Upload CSV and persist validation preview

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id Import runs carry opening balances and open AP/AR documents, so project-scoped (project_manager_view) grants get 403 on every import read.
    integerpathrequired
  • company_id
    stringpathrequired

Request body

  • entity_id
    integerrequired
  • source_namespace
    stringrequired
  • kind
    anyrequired
    One of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
  • as_of
    string (date)
  • file
    string (binary)required
  • profile
    any
    File-import connector profile. foundation flattens a Foundation report export (title block, repeated page headers, totals, grouped party/job, trailing-sign negatives) before preview. One of: flat, foundation.

Response · 201 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • source_namespace
    stringrequired
  • kind
    anyrequired
    One of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
  • status
    anyrequired
    One of: queued, blocked, preview, reconciled, applying, applied.
  • created_at
    stringrequired
  • as_of
    string | nullrequired
  • source_hash
    stringrequired
  • preview_hash
    stringrequired
  • mapping
    objectrequired
  • mapping.columns
    objectrequired
  • mapping.accounts
    objectrequired
  • mapping.parties
    objectrequired
    Open AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
  • mapping.basis
    anyrequired
    Opening TB basis. Cash: no AR/AP in the TB; open documents come on through an accrual conversion entry. One of: accrual, cash.
  • mapping.balance_includes_retainage
    booleanrequired
    Open AP/AR: the Balance column already includes open retainage.
  • mapping.dimensions
    objectrequired
    Journal and open-document dimensions: source key (csv:project:..., csv:cost_codes:...@<project id>, csv:cost_type:...) to local id. Unmapped keys resolve through this namespace's recorded AcctExternalRef rows, then an exact unique match (project number or name, cost code within the project, cost type code/name/base type, party name).
  • preview
    objectrequired
  • preview.headers
    string[]required
  • preview.columns
    objectrequired
  • preview.fields
    string[]required
  • preview.errors
    string[]required
  • preview.debit
    stringrequired
  • preview.credit
    stringrequired
  • preview.currencies
    object[]
    Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
  • preview.sourceHash
    stringrequired
  • preview.currency
    stringrequired
  • preview.sourceAccounts
    object[]required
  • preview.entries
    object[]required
  • preview.reconciliation
    objectrequired
  • preview.totals
    objectrequired
  • preview.openDocuments
    object[]required
    Open AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
  • preview.records
    object[]required
    Master records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
  • preview.tieOut
    null | object[]required
    Opening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
  • preview.sourceParties
    object[]required
  • preview.sourceDimensions
    object[]required
  • preview.chunks
    object[]
  • preview.counts
    object
  • preview.errorCount
    integer
  • prepared_by_id
    integerrequired
  • reconciled_by_id
    integer | nullrequired
  • approved_by_id
    integer | nullrequired
  • applied_at
    string | nullrequired
  • last_error
    string | nullrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].external_key
    stringrequired
  • items[].journal_entry_id
    integer | nullrequired
  • items[].reused
    booleanrequired
  • items[].journal_status
    string | nullrequired
  • items[].reversal_entry_id
    integer | nullrequired
  • items[].kind
    stringrequired
    document: an open AP bill/credit or AR invoice; record: an account, party or cost code; journal: an imported journal One of: document, record, journal.
  • items[].label
    stringrequired
  • items[].local_type
    string | nullrequired
    AcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
  • items[].local_id
    integer | nullrequired
  • history
    object[]required
  • history[].id
    integerrequired
  • history[].action
    stringrequired
  • history[].actor_id
    integerrequired
  • history[].created_at
    stringrequired
  • history[].summary
    stringrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • revision
    integerrequired
  • background
    booleanrequired
    Files over 200 rows or 256 KiB (vendors, customers, cost_codes, open_ap, open_ar, employee_ytd) preview and apply on the accounting_import job in chunks of 500 rows.
  • row_count
    integerrequired
  • chunk_count
    integerrequired
  • chunks_done
    integerrequired
    Resume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
  • item_count
    integerrequired
    items lists at most the first 1,000.
  • job
    null | objectrequired
  • job.status
    anyrequired
    One of: queued, running, completed, failed, cancelled.
  • job.progress
    integerrequired
  • job.attempts
    integerrequired
  • job.max_attempts
    integerrequired

Errors

  • 401Authentication required
  • 403Permission, entity scope or segregation of duties denied
  • 404Import not found in company
  • 409Preview changed; reload and reconcile
  • 413Request too large
  • 422Validation or reconciliation failed
  • 500Operation failed; no partial import committed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/integrations/imports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": 1,
  "source_namespace": "string",
  "kind": "opening_tb",
  "file": "string"
}'

Accounting / Accounting Imports

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

Read preview, results and history

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • source_namespace
    stringrequired
  • kind
    anyrequired
    One of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
  • status
    anyrequired
    One of: queued, blocked, preview, reconciled, applying, applied.
  • created_at
    stringrequired
  • as_of
    string | nullrequired
  • source_hash
    stringrequired
  • preview_hash
    stringrequired
  • mapping
    objectrequired
  • mapping.columns
    objectrequired
  • mapping.accounts
    objectrequired
  • mapping.parties
    objectrequired
    Open AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
  • mapping.basis
    anyrequired
    Opening TB basis. Cash: no AR/AP in the TB; open documents come on through an accrual conversion entry. One of: accrual, cash.
  • mapping.balance_includes_retainage
    booleanrequired
    Open AP/AR: the Balance column already includes open retainage.
  • mapping.dimensions
    objectrequired
    Journal and open-document dimensions: source key (csv:project:..., csv:cost_codes:...@<project id>, csv:cost_type:...) to local id. Unmapped keys resolve through this namespace's recorded AcctExternalRef rows, then an exact unique match (project number or name, cost code within the project, cost type code/name/base type, party name).
  • preview
    objectrequired
  • preview.headers
    string[]required
  • preview.columns
    objectrequired
  • preview.fields
    string[]required
  • preview.errors
    string[]required
  • preview.debit
    stringrequired
  • preview.credit
    stringrequired
  • preview.currencies
    object[]
    Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
  • preview.sourceHash
    stringrequired
  • preview.currency
    stringrequired
  • preview.sourceAccounts
    object[]required
  • preview.entries
    object[]required
  • preview.reconciliation
    objectrequired
  • preview.totals
    objectrequired
  • preview.openDocuments
    object[]required
    Open AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
  • preview.records
    object[]required
    Master records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
  • preview.tieOut
    null | object[]required
    Opening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
  • preview.sourceParties
    object[]required
  • preview.sourceDimensions
    object[]required
  • preview.chunks
    object[]
  • preview.counts
    object
  • preview.errorCount
    integer
  • prepared_by_id
    integerrequired
  • reconciled_by_id
    integer | nullrequired
  • approved_by_id
    integer | nullrequired
  • applied_at
    string | nullrequired
  • last_error
    string | nullrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].external_key
    stringrequired
  • items[].journal_entry_id
    integer | nullrequired
  • items[].reused
    booleanrequired
  • items[].journal_status
    string | nullrequired
  • items[].reversal_entry_id
    integer | nullrequired
  • items[].kind
    stringrequired
    document: an open AP bill/credit or AR invoice; record: an account, party or cost code; journal: an imported journal One of: document, record, journal.
  • items[].label
    stringrequired
  • items[].local_type
    string | nullrequired
    AcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
  • items[].local_id
    integer | nullrequired
  • history
    object[]required
  • history[].id
    integerrequired
  • history[].action
    stringrequired
  • history[].actor_id
    integerrequired
  • history[].created_at
    stringrequired
  • history[].summary
    stringrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • revision
    integerrequired
  • background
    booleanrequired
    Files over 200 rows or 256 KiB (vendors, customers, cost_codes, open_ap, open_ar, employee_ytd) preview and apply on the accounting_import job in chunks of 500 rows.
  • row_count
    integerrequired
  • chunk_count
    integerrequired
  • chunks_done
    integerrequired
    Resume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
  • item_count
    integerrequired
    items lists at most the first 1,000.
  • job
    null | objectrequired
  • job.status
    anyrequired
    One of: queued, running, completed, failed, cancelled.
  • job.progress
    integerrequired
  • job.attempts
    integerrequired
  • job.max_attempts
    integerrequired

Errors

  • 401Authentication required
  • 403Permission, entity scope or segregation of duties denied
  • 404Import not found in company
  • 409Preview changed; reload and reconcile
  • 413Request too large
  • 422Validation or reconciliation failed
  • 500Operation failed; no partial import committed

Example request

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

Accounting / Accounting Imports

POST /rest/v1.0/companies/{company_id}/accounting/integrations/imports/{id}

Map, reconcile, approve/apply or reverse an imported entry

Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Request body

  • action
    anyrequired
  • preview_hash
    stringrequired
  • mapping
    objectrequired
  • mapping.columns
    objectrequired
  • mapping.accounts
    objectrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • source_namespace
    stringrequired
  • kind
    anyrequired
    One of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
  • status
    anyrequired
    One of: queued, blocked, preview, reconciled, applying, applied.
  • created_at
    stringrequired
  • as_of
    string | nullrequired
  • source_hash
    stringrequired
  • preview_hash
    stringrequired
  • mapping
    objectrequired
  • mapping.columns
    objectrequired
  • mapping.accounts
    objectrequired
  • mapping.parties
    objectrequired
    Open AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
  • mapping.basis
    anyrequired
    Opening TB basis. Cash: no AR/AP in the TB; open documents come on through an accrual conversion entry. One of: accrual, cash.
  • mapping.balance_includes_retainage
    booleanrequired
    Open AP/AR: the Balance column already includes open retainage.
  • mapping.dimensions
    objectrequired
    Journal and open-document dimensions: source key (csv:project:..., csv:cost_codes:...@<project id>, csv:cost_type:...) to local id. Unmapped keys resolve through this namespace's recorded AcctExternalRef rows, then an exact unique match (project number or name, cost code within the project, cost type code/name/base type, party name).
  • preview
    objectrequired
  • preview.headers
    string[]required
  • preview.columns
    objectrequired
  • preview.fields
    string[]required
  • preview.errors
    string[]required
  • preview.debit
    stringrequired
  • preview.credit
    stringrequired
  • preview.currencies
    object[]
    Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
  • preview.sourceHash
    stringrequired
  • preview.currency
    stringrequired
  • preview.sourceAccounts
    object[]required
  • preview.entries
    object[]required
  • preview.reconciliation
    objectrequired
  • preview.totals
    objectrequired
  • preview.openDocuments
    object[]required
    Open AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
  • preview.records
    object[]required
    Master records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
  • preview.tieOut
    null | object[]required
    Opening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
  • preview.sourceParties
    object[]required
  • preview.sourceDimensions
    object[]required
  • preview.chunks
    object[]
  • preview.counts
    object
  • preview.errorCount
    integer
  • prepared_by_id
    integerrequired
  • reconciled_by_id
    integer | nullrequired
  • approved_by_id
    integer | nullrequired
  • applied_at
    string | nullrequired
  • last_error
    string | nullrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].external_key
    stringrequired
  • items[].journal_entry_id
    integer | nullrequired
  • items[].reused
    booleanrequired
  • items[].journal_status
    string | nullrequired
  • items[].reversal_entry_id
    integer | nullrequired
  • items[].kind
    stringrequired
    document: an open AP bill/credit or AR invoice; record: an account, party or cost code; journal: an imported journal One of: document, record, journal.
  • items[].label
    stringrequired
  • items[].local_type
    string | nullrequired
    AcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
  • items[].local_id
    integer | nullrequired
  • history
    object[]required
  • history[].id
    integerrequired
  • history[].action
    stringrequired
  • history[].actor_id
    integerrequired
  • history[].created_at
    stringrequired
  • history[].summary
    stringrequired
  • last_edited_by_id
    integerrequired
  • contributor_ids
    integer[]required
  • revision
    integerrequired
  • background
    booleanrequired
    Files over 200 rows or 256 KiB (vendors, customers, cost_codes, open_ap, open_ar, employee_ytd) preview and apply on the accounting_import job in chunks of 500 rows.
  • row_count
    integerrequired
  • chunk_count
    integerrequired
  • chunks_done
    integerrequired
    Resume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
  • item_count
    integerrequired
    items lists at most the first 1,000.
  • job
    null | objectrequired
  • job.status
    anyrequired
    One of: queued, running, completed, failed, cancelled.
  • job.progress
    integerrequired
  • job.attempts
    integerrequired
  • job.max_attempts
    integerrequired

Errors

  • 401Authentication required
  • 403Permission, entity scope or segregation of duties denied
  • 404Import not found in company
  • 409Preview changed; reload and reconcile
  • 413Request too large
  • 422Validation or reconciliation failed
  • 500Operation failed; no partial import committed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/integrations/imports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "action": null,
  "preview_hash": "string",
  "mapping": {
    "columns": {},
    "accounts": {}
  }
}'

Accounting / Accounting Imports

GET /rest/v1.0/companies/{company_id}/accounting/integrations/inbox

Integration error inbox: sync run errors and blocked or failed import runs

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • key
    stringrequired
  • source
    stringrequired
  • sync_run_id
    integer | nullrequired
  • import_id
    integer | nullrequired
  • message
    stringrequired
  • at
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 422Validation failed

Example request

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

Accounting / Accounting Imports

POST /rest/v1.0/companies/{company_id}/accounting/integrations/parallel_run

Parallel run: compare a source system trial balance with the posted trial balance on the same date

Requires the accounting:read scope and a ledger viewer grant over the entity. Read only: nothing is posted. The CSV uses the opening_tb layout (account with debit/credit or a signed balance). Source accounts map by the saved opening_tb mapping of source_namespace, else by account number. Balances are cumulative posted balances through as_of in the entity.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • entity_id
    integerrequired
  • as_of
    string (date)required
  • csv
    stringrequired
  • source_namespace
    string

Response · 200 · object

  • key
    anyrequired
  • title
    stringrequired
  • subtitle
    stringrequired
  • params
    objectrequired
  • columns
    any[]required
  • rows
    any[]required
  • checks
    object[]required
  • checks[].label
    stringrequired
  • checks[].ok
    booleanrequired
  • checks[].difference
    stringrequired
  • checks[].detail
    string | null
  • notes
    string[]required
  • explain
    any[]required
  • generatedAt
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 413Request body too large
  • 422Validation failed (including an unbalanced or unreadable source trial balance)

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/integrations/parallel_run" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": 1,
  "as_of": "2026-11-01",
  "csv": "string"
}'

Accounting / Accounting Imports

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

Get a sync run

Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • status
    anyrequired
    One of: queued, running, succeeded, failed.
  • started_at
    string | nullrequired
  • finished_at
    string | nullrequired
  • stats
    objectrequired
  • errors
    object[]required
  • errors[].entity
    stringrequired
  • errors[].id
    string | nullrequired
  • errors[].message
    stringrequired
  • import_run_ids
    integer[]required
    Staged import runs; they apply through the normal two-person import review.
  • created_at
    stringrequired

Errors

  • 401Authentication required
  • 403Permission or entity scope denied
  • 404Not found in company
  • 422Validation failed

Example request

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

Ask the OS

Reading this page

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

Suggested

    AI · may be imperfect · sample data where shown

    Open file