Esc

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

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.

9 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/accountsList GL accounts
  2. POST /rest/v1.0/companies/{company_id}/accounting/accountsCreate a GL account
  3. GET /rest/v1.0/companies/{company_id}/accounting/accounts/{id}Show a GL account
  4. PATCH /rest/v1.0/companies/{company_id}/accounting/accounts/{id}Update a GL account
  5. POST /rest/v1.0/companies/{company_id}/accounting/accounts/apply_templateApply the construction chart of accounts
  6. GET /rest/v1.0/companies/{company_id}/accounting/accounts/packsList industry chart-of-accounts packs
  7. POST /rest/v1.0/companies/{company_id}/accounting/accounts/packs/applyApply a pack
  8. GET /rest/v1.0/companies/{company_id}/accounting/accounts/packs/previewPreview a pack merge
  9. 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/accounts

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • search
    stringquery
    Account number prefix or name fragment
  • filters[type]
    stringquery
    Comma-separated account types
  • filters[is_active]
    anyquery
    Active accounts only, or inactive only One of: true, false.
  • filters[is_postable]
    anyquery
    Postable or header accounts One of: true, false.
  • page
    integerquery
  • per_page
    integerquery
  • updated_since
    string (date-time)query
    Delta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
  • cursor
    stringquery
    Opaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • type
    anyrequired
    One 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.
  • subtype
    string | nullrequired
  • normal_balance
    anyrequired
    One of: debit, credit.
  • parent_id
    integer | nullrequired
  • is_postable
    booleanrequired
  • is_active
    booleanrequired
  • system_role
    string | nullrequired
    Control-account role, unique per company (e.g. AP_CONTROL)
  • is_control
    booleanrequired
  • require_project
    booleanrequired
  • require_cost_code
    booleanrequired
  • require_cost_type
    booleanrequired
  • job_cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden, null.
  • currency
    stringrequired
  • cash_flow_category
    anyrequired
    One of: operating, investing, financing, null.
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

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

Example request

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

Accounting / Chart of Accounts

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

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

v1.0Implemented

Parameters

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

Request body

  • account
    objectrequired
  • account.number
    stringrequired
  • account.name
    stringrequired
  • account.description
    string | null
  • account.type
    anyrequired
    One 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.subtype
    string | null
  • account.normal_balance
    any
    One of: debit, credit.
  • account.parent_id
    integer | null
  • account.is_postable
    boolean
  • account.is_active
    boolean
  • account.is_control
    boolean
  • account.require_project
    boolean
  • account.require_cost_code
    boolean
  • account.require_cost_type
    boolean
  • account.job_cost_type
    any
    One of: labor, material, subcontract, equipment, other, burden, null.
  • account.currency
    string
  • account.cash_flow_category
    any
    One of: operating, investing, financing, null.

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • type
    anyrequired
    One 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.
  • subtype
    string | nullrequired
  • normal_balance
    anyrequired
    One of: debit, credit.
  • parent_id
    integer | nullrequired
  • is_postable
    booleanrequired
  • is_active
    booleanrequired
  • system_role
    string | nullrequired
    Control-account role, unique per company (e.g. AP_CONTROL)
  • is_control
    booleanrequired
  • require_project
    booleanrequired
  • require_cost_code
    booleanrequired
  • require_cost_type
    booleanrequired
  • job_cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden, null.
  • currency
    stringrequired
  • cash_flow_category
    anyrequired
    One of: operating, investing, financing, null.
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • type
    anyrequired
    One 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.
  • subtype
    string | nullrequired
  • normal_balance
    anyrequired
    One of: debit, credit.
  • parent_id
    integer | nullrequired
  • is_postable
    booleanrequired
  • is_active
    booleanrequired
  • system_role
    string | nullrequired
    Control-account role, unique per company (e.g. AP_CONTROL)
  • is_control
    booleanrequired
  • require_project
    booleanrequired
  • require_cost_code
    booleanrequired
  • require_cost_type
    booleanrequired
  • job_cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden, null.
  • currency
    stringrequired
  • cash_flow_category
    anyrequired
    One of: operating, investing, financing, null.
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

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

Example request

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

v1.0Implemented

Parameters

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

