Chart of Accounts
Maintain the accounts used by every accounting app. 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 Chart of Accounts guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/accountsList GL accounts - POST
/rest/v1.0/companies/{company_id}/accounting/accountsCreate a GL account - GET
/rest/v1.0/companies/{company_id}/accounting/accounts/{id}Show a GL account - PATCH
/rest/v1.0/companies/{company_id}/accounting/accounts/{id}Update a GL account - POST
/rest/v1.0/companies/{company_id}/accounting/accounts/apply_templateApply the construction chart of accounts - GET
/rest/v1.0/companies/{company_id}/accounting/accounts/packsList industry chart-of-accounts packs - POST
/rest/v1.0/companies/{company_id}/accounting/accounts/packs/applyApply a pack - GET
/rest/v1.0/companies/{company_id}/accounting/accounts/packs/previewPreview a pack merge - GET
/rest/v1.0/companies/{company_id}/accounting/accounts/treeChart of accounts tree
Accounting / Chart of Accounts
GET/rest/v1.0/companies/{company_id}/accounting/accountsList GL accounts
The chart of accounts in number order. Filter with filters[type], filters[is_active], filters[is_postable], or search (number prefix or name). Delta sync: updated_since and/or cursor return changes in ascending (updated_at, id) order with Next-Cursor. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- searchstringqueryAccount number prefix or name fragment
- filters[type]stringqueryComma-separated account types
- filters[is_active]anyqueryActive accounts only, or inactive only One of: true, false.
- filters[is_postable]anyqueryPostable or header accounts One of: true, false.
- pageintegerquery
- per_pageintegerquery
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- namestringrequired
- descriptionstring | nullrequired
- typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- subtypestring | nullrequired
- normal_balanceanyrequiredOne of: debit, credit.
- parent_idinteger | nullrequired
- is_postablebooleanrequired
- is_activebooleanrequired
- system_rolestring | nullrequiredControl-account role, unique per company (e.g. AP_CONTROL)
- is_controlbooleanrequired
- require_projectbooleanrequired
- require_cost_codebooleanrequired
- require_cost_typebooleanrequired
- job_cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden, null.
- currencystringrequired
- cash_flow_categoryanyrequiredOne of: operating, investing, financing, null.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Unknown filter value
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Chart of Accounts
POST/rest/v1.0/companies/{company_id}/accounting/accountsCreate a GL account
Adds an account. Normal balance and cash-flow category default from the type. Header accounts (is_postable: false) group others in the tree and never take postings. Job-cost accounts set job_cost_type so lines with a project also write the job cost subledger. Needs manage_coa. 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
- accountobjectrequired
- account.numberstringrequired
- account.namestringrequired
- account.descriptionstring | null
- account.typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- account.subtypestring | null
- account.normal_balanceanyOne of: debit, credit.
- account.parent_idinteger | null
- account.is_postableboolean
- account.is_activeboolean
- account.is_controlboolean
- account.require_projectboolean
- account.require_cost_codeboolean
- account.require_cost_typeboolean
- account.job_cost_typeanyOne of: labor, material, subcontract, equipment, other, burden, null.
- account.currencystring
- account.cash_flow_categoryanyOne of: operating, investing, financing, null.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- namestringrequired
- descriptionstring | nullrequired
- typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- subtypestring | nullrequired
- normal_balanceanyrequiredOne of: debit, credit.
- parent_idinteger | nullrequired
- is_postablebooleanrequired
- is_activebooleanrequired
- system_rolestring | nullrequiredControl-account role, unique per company (e.g. AP_CONTROL)
- is_controlbooleanrequired
- require_projectbooleanrequired
- require_cost_codebooleanrequired
- require_cost_typebooleanrequired
- job_cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden, null.
- currencystringrequired
- cash_flow_categoryanyrequiredOne of: operating, investing, financing, null.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"account": {
"number": "string",
"name": "string",
"type": "bank"
}
}'Accounting / Chart of Accounts
GET/rest/v1.0/companies/{company_id}/accounting/accounts/{id}Show a GL account
One account of this company. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- namestringrequired
- descriptionstring | nullrequired
- typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- subtypestring | nullrequired
- normal_balanceanyrequiredOne of: debit, credit.
- parent_idinteger | nullrequired
- is_postablebooleanrequired
- is_activebooleanrequired
- system_rolestring | nullrequiredControl-account role, unique per company (e.g. AP_CONTROL)
- is_controlbooleanrequired
- require_projectbooleanrequired
- require_cost_codebooleanrequired
- require_cost_typebooleanrequired
- job_cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden, null.
- currencystringrequired
- cash_flow_categoryanyrequiredOne of: operating, investing, financing, null.
- 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 in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Chart of Accounts
PATCH/rest/v1.0/companies/{company_id}/accounting/accounts/{id}Update a GL account
Edits an account. Once it has journal activity its type, normal balance and postable flag are fixed (reclassify with a journal entry instead). Needs manage_coa. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- accountobjectrequired
- account.numberstring
- account.namestring
- account.descriptionstring | null
- account.typeanyOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- account.subtypestring | null
- account.normal_balanceanyOne of: debit, credit.
- account.parent_idinteger | null
- account.is_postableboolean
- account.is_activeboolean
- account.is_controlboolean
- account.require_projectboolean
- account.require_cost_codeboolean
- account.require_cost_typeboolean
- account.job_cost_typeanyOne of: labor, material, subcontract, equipment, other, burden, null.
- account.currencystring
- account.cash_flow_categoryanyOne of: operating, investing, financing, null.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- namestringrequired
- descriptionstring | nullrequired
- typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- subtypestring | nullrequired
- normal_balanceanyrequiredOne of: debit, credit.
- parent_idinteger | nullrequired
- is_postablebooleanrequired
- is_activebooleanrequired
- system_rolestring | nullrequiredControl-account role, unique per company (e.g. AP_CONTROL)
- is_controlbooleanrequired
- require_projectbooleanrequired
- require_cost_codebooleanrequired
- require_cost_typebooleanrequired
- job_cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden, null.
- currencystringrequired
- cash_flow_categoryanyrequiredOne of: operating, investing, financing, null.
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"account": {}
}'Accounting / Chart of Accounts
POST/rest/v1.0/companies/{company_id}/accounting/accounts/apply_templateApply the construction chart of accounts
Adds the numbered construction template (cash, retainage, contract assets and liabilities for under/over billings, job cost by cost type, payroll liabilities, accumulated depreciation, equity and system roles). Only missing account numbers are added, so it is safe to repeat. Needs manage_coa. 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
- templateobjectrequired
- template.nameanyrequired
Response · 200 · object
- templateanyrequired
- accounts_createdintegerrequired
- accounts_totalintegerrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/apply_template" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"template": {
"name": null
}
}'Accounting / Chart of Accounts
GET/rest/v1.0/companies/{company_id}/accounting/accounts/packsList industry chart-of-accounts packs
General contractor, specialty contractor, home builder, heavy civil and construction management packs: the accounts each adds to the construction template, suggested dimensions and default job cost accounts, plus the pack this company last applied. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- appliedstring | nullrequired
- packsobject[]required
- packs[].keystringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- packs[].namestringrequired
- packs[].descriptionstringrequired
- packs[].recommended_editionstringrequiredOne of: essentials, professional, enterprise.
- packs[].accountsobject[]required
- packs[].dimensionsobject[]required
- packs[].cost_typesobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/packs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Chart of Accounts
POST/rest/v1.0/companies/{company_id}/accounting/accounts/packs/applyApply a pack
Creates the pack's accounts the company does not have; never renumbers, renames, retypes, remaps or removes an existing account. A company with accounts must send the preview's confirm_hash (422 pack_preview_required without it, 409 pack_preview_stale when the chart changed). create_dimensions adds the suggested dimensions as optional. Audited (pack_applied). Needs manage_coa on an unrestricted grant. 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
- packobjectrequired
- pack.keystringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- pack.confirm_hashstring
- pack.create_dimensionsboolean
Response · 201 · object
- packstringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- hashstringrequired
- createdstring[]required
- keptstring[]required
- rolesobject[]required
- roles[].rolestringrequired
- roles[].statusstringrequiredOne of: kept, assigned, unmapped.
- roles[].accountstring | nullrequired
- roles[].notestringrequired
- dimensions_createdstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA409The chart changed since the preview, or an Idempotency-Key conflict422Preview required, or an invalid body
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/packs/apply" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"pack": {
"key": "general_contractor"
}
}'Accounting / Chart of Accounts
GET/rest/v1.0/companies/{company_id}/accounting/accounts/packs/previewPreview a pack merge
The non-destructive merge of pack into this company's chart: accounts to create (numbers it does not have), existing accounts kept unchanged (posted or not), role mappings kept, assigned or left for manual mapping, dimensions to create, and the hash to confirm with. Needs manage_coa. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- packstringqueryOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
Response · 200 · object
- packstringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- hashstringrequired
- createobject[]required
- create[].numberstringrequired
- create[].namestringrequired
- create[].typestringrequired
- create[].headerbooleanrequired
- create[].parentstring | nullrequired
- create[].rolestring | nullrequired
- create[].notestring | nullrequired
- keptobject[]required
- kept[].numberstringrequired
- kept[].namestringrequired
- kept[].packNamestringrequired
- kept[].differsbooleanrequired
- kept[].postedbooleanrequired
- rolesobject[]required
- roles[].rolestringrequired
- roles[].statusstringrequiredOne of: kept, assigned, unmapped.
- roles[].accountstring | nullrequired
- roles[].notestringrequired
- dimensionsobject[]required
- dimensions[].codestringrequired
- dimensions[].statusstringrequiredOne of: create, exists.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA422Unknown or missing pack
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/accounts/packs/preview" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Chart of Accounts
GET/rest/v1.0/companies/{company_id}/accounting/accounts/treeChart of accounts tree
Every account nested under its parent header account, roots in number order. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- namestringrequired
- descriptionstring | nullrequired
- typeanyrequiredOne of: bank, cash, accounts_receivable, retainage_receivable, contract_asset, other_current_asset, inventory, fixed_asset, accumulated_depreciation, other_asset, accounts_payable, retainage_payable, contract_liability, credit_card, payroll_liability, sales_tax_payable, other_current_liability, long_term_liability, equity, retained_earnings, income, other_income, cost_of_revenue, expense, other_expense.
- subtypestring | nullrequired
- normal_balanceanyrequiredOne of: debit, credit.
- parent_idinteger | nullrequired
- is_postablebooleanrequired
- is_activebooleanrequired
- system_rolestring | nullrequiredControl-account role, unique per company (e.g. AP_CONTROL)
- is_controlbooleanrequired
- require_projectbooleanrequired
- require_cost_codebooleanrequired
- require_cost_typebooleanrequired
- job_cost_typeanyrequiredOne of: labor, material, subcontract, equipment, other, burden, null.
- currencystringrequired
- cash_flow_categoryanyrequiredOne of: operating, investing, financing, null.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- childrenobject[]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/accounts/tree" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"