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.
- GET
/rest/v1.0/companies/{company_id}/accounting/integrations/connectionsList ERP connections with health and recent sync runs - POST
/rest/v1.0/companies/{company_id}/accounting/integrations/connectionsCreate an ERP connection (manageIntegrations) - 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 - GET
/rest/v1.0/companies/{company_id}/accounting/integrations/exports/journalsExport posted journals as an ERP import file - GET
/rest/v1.0/companies/{company_id}/accounting/integrations/importsList imports - POST
/rest/v1.0/companies/{company_id}/accounting/integrations/importsUpload CSV and persist validation preview - GET
/rest/v1.0/companies/{company_id}/accounting/integrations/imports/{id}Read preview, results and history - POST
/rest/v1.0/companies/{company_id}/accounting/integrations/imports/{id}Map, reconcile, approve/apply or reverse an imported entry - GET
/rest/v1.0/companies/{company_id}/accounting/integrations/inboxIntegration error inbox: sync run errors and blocked or failed import runs - 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 - 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/connectionsList ERP connections with health and recent sync runs
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- provideranyrequiredOne of: qbo, spectrum, sage300cre, intacct, foundation, csv.
- provider_labelstringrequired
- modeanyrequiredlive_api pulls over the vendor API (QuickBooks Online only); file_import sources sync by uploading their export files. One of: live_api, file_import.
- namestringrequired
- statusanyrequiredOne of: active, error, disconnected.
- external_tenantstring | nullrequired
- authorizedbooleanrequiredOAuth tokens are stored (encrypted, row-bound); they are never returned.
- configobjectrequired
- last_sync_atstring | nullrequired
- last_errorstring | nullrequired
- healthanyrequiredOne of: ok, error, needs_authorization, never_synced.
- runsobject[]requiredLatest five sync runs.
- runs[].idintegerrequired
- runs[].statusanyrequiredOne of: queued, running, succeeded, failed.
- runs[].started_atstring | nullrequired
- runs[].finished_atstring | nullrequired
- runs[].statsobjectrequired
- runs[].errorsobject[]required
- runs[].import_run_idsinteger[]requiredStaged import runs; they apply through the normal two-person import review.
- runs[].created_atstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company422Validation failed
Example request
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/connectionsCreate an ERP connection (manageIntegrations)
Requires the accounting:write scope.
Parameters
- 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
- entity_idintegerrequired
- provideranyrequiredOne of: qbo, spectrum, sage300cre, intacct, foundation, csv.
- namestringrequired
- external_tenantstringQBO realm id.
- configobject
- config.environmentanyOne of: production, sandbox.
- config.as_ofstring (date)Cut-over date; without it a sync stages masters only.
- config.retainage_payable_account_idsstring[]
Response · 201 · object
- idintegerrequired
- entity_idintegerrequired
- provideranyrequiredOne of: qbo, spectrum, sage300cre, intacct, foundation, csv.
- provider_labelstringrequired
- modeanyrequiredlive_api pulls over the vendor API (QuickBooks Online only); file_import sources sync by uploading their export files. One of: live_api, file_import.
- namestringrequired
- statusanyrequiredOne of: active, error, disconnected.
- external_tenantstring | nullrequired
- authorizedbooleanrequiredOAuth tokens are stored (encrypted, row-bound); they are never returned.
- configobjectrequired
- last_sync_atstring | nullrequired
- last_errorstring | nullrequired
- healthanyrequiredOne of: ok, error, needs_authorization, never_synced.
- runsobject[]requiredLatest five sync runs.
- runs[].idintegerrequired
- runs[].statusanyrequiredOne of: queued, running, succeeded, failed.
- runs[].started_atstring | nullrequired
- runs[].finished_atstring | nullrequired
- runs[].statsobjectrequired
- runs[].errorsobject[]required
- runs[].import_run_idsinteger[]requiredStaged import runs; they apply through the normal two-person import review.
- runs[].created_atstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company422Validation failed
Example request
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}/syncQueue a sync pull (live API connections); it stages coa, vendors and open_ap import runs
Requires the accounting:write scope.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 202 · object
- idintegerrequired
- statusanyrequiredOne of: queued, running, succeeded, failed.
- started_atstring | nullrequired
- finished_atstring | nullrequired
- statsobjectrequired
- errorsobject[]required
- errors[].entitystringrequired
- errors[].idstring | nullrequired
- errors[].messagestringrequired
- import_run_idsinteger[]requiredStaged import runs; they apply through the normal two-person import review.
- created_atstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company422Validation failed
Example request
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/journalsExport 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).
Parameters
- company_idintegerpathrequired
- fromstring (date)queryPosting date range; required unless since_last or batch_id is sent.
- tostring (date)queryPosting date range; required unless since_last or batch_id is sent.
- formatanyqueryOne of: debit_credit, signed_amount, qbo_journal.
- journalanyqueryOne of: GJ, AP, AR, PR, CM, JC, FA, CL, IC, WIP.
- entity_idintegerquery
- targetstringqueryA 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_lastanyqueryWith 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_idintegerqueryDownload 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_classanyqueryWhat 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 token403No ledger access or wrong company422Invalid range, entity outside scope, or more than 20,000 lines429Export rate limit
Example request
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/importsList imports
Requires the accounting:read scope.
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
- pageintegerquery
- per_pageintegerquery
- company_idstringpathrequired
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- source_namespacestringrequired
- kindanyrequiredOne of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
- statusanyrequiredOne of: queued, blocked, preview, reconciled, applying, applied.
- created_atstringrequired
- prepared_by_idintegerrequired
Errors
401Authentication required403Permission, entity scope or segregation of duties denied404Import not found in company409Preview changed; reload and reconcile413Request too large422Validation or reconciliation failed500Operation failed; no partial import committed
Example request
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/importsUpload CSV and persist validation preview
Requires the accounting:write scope.
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_idstringpathrequired
Request body
- entity_idintegerrequired
- source_namespacestringrequired
- kindanyrequiredOne of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
- as_ofstring (date)
- filestring (binary)required
- profileanyFile-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
- idintegerrequired
- entity_idintegerrequired
- source_namespacestringrequired
- kindanyrequiredOne of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
- statusanyrequiredOne of: queued, blocked, preview, reconciled, applying, applied.
- created_atstringrequired
- as_ofstring | nullrequired
- source_hashstringrequired
- preview_hashstringrequired
- mappingobjectrequired
- mapping.columnsobjectrequired
- mapping.accountsobjectrequired
- mapping.partiesobjectrequiredOpen AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
- mapping.basisanyrequiredOpening 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_retainagebooleanrequiredOpen AP/AR: the Balance column already includes open retainage.
- mapping.dimensionsobjectrequiredJournal 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).
- previewobjectrequired
- preview.headersstring[]required
- preview.columnsobjectrequired
- preview.fieldsstring[]required
- preview.errorsstring[]required
- preview.debitstringrequired
- preview.creditstringrequired
- preview.currenciesobject[]Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
- preview.sourceHashstringrequired
- preview.currencystringrequired
- preview.sourceAccountsobject[]required
- preview.entriesobject[]required
- preview.reconciliationobjectrequired
- preview.totalsobjectrequired
- preview.openDocumentsobject[]requiredOpen AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
- preview.recordsobject[]requiredMaster records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
- preview.tieOutnull | object[]requiredOpening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
- preview.sourcePartiesobject[]required
- preview.sourceDimensionsobject[]required
- preview.chunksobject[]
- preview.countsobject
- preview.errorCountinteger
- prepared_by_idintegerrequired
- reconciled_by_idinteger | nullrequired
- approved_by_idinteger | nullrequired
- applied_atstring | nullrequired
- last_errorstring | nullrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].external_keystringrequired
- items[].journal_entry_idinteger | nullrequired
- items[].reusedbooleanrequired
- items[].journal_statusstring | nullrequired
- items[].reversal_entry_idinteger | nullrequired
- items[].kindstringrequireddocument: 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[].labelstringrequired
- items[].local_typestring | nullrequiredAcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
- items[].local_idinteger | nullrequired
- historyobject[]required
- history[].idintegerrequired
- history[].actionstringrequired
- history[].actor_idintegerrequired
- history[].created_atstringrequired
- history[].summarystringrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]required
- revisionintegerrequired
- backgroundbooleanrequiredFiles 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_countintegerrequired
- chunk_countintegerrequired
- chunks_doneintegerrequiredResume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
- item_countintegerrequireditems lists at most the first 1,000.
- jobnull | objectrequired
- job.statusanyrequiredOne of: queued, running, completed, failed, cancelled.
- job.progressintegerrequired
- job.attemptsintegerrequired
- job.max_attemptsintegerrequired
Errors
401Authentication required403Permission, entity scope or segregation of duties denied404Import not found in company409Preview changed; reload and reconcile413Request too large422Validation or reconciliation failed500Operation failed; no partial import committed
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- source_namespacestringrequired
- kindanyrequiredOne of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
- statusanyrequiredOne of: queued, blocked, preview, reconciled, applying, applied.
- created_atstringrequired
- as_ofstring | nullrequired
- source_hashstringrequired
- preview_hashstringrequired
- mappingobjectrequired
- mapping.columnsobjectrequired
- mapping.accountsobjectrequired
- mapping.partiesobjectrequiredOpen AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
- mapping.basisanyrequiredOpening 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_retainagebooleanrequiredOpen AP/AR: the Balance column already includes open retainage.
- mapping.dimensionsobjectrequiredJournal 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).
- previewobjectrequired
- preview.headersstring[]required
- preview.columnsobjectrequired
- preview.fieldsstring[]required
- preview.errorsstring[]required
- preview.debitstringrequired
- preview.creditstringrequired
- preview.currenciesobject[]Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
- preview.sourceHashstringrequired
- preview.currencystringrequired
- preview.sourceAccountsobject[]required
- preview.entriesobject[]required
- preview.reconciliationobjectrequired
- preview.totalsobjectrequired
- preview.openDocumentsobject[]requiredOpen AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
- preview.recordsobject[]requiredMaster records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
- preview.tieOutnull | object[]requiredOpening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
- preview.sourcePartiesobject[]required
- preview.sourceDimensionsobject[]required
- preview.chunksobject[]
- preview.countsobject
- preview.errorCountinteger
- prepared_by_idintegerrequired
- reconciled_by_idinteger | nullrequired
- approved_by_idinteger | nullrequired
- applied_atstring | nullrequired
- last_errorstring | nullrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].external_keystringrequired
- items[].journal_entry_idinteger | nullrequired
- items[].reusedbooleanrequired
- items[].journal_statusstring | nullrequired
- items[].reversal_entry_idinteger | nullrequired
- items[].kindstringrequireddocument: 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[].labelstringrequired
- items[].local_typestring | nullrequiredAcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
- items[].local_idinteger | nullrequired
- historyobject[]required
- history[].idintegerrequired
- history[].actionstringrequired
- history[].actor_idintegerrequired
- history[].created_atstringrequired
- history[].summarystringrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]required
- revisionintegerrequired
- backgroundbooleanrequiredFiles 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_countintegerrequired
- chunk_countintegerrequired
- chunks_doneintegerrequiredResume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
- item_countintegerrequireditems lists at most the first 1,000.
- jobnull | objectrequired
- job.statusanyrequiredOne of: queued, running, completed, failed, cancelled.
- job.progressintegerrequired
- job.attemptsintegerrequired
- job.max_attemptsintegerrequired
Errors
401Authentication required403Permission, entity scope or segregation of duties denied404Import not found in company409Preview changed; reload and reconcile413Request too large422Validation or reconciliation failed500Operation failed; no partial import committed
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Request body
- actionanyrequired
- preview_hashstringrequired
- mappingobjectrequired
- mapping.columnsobjectrequired
- mapping.accountsobjectrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- source_namespacestringrequired
- kindanyrequiredOne of: opening_tb, journal, open_ap, open_ar, coa, vendors, customers, cost_codes, employee_ytd.
- statusanyrequiredOne of: queued, blocked, preview, reconciled, applying, applied.
- created_atstringrequired
- as_ofstring | nullrequired
- source_hashstringrequired
- preview_hashstringrequired
- mappingobjectrequired
- mapping.columnsobjectrequired
- mapping.accountsobjectrequired
- mapping.partiesobjectrequiredOpen AP/AR: source party key to vendor id; unmapped parties match an active vendor by exact name.
- mapping.basisanyrequiredOpening 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_retainagebooleanrequiredOpen AP/AR: the Balance column already includes open retainage.
- mapping.dimensionsobjectrequiredJournal 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).
- previewobjectrequired
- preview.headersstring[]required
- preview.columnsobjectrequired
- preview.fieldsstring[]required
- preview.errorsstring[]required
- preview.debitstringrequired
- preview.creditstringrequired
- preview.currenciesobject[]Rows that state a currency (opening TB, open AP/AR); each must be the entity functional currency.
- preview.sourceHashstringrequired
- preview.currencystringrequired
- preview.sourceAccountsobject[]required
- preview.entriesobject[]required
- preview.reconciliationobjectrequired
- preview.totalsobjectrequired
- preview.openDocumentsobject[]requiredOpen AP/AR documents to post (one AP bill/credit or AR invoice each, coded to OPENING_BALANCE_EQUITY).
- preview.recordsobject[]requiredMaster records (accounts, vendors/customers, standard cost codes) to create; existingId means an identical record is reused.
- preview.tieOutnull | object[]requiredOpening TB (accrual): each control role against the imported open documents; any non-zero difference blocks apply.
- preview.sourcePartiesobject[]required
- preview.sourceDimensionsobject[]required
- preview.chunksobject[]
- preview.countsobject
- preview.errorCountinteger
- prepared_by_idintegerrequired
- reconciled_by_idinteger | nullrequired
- approved_by_idinteger | nullrequired
- applied_atstring | nullrequired
- last_errorstring | nullrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].external_keystringrequired
- items[].journal_entry_idinteger | nullrequired
- items[].reusedbooleanrequired
- items[].journal_statusstring | nullrequired
- items[].reversal_entry_idinteger | nullrequired
- items[].kindstringrequireddocument: 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[].labelstringrequired
- items[].local_typestring | nullrequiredAcctApBill, AcctArInvoice, AcctAccount, Vendor or StandardCostCode
- items[].local_idinteger | nullrequired
- historyobject[]required
- history[].idintegerrequired
- history[].actionstringrequired
- history[].actor_idintegerrequired
- history[].created_atstringrequired
- history[].summarystringrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]required
- revisionintegerrequired
- backgroundbooleanrequiredFiles 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_countintegerrequired
- chunk_countintegerrequired
- chunks_doneintegerrequiredResume cursor: each chunk commits with its records and this counter, so a killed worker resumes without duplicates.
- item_countintegerrequireditems lists at most the first 1,000.
- jobnull | objectrequired
- job.statusanyrequiredOne of: queued, running, completed, failed, cancelled.
- job.progressintegerrequired
- job.attemptsintegerrequired
- job.max_attemptsintegerrequired
Errors
401Authentication required403Permission, entity scope or segregation of duties denied404Import not found in company409Preview changed; reload and reconcile413Request too large422Validation or reconciliation failed500Operation failed; no partial import committed
Example request
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/inboxIntegration error inbox: sync run errors and blocked or failed import runs
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequired
Response · 200 · object[]
- keystringrequired
- sourcestringrequired
- sync_run_idinteger | nullrequired
- import_idinteger | nullrequired
- messagestringrequired
- atstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company422Validation failed
Example request
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_runParallel 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.
Parameters
- company_idintegerpathrequired
Request body
- entity_idintegerrequired
- as_ofstring (date)required
- csvstringrequired
- source_namespacestring
Response · 200 · object
- keyanyrequired
- titlestringrequired
- subtitlestringrequired
- paramsobjectrequired
- columnsany[]required
- rowsany[]required
- checksobject[]required
- checks[].labelstringrequired
- checks[].okbooleanrequired
- checks[].differencestringrequired
- checks[].detailstring | null
- notesstring[]required
- explainany[]required
- generatedAtstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company413Request body too large422Validation failed (including an unbalanced or unreadable source trial balance)
Example request
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.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- statusanyrequiredOne of: queued, running, succeeded, failed.
- started_atstring | nullrequired
- finished_atstring | nullrequired
- statsobjectrequired
- errorsobject[]required
- errors[].entitystringrequired
- errors[].idstring | nullrequired
- errors[].messagestringrequired
- import_run_idsinteger[]requiredStaged import runs; they apply through the normal two-person import review.
- created_atstringrequired
Errors
401Authentication required403Permission or entity scope denied404Not found in company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/integrations/sync_runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"