Request body

  • account
    objectrequired
  • account.number
    string
  • account.name
    string
  • account.description
    string | null
  • account.type
    any
    One 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.subtype
    string | null
  • account.normal_balance
    any
    One of: debit, credit.
  • account.parent_id
    integer | null
  • account.is_postable
    boolean
  • account.is_active
    boolean
  • account.is_control
    boolean
  • account.require_project
    boolean
  • account.require_cost_code
    boolean
  • account.require_cost_type
    boolean
  • account.job_cost_type
    any
    One of: labor, material, subcontract, equipment, other, burden, null.
  • account.currency
    string
  • account.cash_flow_category
    any
    One of: operating, investing, financing, null.

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • type
    anyrequired
    One 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.
  • subtype
    string | nullrequired
  • normal_balance
    anyrequired
    One of: debit, credit.
  • parent_id
    integer | nullrequired
  • is_postable
    booleanrequired
  • is_active
    booleanrequired
  • system_role
    string | nullrequired
    Control-account role, unique per company (e.g. AP_CONTROL)
  • is_control
    booleanrequired
  • require_project
    booleanrequired
  • require_cost_code
    booleanrequired
  • require_cost_type
    booleanrequired
  • job_cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden, null.
  • currency
    stringrequired
  • cash_flow_category
    anyrequired
    One of: operating, investing, financing, null.
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • template
    objectrequired
  • template.name
    anyrequired

Response · 200 · object

  • template
    anyrequired
  • accounts_created
    integerrequired
  • accounts_total
    integerrequired

Errors

  • 400Malformed JSON body, or the request was refused by a business rule (message list)
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • applied
    string | nullrequired
  • packs
    object[]required
  • packs[].key
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • packs[].name
    stringrequired
  • packs[].description
    stringrequired
  • packs[].recommended_edition
    stringrequired
    One of: essentials, professional, enterprise.
  • packs[].accounts
    object[]required
  • packs[].dimensions
    object[]required
  • packs[].cost_types
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No 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

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

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

v1.0Implemented

Parameters

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

Request body

  • pack
    objectrequired
  • pack.key
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • pack.confirm_hash
    string
  • pack.create_dimensions
    boolean

Response · 201 · object

  • pack
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • hash
    stringrequired
  • created
    string[]required
  • kept
    string[]required
  • roles
    object[]required
  • roles[].role
    stringrequired
  • roles[].status
    stringrequired
    One of: kept, assigned, unmapped.
  • roles[].account
    string | nullrequired
  • roles[].note
    stringrequired
  • dimensions_created
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 409The chart changed since the preview, or an Idempotency-Key conflict
  • 422Preview required, or an invalid body

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • pack
    stringquery
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.

Response · 200 · object

  • pack
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • hash
    stringrequired
  • create
    object[]required
  • create[].number
    stringrequired
  • create[].name
    stringrequired
  • create[].type
    stringrequired
  • create[].header
    booleanrequired
  • create[].parent
    string | nullrequired
  • create[].role
    string | nullrequired
  • create[].note
    string | nullrequired
  • kept
    object[]required
  • kept[].number
    stringrequired
  • kept[].name
    stringrequired
  • kept[].packName
    stringrequired
  • kept[].differs
    booleanrequired
  • kept[].posted
    booleanrequired
  • roles
    object[]required
  • roles[].role
    stringrequired
  • roles[].status
    stringrequired
    One of: kept, assigned, unmapped.
  • roles[].account
    string | nullrequired
  • roles[].note
    stringrequired
  • dimensions
    object[]required
  • dimensions[].code
    stringrequired
  • dimensions[].status
    stringrequired
    One of: create, exists.

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Unknown or missing pack

Example request

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

Chart of accounts tree

Every account nested under its parent header account, roots in number order. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • type
    anyrequired
    One 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.
  • subtype
    string | nullrequired
  • normal_balance
    anyrequired
    One of: debit, credit.
  • parent_id
    integer | nullrequired
  • is_postable
    booleanrequired
  • is_active
    booleanrequired
  • system_role
    string | nullrequired
    Control-account role, unique per company (e.g. AP_CONTROL)
  • is_control
    booleanrequired
  • require_project
    booleanrequired
  • require_cost_code
    booleanrequired
  • require_cost_type
    booleanrequired
  • job_cost_type
    anyrequired
    One of: labor, material, subcontract, equipment, other, burden, null.
  • currency
    stringrequired
  • cash_flow_category
    anyrequired
    One of: operating, investing, financing, null.
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • children
    object[]required

Errors

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

Example request

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