Esc

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

Accounting Settings

Configure entities, account mappings, terms and tax settings. 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 Settings guide for the workflow.

79 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/dimensionsList dimensions
  2. POST /rest/v1.0/companies/{company_id}/accounting/dimensionsCreate a dimension
  3. GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}Show a dimension
  4. PATCH /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}Update a dimension
  5. GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/historyDimension history
  6. GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rulesList a dimension's requirement rules
  7. PUT /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rulesReplace a dimension's requirement rules
  8. GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/valuesList a dimension's values
  9. POST /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/valuesCreate a dimension value
  10. GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}Show a dimension value
  11. PATCH /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}Update a dimension value
  12. GET /rest/v1.0/companies/{company_id}/accounting/entitiesList legal entities
  13. POST /rest/v1.0/companies/{company_id}/accounting/entitiesCreate a legal entity
  14. GET /rest/v1.0/companies/{company_id}/accounting/entities/{id}Show a legal entity
  15. PATCH /rest/v1.0/companies/{company_id}/accounting/entities/{id}Update a legal entity
  16. GET /rest/v1.0/companies/{company_id}/accounting/job_tax_profiles/{id}Get a job tax profile
  17. PUT /rest/v1.0/companies/{company_id}/accounting/job_tax_profiles/{id}Set a job tax profile
  18. GET /rest/v1.0/companies/{company_id}/accounting/party_profilesList party profiles
  19. POST /rest/v1.0/companies/{company_id}/accounting/party_profilesCreate a party profile
  20. GET /rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}Show a party profile
  21. PATCH /rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}Update a party profile
  22. POST /rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}/sensitive_changeApprove or reject a routing/bank/TIN change
  23. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/ar_invoices/{id}/determinationsAn invoice's sales tax determinations
  24. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappingsList cost type taxability categories
  25. PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappingsSet a cost type taxability category
  26. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificatesList exemption and resale certificates
  27. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificatesAdd a certificate
  28. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}Show a certificate
  29. PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}Renew or revoke a certificate
  30. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filingsList sales tax returns
  31. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filingsPrepare a sales tax return
  32. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}Show a sales tax return
  33. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/decisionMark a return filed, or cancel it
  34. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/exportFiling-prep export (CSV)
  35. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/paymentLink a return's payment
  36. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_setsList jurisdiction sets
  37. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_setsAdd a jurisdiction set
  38. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}Show a jurisdiction set
  39. PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}Change a jurisdiction set
  40. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictionsList tax jurisdictions
  41. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictionsAdd a tax jurisdiction
  42. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}Show a tax jurisdiction
  43. PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}Change a tax jurisdiction
  44. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/liabilitySales and use tax liability by jurisdiction
  45. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sitesList job sites
  46. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}Show a project's job site
  47. PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}Set a project's job site
  48. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/ratesList tax rates
  49. DELETE /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}Delete an unused tax rate
  50. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}/reviewRecord a qualified review of a rate
  51. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/importImport tax rates from CSV
  52. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/provider_syncImport rates from a provider adapter
  53. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/rulesList taxability rules
  54. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rulesAdd a taxability rule
  55. PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/rules/{id}Change or end a taxability rule
  56. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/settingsSales tax settings
  57. PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/settingsUpdate sales tax settings
  58. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accrualsList use tax accruals
  59. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accrualsAccrue use tax on a posted bill
  60. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}Show a use tax accrual
  61. POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}/reverseReverse a use tax accrual
  62. GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/candidatesBills that may owe use tax
  63. GET /rest/v1.0/companies/{company_id}/accounting/settingsShow accounting settings
  64. PATCH /rest/v1.0/companies/{company_id}/accounting/settingsUpdate accounting settings
  65. GET /rest/v1.0/companies/{company_id}/accounting/settings/editionGet the accounting edition
  66. PATCH /rest/v1.0/companies/{company_id}/accounting/settings/editionOverride edition areas
  67. PUT /rest/v1.0/companies/{company_id}/accounting/settings/editionApply an edition
  68. GET /rest/v1.0/companies/{company_id}/accounting/settings/edition/previewPreview an edition change
  69. GET /rest/v1.0/companies/{company_id}/accounting/settings/setupGet guided setup progress
  70. PUT /rest/v1.0/companies/{company_id}/accounting/settings/setupRecord a setup step
  71. GET /rest/v1.0/companies/{company_id}/accounting/tax_codesList tax codes
  72. POST /rest/v1.0/companies/{company_id}/accounting/tax_codesCreate a tax code
  73. PATCH /rest/v1.0/companies/{company_id}/accounting/tax_codes/{id}Update a tax code
  74. GET /rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificatesList customer tax exemption certificates
  75. POST /rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificatesRecord a customer tax exemption certificate
  76. PATCH /rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificates/{id}Change a certificate expiry
  77. GET /rest/v1.0/companies/{company_id}/accounting/termsList payment terms
  78. POST /rest/v1.0/companies/{company_id}/accounting/termsCreate a payment term
  79. PATCH /rest/v1.0/companies/{company_id}/accounting/terms/{id}Update a payment term

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/dimensions

List dimensions

Every dimension with its values and requirement rules, by position then code. active=true lists active dimensions only. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • active
    stringquery
    One of: true, false.

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    stringrequired
    One of: department, division, location, custom.
  • description
    string | nullrequired
  • default_requirement
    stringrequired
    One of: optional, required.
  • is_active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • values
    object[]required
  • values[].id
    integerrequired
  • values[].dimension_id
    integerrequired
  • values[].code
    stringrequired
  • values[].name
    stringrequired
  • values[].description
    string | nullrequired
  • values[].parent_id
    integer | nullrequired
  • values[].effective_from
    string | null (date)required
  • values[].effective_to
    string | null (date)required
  • values[].entity_ids
    integer[]required
  • values[].is_active
    booleanrequired
  • values[].created_at
    string (date-time)required
  • values[].updated_at
    string (date-time)required
  • rules
    object[]required
  • rules[].id
    integerrequired
  • rules[].account_id
    integer | nullrequired
  • rules[].account_type
    string | nullrequired
    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, null.
  • rules[].account_from
    string | nullrequired
  • rules[].account_to
    string | nullrequired
  • rules[].requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, 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/dimensions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

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

Create a dimension

Needs manage_coa on an unrestricted grant. Codes are unique per company (case-insensitive). 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

  • dimension
    objectrequired
  • dimension.code
    stringrequired
  • dimension.name
    stringrequired
  • dimension.kind
    string
    One of: department, division, location, custom.
  • dimension.description
    string | null
  • dimension.default_requirement
    string
    One of: optional, required.
  • dimension.is_active
    boolean
  • dimension.position
    integer

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    stringrequired
    One of: department, division, location, custom.
  • description
    string | nullrequired
  • default_requirement
    stringrequired
    One of: optional, required.
  • is_active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • values
    object[]required
  • values[].id
    integerrequired
  • values[].dimension_id
    integerrequired
  • values[].code
    stringrequired
  • values[].name
    stringrequired
  • values[].description
    string | nullrequired
  • values[].parent_id
    integer | nullrequired
  • values[].effective_from
    string | null (date)required
  • values[].effective_to
    string | null (date)required
  • values[].entity_ids
    integer[]required
  • values[].is_active
    booleanrequired
  • values[].created_at
    string (date-time)required
  • values[].updated_at
    string (date-time)required
  • rules
    object[]required
  • rules[].id
    integerrequired
  • rules[].account_id
    integer | nullrequired
  • rules[].account_type
    string | nullrequired
    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, null.
  • rules[].account_from
    string | nullrequired
  • rules[].account_to
    string | nullrequired
  • rules[].requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 409Idempotency-Key conflict
  • 422Validation failed

Example request

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

Accounting / Accounting Settings

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

Show a dimension

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
  • code
    stringrequired
  • name
    stringrequired
  • kind
    stringrequired
    One of: department, division, location, custom.
  • description
    string | nullrequired
  • default_requirement
    stringrequired
    One of: optional, required.
  • is_active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • values
    object[]required
  • values[].id
    integerrequired
  • values[].dimension_id
    integerrequired
  • values[].code
    stringrequired
  • values[].name
    stringrequired
  • values[].description
    string | nullrequired
  • values[].parent_id
    integer | nullrequired
  • values[].effective_from
    string | null (date)required
  • values[].effective_to
    string | null (date)required
  • values[].entity_ids
    integer[]required
  • values[].is_active
    booleanrequired
  • values[].created_at
    string (date-time)required
  • values[].updated_at
    string (date-time)required
  • rules
    object[]required
  • rules[].id
    integerrequired
  • rules[].account_id
    integer | nullrequired
  • rules[].account_type
    string | nullrequired
    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, null.
  • rules[].account_from
    string | nullrequired
  • rules[].account_to
    string | nullrequired
  • rules[].requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}

Update a dimension

Rename (audited as renamed with from and to), change the default requirement or order, or (de)activate. An inactive dimension's values are refused at posting. 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
  • id
    integerpathrequired

Request body

  • dimension
    objectrequired
  • dimension.code
    string
  • dimension.name
    string
  • dimension.kind
    string
    One of: department, division, location, custom.
  • dimension.description
    string | null
  • dimension.default_requirement
    string
    One of: optional, required.
  • dimension.is_active
    boolean
  • dimension.position
    integer

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    stringrequired
    One of: department, division, location, custom.
  • description
    string | nullrequired
  • default_requirement
    stringrequired
    One of: optional, required.
  • is_active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • values
    object[]required
  • values[].id
    integerrequired
  • values[].dimension_id
    integerrequired
  • values[].code
    stringrequired
  • values[].name
    stringrequired
  • values[].description
    string | nullrequired
  • values[].parent_id
    integer | nullrequired
  • values[].effective_from
    string | null (date)required
  • values[].effective_to
    string | null (date)required
  • values[].entity_ids
    integer[]required
  • values[].is_active
    booleanrequired
  • values[].created_at
    string (date-time)required
  • values[].updated_at
    string (date-time)required
  • rules
    object[]required
  • rules[].id
    integerrequired
  • rules[].account_id
    integer | nullrequired
  • rules[].account_type
    string | nullrequired
    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, null.
  • rules[].account_from
    string | nullrequired
  • rules[].account_to
    string | nullrequired
  • rules[].requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/dimensions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "dimension": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/history

Dimension history

Audit trail of the dimension and its values, newest first (at most 500): created, renamed (changes.name / changes.code from and to), updated, deactivated, reactivated and rules_changed (rules before and after). 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
  • item_type
    stringrequired
    One of: AcctDimension, AcctDimensionValue.
  • item_id
    integerrequired
  • action
    stringrequired
  • summary
    stringrequired
  • actor_id
    integerrequired
  • changes
    object | array | nullrequired
  • at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rules

List a dimension's requirement rules

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
  • account_id
    integer | nullrequired
  • account_type
    string | nullrequired
    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, null.
  • account_from
    string | nullrequired
  • account_to
    string | nullrequired
  • requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found

Example request

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

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rules

Replace a dimension's requirement rules

Each rule names one selector: account_id, account_type, or an account number range (account_from with account_to, inclusive). The most specific match wins (account, then the narrowest range, then type), else the dimension's default_requirement. optional exempts accounts a broader rule requires. Checked when an entry posts; closing entries and reversals are exempt. 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
  • id
    integerpathrequired

Request body

  • rules
    object[]required
  • rules[].account_id
    integer | null
  • rules[].account_type
    string | null
    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, null.
  • rules[].account_from
    string | null
  • rules[].account_to
    string | null
  • rules[].requirement
    stringrequired
    One of: optional, required.

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    stringrequired
    One of: department, division, location, custom.
  • description
    string | nullrequired
  • default_requirement
    stringrequired
    One of: optional, required.
  • is_active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • values
    object[]required
  • values[].id
    integerrequired
  • values[].dimension_id
    integerrequired
  • values[].code
    stringrequired
  • values[].name
    stringrequired
  • values[].description
    string | nullrequired
  • values[].parent_id
    integer | nullrequired
  • values[].effective_from
    string | null (date)required
  • values[].effective_to
    string | null (date)required
  • values[].entity_ids
    integer[]required
  • values[].is_active
    booleanrequired
  • values[].created_at
    string (date-time)required
  • values[].updated_at
    string (date-time)required
  • rules
    object[]required
  • rules[].id
    integerrequired
  • rules[].account_id
    integer | nullrequired
  • rules[].account_type
    string | nullrequired
    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, null.
  • rules[].account_from
    string | nullrequired
  • rules[].account_to
    string | nullrequired
  • rules[].requirement
    stringrequired
    One of: optional, required.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/dimensions/1/rules" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "rules": [
    {
      "requirement": "optional"
    }
  ]
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values

List a dimension's values

By code; parent_id gives the roll-up hierarchy. 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
  • dimension_id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • parent_id
    integer | nullrequired
  • effective_from
    string | null (date)required
  • effective_to
    string | null (date)required
  • entity_ids
    integer[]required
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values

Create a dimension value

parent_id must be a value of the same dimension. entity_ids restricts the value to those entities (empty = every entity); effective_from/effective_to bound the posting dates it accepts. 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
  • 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

  • value
    objectrequired
  • value.code
    stringrequired
  • value.name
    stringrequired
  • value.description
    string | null
  • value.parent_id
    integer | null
  • value.effective_from
    string | null (date)
  • value.effective_to
    string | null (date)
  • value.entity_ids
    integer[]
  • value.is_active
    boolean

Response · 201 · object

  • id
    integerrequired
  • dimension_id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • parent_id
    integer | nullrequired
  • effective_from
    string | null (date)required
  • effective_to
    string | null (date)required
  • entity_ids
    integer[]required
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found
  • 409Idempotency-Key conflict
  • 422Validation failed

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}

Show a dimension value

Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • dimension_id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • parent_id
    integer | nullrequired
  • effective_from
    string | null (date)required
  • effective_to
    string | null (date)required
  • entity_ids
    integer[]required
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}

Update a dimension value

Rename, re-parent (no cycles), change the effective window or entity restriction, or (de)activate. Posted lines keep the value id, so reports show the new name for all history and the rename is in the dimension's history. 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
  • id
    integerpathrequired
  • value_id
    integerpathrequired

Request body

  • value
    objectrequired
  • value.code
    string
  • value.name
    string
  • value.description
    string | null
  • value.parent_id
    integer | null
  • value.effective_from
    string | null (date)
  • value.effective_to
    string | null (date)
  • value.entity_ids
    integer[]
  • value.is_active
    boolean

Response · 200 · object

  • id
    integerrequired
  • dimension_id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • parent_id
    integer | nullrequired
  • effective_from
    string | null (date)required
  • effective_to
    string | null (date)required
  • entity_ids
    integer[]required
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/dimensions/1/values/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "value": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/entities

List legal entities

Legal entities inside the company, for multi-entity books, intercompany and consolidation. Every posted entry balances per entity. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • legal_name
    string | nullrequired
  • is_active
    booleanrequired
  • intercompany_due_to_account_id
    integer | nullrequired
  • intercompany_due_from_account_id
    integer | nullrequired
  • tax_id_last4
    string | nullrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • is_elimination
    booleanrequired
    The consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
  • retained_earnings_account_id
    integer | nullrequired
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

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/entities" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

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

Create a legal entity

Adds an entity with optional intercompany due-to/due-from accounts. The first entity becomes the default. Needs manage_coa. Requires the accounting:write scope. is_elimination: true creates the consolidation elimination book (one per company), which takes only CL entries and never becomes the default.

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

  • entity
    objectrequired
  • entity.code
    stringrequired
  • entity.name
    stringrequired
  • entity.legal_name
    string | null
  • entity.is_active
    boolean
  • entity.intercompany_due_to_account_id
    integer | null
  • entity.intercompany_due_from_account_id
    integer | null
  • entity.is_elimination
    boolean
    Create the consolidation elimination entity (one per company).
  • entity.tax_id
    string | null
    Payer EIN for 1099 issuer records; stored encrypted, only tax_id_last4 is returned.
  • entity.address
    string | null
  • entity.city
    string | null
  • entity.state
    string | null
  • entity.zip
    string | null
  • entity.phone
    string | null
  • entity.retained_earnings_account_id
    integer | null
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • legal_name
    string | nullrequired
  • is_active
    booleanrequired
  • intercompany_due_to_account_id
    integer | nullrequired
  • intercompany_due_from_account_id
    integer | nullrequired
  • tax_id_last4
    string | nullrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • is_elimination
    booleanrequired
    The consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
  • retained_earnings_account_id
    integer | nullrequired
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

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/entities" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity": {
    "code": "string",
    "name": "string"
  }
}'

Accounting / Accounting Settings

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

Show a legal entity

One entity 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
  • code
    stringrequired
  • name
    stringrequired
  • legal_name
    string | nullrequired
  • is_active
    booleanrequired
  • intercompany_due_to_account_id
    integer | nullrequired
  • intercompany_due_from_account_id
    integer | nullrequired
  • tax_id_last4
    string | nullrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • is_elimination
    booleanrequired
    The consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
  • retained_earnings_account_id
    integer | nullrequired
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

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/entities/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/entities/{id}

Update a legal entity

Renames, deactivates or remaps intercompany accounts. 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

  • entity
    objectrequired
  • entity.code
    string
  • entity.name
    string
  • entity.legal_name
    string | null
  • entity.is_active
    boolean
  • entity.intercompany_due_to_account_id
    integer | null
  • entity.intercompany_due_from_account_id
    integer | null
  • entity.tax_id
    string | null
    Payer EIN for 1099 issuer records; stored encrypted, only tax_id_last4 is returned.
  • entity.address
    string | null
  • entity.city
    string | null
  • entity.state
    string | null
  • entity.zip
    string | null
  • entity.phone
    string | null
  • entity.retained_earnings_account_id
    integer | null
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • legal_name
    string | nullrequired
  • is_active
    booleanrequired
  • intercompany_due_to_account_id
    integer | nullrequired
  • intercompany_due_from_account_id
    integer | nullrequired
  • tax_id_last4
    string | nullrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • is_elimination
    booleanrequired
    The consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
  • retained_earnings_account_id
    integer | nullrequired
    Retained earnings this entity's year-end close posts to (a postable retained earnings or equity account); null uses the company's RETAINED_EARNINGS account.

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/entities/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "entity": {}
}'

Accounting / Accounting Settings

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

Get a job tax profile

id is the project id. Returns the job's contractor sales/use tax profile with the model resolved from the state and contract type on as_of (default today). Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • as_of
    string (date)query

Response · 200 · object

  • project_id
    integerrequired
  • state_code
    stringrequired
  • contract_type
    stringrequired
    One of: lump_sum, separated.
  • sales_tax_code_id
    integer | nullrequired
    Job-site sales tax code billed to the owner (retailer and gross-receipts models); the pay-app bridge applies it.
  • use_tax_code_id
    integer | nullrequired
    Use tax code accrued on untaxed material bills (consumer model).
  • as_of
    string (date)required
  • model
    stringrequired
    One of: consumer, retailer_on_separated, gross_receipts, retail_sale_of_construction.
  • charge_customer
    booleanrequired
  • accrue_use_tax
    booleanrequired
  • fixtures
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace
  • 404Not found in this company
  • 422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)

Example request

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

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/job_tax_profiles/{id}

Set a job tax profile

id is the project id. Creates or replaces the profile. A state with no encoded contractor rule is refused (422, setup gap) rather than defaulted. Retailer and gross-receipts states need sales_tax_code_id (except separated retailer contracts); use-tax states need use_tax_code_id. 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

  • tax_profile
    objectrequired
  • tax_profile.state_code
    stringrequired
  • tax_profile.contract_type
    stringrequired
    One of: lump_sum, separated.
  • tax_profile.sales_tax_code_id
    integer | null
  • tax_profile.use_tax_code_id
    integer | null

Response · 200 · object

  • project_id
    integerrequired
  • state_code
    stringrequired
  • contract_type
    stringrequired
    One of: lump_sum, separated.
  • sales_tax_code_id
    integer | nullrequired
    Job-site sales tax code billed to the owner (retailer and gross-receipts models); the pay-app bridge applies it.
  • use_tax_code_id
    integer | nullrequired
    Use tax code accrued on untaxed material bills (consumer model).
  • as_of
    string (date)required
  • model
    stringrequired
    One of: consumer, retailer_on_separated, gross_receipts, retail_sale_of_construction.
  • charge_customer
    booleanrequired
  • accrue_use_tax
    booleanrequired
  • fixtures
    string | nullrequired

Errors

  • 400Malformed JSON body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace
  • 404Not found in this company
  • 422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/job_tax_profiles/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "tax_profile": {
    "state_code": "string",
    "contract_type": "lump_sum"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/party_profiles

List party profiles

Accounting profiles of company vendors and customers: 1099 settings, W-9 status, terms, remit-to, payment method, retainage, compliance hold and credit limit. Tax ids and bank numbers are always masked. Filter with filters[role] (vendor or customer) or search by vendor name. Delta sync: updated_since and/or cursor return changes in ascending (updated_at, id) order with Next-Cursor. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • filters[role]
    anyquery
    Vendors or customers One of: vendor, customer.
  • search
    stringquery
    Vendor name
  • 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
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • is_vendor
    booleanrequired
  • is_customer
    booleanrequired
  • tax_id_masked
    string | nullrequired
  • tax_id_type
    string | nullrequired
  • is_1099
    booleanrequired
  • form_1099_type
    string | nullrequired
  • form_1099_box
    string | nullrequired
  • tax_classification
    string | nullrequired
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • w9_status
    anyrequired
    One of: not_requested, requested, received, expired.
  • w9_received_at
    string | null (date)required
  • term_id
    integer | nullrequired
  • remit_to_name
    string | nullrequired
  • remit_to_address
    string | nullrequired
  • remit_to_city
    string | nullrequired
  • remit_to_state
    string | nullrequired
  • remit_to_zip
    string | nullrequired
  • default_expense_account_id
    integer | nullrequired
  • payment_method
    anyrequired
    One of: check, ach, wire, card.
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | nullrequired
  • has_bank_routing
    booleanrequired
  • retainage_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • compliance_hold
    booleanrequired
  • compliance_hold_reason
    string | nullrequired
  • credit_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • billing_contact_name
    string | nullrequired
  • billing_email
    string | null (email)required
  • billing_address
    string | nullrequired
  • pending_sensitive_change
    object | nullrequired
  • pending_sensitive_change.reason
    string | null
    Reason entered by the proposer.
  • pending_sensitive_change.requested_by_id
    integerrequired
  • pending_sensitive_change.fields
    string[]required
  • pending_sensitive_change.changes
    object[]required
    What the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
  • pending_sensitive_change.change_hash
    stringrequired
    SHA-256 of the pending change; echo it when deciding.
  • revealed
    object
  • revealed.tax_id
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • tin_match_code
    integer | nullrequired
    Latest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
  • tin_matched_at
    string | null (date)required
  • bank_account_ownership
    string | null
    Who owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.

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/party_profiles" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

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

Create a party profile

Creates a party profile. Changed W-9 status/date, tax classification, 1099 flag/form/box and clearing a compliance hold need (ap_approve AND release_payments) OR manage_vendor_banking, including configured MFA checks. Unchanged fields and safe create defaults need no sensitive permission. AR-only users may edit customer role, billing/contact, credit limit and terms, never vendor-only fields. Customer-only creates must explicitly set is_vendor=false (the server default is true). Bank account ownership still needs manage_vendor_banking. Remit-to and payment_method changes, including non-default create values, require a reason and step-up and become pending_sensitive_change alongside bank/TIN proposals. Effective routing stays unchanged until a different manage_vendor_banking user approves the reviewed change_hash. Any new proposal replaces the entire pending change; stale hashes and self-approval are refused. Approval arms the existing non-overridable payment cool-off. Authorization and step-up run before Idempotency-Key replay as well as inside the mutation. Requires accounting:write.

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

  • party_profile
    objectrequired
  • party_profile.vendor_id
    integerrequired
  • party_profile.is_vendor
    boolean
  • party_profile.is_customer
    boolean
  • party_profile.is_1099
    boolean
  • party_profile.form_1099_type
    string | null
  • party_profile.form_1099_box
    string | null
  • party_profile.tax_classification
    string | null
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • party_profile.w9_status
    any
    One of: not_requested, requested, received, expired.
  • party_profile.w9_received_at
    string | null (date)
  • party_profile.term_id
    integer | null
  • party_profile.reason
    string | null
    Required for non-default remit-to/payment method proposals.
  • party_profile.remit_to_name
    string | null
  • party_profile.remit_to_address
    string | null
  • party_profile.remit_to_city
    string | null
  • party_profile.remit_to_state
    string | null
  • party_profile.remit_to_zip
    string | null
  • party_profile.default_expense_account_id
    integer | null
  • party_profile.payment_method
    any
    One of: check, ach, wire, card.
  • party_profile.bank_account_type
    string | null
  • party_profile.compliance_hold
    boolean
  • party_profile.compliance_hold_reason
    string | null
  • party_profile.tax_id
    string | null
    9-digit EIN or SSN; applied only after a second person approves
  • party_profile.tax_id_type
    any
    One of: ein, ssn, null.
  • party_profile.bank_account_number
    string | null
  • party_profile.bank_routing_number
    string | null
  • party_profile.retainage_percent
    string | null
  • party_profile.credit_limit
    string | null
  • party_profile.billing_contact_name
    string | null
  • party_profile.billing_email
    string | null (email)
  • party_profile.billing_address
    string | null
  • party_profile.bank_account_ownership
    string | null
    Needs manage_vendor_banking. One of: business, consumer, null.

Response · 201 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • is_vendor
    booleanrequired
  • is_customer
    booleanrequired
  • tax_id_masked
    string | nullrequired
  • tax_id_type
    string | nullrequired
  • is_1099
    booleanrequired
  • form_1099_type
    string | nullrequired
  • form_1099_box
    string | nullrequired
  • tax_classification
    string | nullrequired
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • w9_status
    anyrequired
    One of: not_requested, requested, received, expired.
  • w9_received_at
    string | null (date)required
  • term_id
    integer | nullrequired
  • remit_to_name
    string | nullrequired
  • remit_to_address
    string | nullrequired
  • remit_to_city
    string | nullrequired
  • remit_to_state
    string | nullrequired
  • remit_to_zip
    string | nullrequired
  • default_expense_account_id
    integer | nullrequired
  • payment_method
    anyrequired
    One of: check, ach, wire, card.
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | nullrequired
  • has_bank_routing
    booleanrequired
  • retainage_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • compliance_hold
    booleanrequired
  • compliance_hold_reason
    string | nullrequired
  • credit_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • billing_contact_name
    string | nullrequired
  • billing_email
    string | null (email)required
  • billing_address
    string | nullrequired
  • pending_sensitive_change
    object | nullrequired
  • pending_sensitive_change.reason
    string | null
    Reason entered by the proposer.
  • pending_sensitive_change.requested_by_id
    integerrequired
  • pending_sensitive_change.fields
    string[]required
  • pending_sensitive_change.changes
    object[]required
    What the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
  • pending_sensitive_change.change_hash
    stringrequired
    SHA-256 of the pending change; echo it when deciding.
  • revealed
    object
  • revealed.tax_id
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • tin_match_code
    integer | nullrequired
    Latest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
  • tin_matched_at
    string | null (date)required
  • bank_account_ownership
    string | null
    Who owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.

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/party_profiles" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "party_profile": {
    "vendor_id": 1
  }
}'

Accounting / Accounting Settings

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

Show a party profile

One profile with masked tax id and bank account. reveal=true adds the decrypted values; it needs the accounting:write scope and manage_vendor_banking, writes an audit record, counts toward the per-user export limit (429), and is never cached. Requires the accounting:read scope (accounting:write with reveal=true). Entity-wide: a project-scoped (project_manager_view) grant gets 403.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • reveal
    anyquery
    Decrypt TIN and bank numbers One of: true, false.

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • is_vendor
    booleanrequired
  • is_customer
    booleanrequired
  • tax_id_masked
    string | nullrequired
  • tax_id_type
    string | nullrequired
  • is_1099
    booleanrequired
  • form_1099_type
    string | nullrequired
  • form_1099_box
    string | nullrequired
  • tax_classification
    string | nullrequired
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • w9_status
    anyrequired
    One of: not_requested, requested, received, expired.
  • w9_received_at
    string | null (date)required
  • term_id
    integer | nullrequired
  • remit_to_name
    string | nullrequired
  • remit_to_address
    string | nullrequired
  • remit_to_city
    string | nullrequired
  • remit_to_state
    string | nullrequired
  • remit_to_zip
    string | nullrequired
  • default_expense_account_id
    integer | nullrequired
  • payment_method
    anyrequired
    One of: check, ach, wire, card.
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | nullrequired
  • has_bank_routing
    booleanrequired
  • retainage_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • compliance_hold
    booleanrequired
  • compliance_hold_reason
    string | nullrequired
  • credit_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • billing_contact_name
    string | nullrequired
  • billing_email
    string | null (email)required
  • billing_address
    string | nullrequired
  • pending_sensitive_change
    object | nullrequired
  • pending_sensitive_change.reason
    string | null
    Reason entered by the proposer.
  • pending_sensitive_change.requested_by_id
    integerrequired
  • pending_sensitive_change.fields
    string[]required
  • pending_sensitive_change.changes
    object[]required
    What the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
  • pending_sensitive_change.change_hash
    stringrequired
    SHA-256 of the pending change; echo it when deciding.
  • revealed
    object
  • revealed.tax_id
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • tin_match_code
    integer | nullrequired
    Latest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
  • tin_matched_at
    string | null (date)required
  • bank_account_ownership
    string | null
    Who owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, or read-only workspace
  • 404Not found in this company
  • 429Too many reveals; retry after the Retry-After seconds.

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}

Update a party profile

Updates changed profile fields. Changed W-9 status/date, tax classification, 1099 flag/form/box and clearing a compliance hold need (ap_approve AND release_payments) OR manage_vendor_banking, including configured MFA checks. Unchanged fields and safe create defaults need no sensitive permission. AR-only users may edit customer role, billing/contact, credit limit and terms, never vendor-only fields. Customer-only creates must explicitly set is_vendor=false (the server default is true). Bank account ownership still needs manage_vendor_banking. Remit-to and payment_method changes, including non-default create values, require a reason and step-up and become pending_sensitive_change alongside bank/TIN proposals. Effective routing stays unchanged until a different manage_vendor_banking user approves the reviewed change_hash. Any new proposal replaces the entire pending change; stale hashes and self-approval are refused. Approval arms the existing non-overridable payment cool-off. Ordinary edits need ap_enter, ar_enter or manage_vendor_banking. Requires accounting:write.

v1.0Implemented

Parameters

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

Request body

  • party_profile
    objectrequired
  • party_profile.is_vendor
    boolean
  • party_profile.is_customer
    boolean
  • party_profile.is_1099
    boolean
  • party_profile.form_1099_type
    string | null
  • party_profile.form_1099_box
    string | null
  • party_profile.tax_classification
    string | null
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • party_profile.w9_status
    any
    One of: not_requested, requested, received, expired.
  • party_profile.w9_received_at
    string | null (date)
  • party_profile.term_id
    integer | null
  • party_profile.remit_to_name
    string | null
  • party_profile.remit_to_address
    string | null
  • party_profile.remit_to_city
    string | null
  • party_profile.remit_to_state
    string | null
  • party_profile.remit_to_zip
    string | null
  • party_profile.default_expense_account_id
    integer | null
  • party_profile.payment_method
    any
    One of: check, ach, wire, card.
  • party_profile.bank_account_type
    string | null
  • party_profile.compliance_hold
    boolean
  • party_profile.compliance_hold_reason
    string | null
  • party_profile.reason
    string | null
    Required (422 without it) when clearing compliance_hold or changing remit_to_* or payment_method; recorded in the audit trail with the old and new values.
  • party_profile.tax_id
    string | null
    9-digit EIN or SSN; applied only after a second person approves
  • party_profile.tax_id_type
    any
    One of: ein, ssn, null.
  • party_profile.bank_account_number
    string | null
  • party_profile.bank_routing_number
    string | null
  • party_profile.retainage_percent
    string | null
  • party_profile.credit_limit
    string | null
  • party_profile.billing_contact_name
    string | null
  • party_profile.billing_email
    string | null (email)
  • party_profile.billing_address
    string | null
  • party_profile.bank_account_ownership
    string | null
    Needs manage_vendor_banking. One of: business, consumer, null.

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • is_vendor
    booleanrequired
  • is_customer
    booleanrequired
  • tax_id_masked
    string | nullrequired
  • tax_id_type
    string | nullrequired
  • is_1099
    booleanrequired
  • form_1099_type
    string | nullrequired
  • form_1099_box
    string | nullrequired
  • tax_classification
    string | nullrequired
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • w9_status
    anyrequired
    One of: not_requested, requested, received, expired.
  • w9_received_at
    string | null (date)required
  • term_id
    integer | nullrequired
  • remit_to_name
    string | nullrequired
  • remit_to_address
    string | nullrequired
  • remit_to_city
    string | nullrequired
  • remit_to_state
    string | nullrequired
  • remit_to_zip
    string | nullrequired
  • default_expense_account_id
    integer | nullrequired
  • payment_method
    anyrequired
    One of: check, ach, wire, card.
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | nullrequired
  • has_bank_routing
    booleanrequired
  • retainage_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • compliance_hold
    booleanrequired
  • compliance_hold_reason
    string | nullrequired
  • credit_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • billing_contact_name
    string | nullrequired
  • billing_email
    string | null (email)required
  • billing_address
    string | nullrequired
  • pending_sensitive_change
    object | nullrequired
  • pending_sensitive_change.reason
    string | null
    Reason entered by the proposer.
  • pending_sensitive_change.requested_by_id
    integerrequired
  • pending_sensitive_change.fields
    string[]required
  • pending_sensitive_change.changes
    object[]required
    What the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
  • pending_sensitive_change.change_hash
    stringrequired
    SHA-256 of the pending change; echo it when deciding.
  • revealed
    object
  • revealed.tax_id
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • tin_match_code
    integer | nullrequired
    Latest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
  • tin_matched_at
    string | null (date)required
  • bank_account_ownership
    string | null
    Who owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.

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/party_profiles/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "party_profile": {}
}'

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}/sensitive_change

Approve or reject a routing/bank/TIN change

Applies (approve) or discards (reject) the pending remit-to, payment method, tax id and bank change. Send the change_hash from the profile's pending_sensitive_change you reviewed: if the change was replaced since (any new request replaces it and gets a new hash), the decision is refused with 409 stale_change. A legacy pending change without reviewable values can only be rejected (409 unreviewable_change). The requester cannot decide their own change. Needs manage_vendor_banking. Requires the accounting:write scope. Step-up is required. Routing before/after and the request reason are shown in pending_sensitive_change; approval starts the non-overridable payment cool-off.

v1.0Implemented

Parameters

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

Request body

  • decision
    anyrequired
    One of: approve, reject.
  • change_hash
    stringrequired
    pending_sensitive_change.change_hash of the change you reviewed.

Response · 200 · object

  • id
    integerrequired
  • vendor_id
    integerrequired
  • vendor_name
    string | nullrequired
  • is_vendor
    booleanrequired
  • is_customer
    booleanrequired
  • tax_id_masked
    string | nullrequired
  • tax_id_type
    string | nullrequired
  • is_1099
    booleanrequired
  • form_1099_type
    string | nullrequired
  • form_1099_box
    string | nullrequired
  • tax_classification
    string | nullrequired
    W-9 federal tax classification; corporations and exempt payees get no 1099-NEC/MISC. Null is treated as reportable. One of: individual, sole_proprietor, partnership, llc_disregarded, llc_partnership, llc_c_corp, llc_s_corp, c_corp, s_corp, tax_exempt, government, null.
  • w9_status
    anyrequired
    One of: not_requested, requested, received, expired.
  • w9_received_at
    string | null (date)required
  • term_id
    integer | nullrequired
  • remit_to_name
    string | nullrequired
  • remit_to_address
    string | nullrequired
  • remit_to_city
    string | nullrequired
  • remit_to_state
    string | nullrequired
  • remit_to_zip
    string | nullrequired
  • default_expense_account_id
    integer | nullrequired
  • payment_method
    anyrequired
    One of: check, ach, wire, card.
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | nullrequired
  • has_bank_routing
    booleanrequired
  • retainage_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • compliance_hold
    booleanrequired
  • compliance_hold_reason
    string | nullrequired
  • credit_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • billing_contact_name
    string | nullrequired
  • billing_email
    string | null (email)required
  • billing_address
    string | nullrequired
  • pending_sensitive_change
    object | nullrequired
  • pending_sensitive_change.reason
    string | null
    Reason entered by the proposer.
  • pending_sensitive_change.requested_by_id
    integerrequired
  • pending_sensitive_change.fields
    string[]required
  • pending_sensitive_change.changes
    object[]required
    What the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
  • pending_sensitive_change.change_hash
    stringrequired
    SHA-256 of the pending change; echo it when deciding.
  • revealed
    object
  • revealed.tax_id
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • tin_match_code
    integer | nullrequired
    Latest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
  • tin_matched_at
    string | null (date)required
  • bank_account_ownership
    string | null
    Who owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.

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
  • 409The pending change was replaced after review (stale_change) or has no reviewable values (unreviewable_change)
  • 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/party_profiles/1/sensitive_change" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": "approve",
  "change_hash": "string"
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/ar_invoices/{id}/determinations

An invoice's sales tax determinations

One row per line and job-site jurisdiction: taxability, base, rate, tax, certificate and liability account. AR read access (project-scoped grants refused). 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
  • doc_type
    stringrequired
    One of: ar_invoice, use_tax_accrual.
  • line_no
    integerrequired
  • ar_invoice_line_id
    integer | nullrequired
  • accrual_id
    integer | nullrequired
  • bill_line_id
    integer | nullrequired
  • entity_id
    integerrequired
  • project_id
    integer | nullrequired
  • party_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • jurisdiction_code
    string | nullrequired
  • kind
    stringrequired
    One of: sales, use.
  • tax_date
    string (date)required
  • category
    string | nullrequired
  • taxability
    stringrequired
    One of: taxable, exempt, nontaxable.
  • base_amount
    stringrequired
  • rate
    stringrequired
  • tax_amount
    stringrequired
  • rate_id
    integer | nullrequired
  • rule_id
    integer | nullrequired
  • certificate_id
    integer | nullrequired
  • account_id
    integer | nullrequired
  • note
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappings

List cost type taxability categories

AP lines without their own tax category take their cost type's. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • cost_type_id
    integerrequired
  • category
    stringrequired
    One of: material, fixture, labor, equipment.
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappings

Set a cost type taxability category

category null clears it (response null). Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • mapping
    objectrequired
  • mapping.cost_type_id
    integerrequired
  • mapping.category
    string | nullrequired
    One of: material, fixture, labor, equipment, null.

Response · 200 · object | null

  • cost_type_id
    integerrequired
  • category
    stringrequired
    One of: material, fixture, labor, equipment.
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/category_mappings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "mapping": {
    "cost_type_id": 1,
    "category": "material"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates

List exemption and resale certificates

Customer exemption or resale certificates (exempt their invoices) and resale certificates given to vendors. Any accounting grant; a project-scoped grant sees company-wide and its projects' certificates. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • party_type
    stringquery
    Filter by party type One of: customer, vendor.
  • party_id
    integerquery
    Filter by party

Response · 200 · object[]

  • id
    integerrequired
  • party_type
    stringrequired
    One of: customer, vendor.
  • party_id
    integerrequired
  • kind
    stringrequired
    One of: exemption, resale.
  • jurisdiction_id
    integerrequired
  • project_id
    integer | nullrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string | null (date)required
  • revoked_at
    string | null (date-time)required
  • revoke_reason
    string | nullrequired
  • status
    stringrequired
    One of: active, expired, revoked, future.
  • created_by_id
    integerrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates

Add a certificate

Covers its jurisdiction and descendants, optionally one project, from effective_from to expires_on. Needs manage_coa; audited. 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

  • certificate
    objectrequired
  • certificate.party_type
    stringrequired
    One of: customer, vendor.
  • certificate.party_id
    integerrequired
  • certificate.kind
    stringrequired
    One of: exemption, resale.
  • certificate.jurisdiction_id
    integerrequired
  • certificate.project_id
    integer | null
  • certificate.certificate_number
    stringrequired
  • certificate.reason
    stringrequired
  • certificate.effective_from
    string (date)required
  • certificate.expires_on
    string | null (date)

Response · 201 · object

  • id
    integerrequired
  • party_type
    stringrequired
    One of: customer, vendor.
  • party_id
    integerrequired
  • kind
    stringrequired
    One of: exemption, resale.
  • jurisdiction_id
    integerrequired
  • project_id
    integer | nullrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string | null (date)required
  • revoked_at
    string | null (date-time)required
  • revoke_reason
    string | nullrequired
  • status
    stringrequired
    One of: active, expired, revoked, future.
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/certificates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "certificate": {
    "party_type": "customer",
    "party_id": 1,
    "kind": "exemption",
    "jurisdiction_id": 1,
    "certificate_number": "string",
    "reason": "string",
    "effective_from": "2026-11-01"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}

Show a certificate

Any accounting grant. 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
  • party_type
    stringrequired
    One of: customer, vendor.
  • party_id
    integerrequired
  • kind
    stringrequired
    One of: exemption, resale.
  • jurisdiction_id
    integerrequired
  • project_id
    integer | nullrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string | null (date)required
  • revoked_at
    string | null (date-time)required
  • revoke_reason
    string | nullrequired
  • status
    stringrequired
    One of: active, expired, revoked, future.
  • created_by_id
    integerrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}

Renew or revoke a certificate

expires_on renews; revoke_reason revokes (final). Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • certificate
    objectrequired
  • certificate.expires_on
    string | null (date)
  • certificate.revoke_reason
    string

Response · 200 · object

  • id
    integerrequired
  • party_type
    stringrequired
    One of: customer, vendor.
  • party_id
    integerrequired
  • kind
    stringrequired
    One of: exemption, resale.
  • jurisdiction_id
    integerrequired
  • project_id
    integer | nullrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string | null (date)required
  • revoked_at
    string | null (date-time)required
  • revoke_reason
    string | nullrequired
  • status
    stringrequired
    One of: active, expired, revoked, future.
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/certificates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "certificate": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings

List sales tax returns

Project-scoped grants refused; entity-scoped grants see their entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • jurisdiction_id
    integerquery
    Filter by jurisdiction

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • status
    stringrequired
    One of: prepared, filed, superseded, cancelled, amended.
  • is_amendment
    booleanrequired
  • tax_due
    stringrequired
  • evidence_hash
    stringrequired
  • stale
    boolean | nullrequired
  • figures
    objectrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • filed_by_id
    integer | nullrequired
  • filed_at
    string | null (date-time)required
  • filed_on
    string | null (date)required
  • confirmation_number
    string | nullrequired
  • cancel_reason
    string | nullrequired
  • payment
    null | objectrequired
  • payment.source
    stringrequired
  • payment.source_id
    integerrequired
  • payment.entry_id
    integerrequired
  • payment.amount
    string | nullrequired
  • payment.linked_by_id
    integer | nullrequired
  • payment.linked_at
    string | null (date-time)required
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings

Prepare a sales tax return

For a filing jurisdiction (with those that file with it), entity and whole-month period matching its frequency: figures frozen with an evidence hash. The same figures return the prepared return (200); new figures supersede it. A filed period needs amendment true. Needs post_journal. 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

  • filing
    objectrequired
  • filing.entity_id
    integerrequired
  • filing.jurisdiction_id
    integerrequired
  • filing.period_start
    string (date)required
  • filing.period_end
    string (date)required
  • filing.amendment
    boolean

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • status
    stringrequired
    One of: prepared, filed, superseded, cancelled, amended.
  • is_amendment
    booleanrequired
  • tax_due
    stringrequired
  • evidence_hash
    stringrequired
  • stale
    boolean | nullrequired
  • figures
    objectrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • filed_by_id
    integer | nullrequired
  • filed_at
    string | null (date-time)required
  • filed_on
    string | null (date)required
  • confirmation_number
    string | nullrequired
  • cancel_reason
    string | nullrequired
  • payment
    null | objectrequired
  • payment.source
    stringrequired
  • payment.source_id
    integerrequired
  • payment.entry_id
    integerrequired
  • payment.amount
    string | nullrequired
  • payment.linked_by_id
    integer | nullrequired
  • payment.linked_at
    string | null (date-time)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/filings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "filing": {
    "entity_id": 1,
    "jurisdiction_id": 1,
    "period_start": "2026-11-01",
    "period_end": "2026-11-01"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}

Show a sales tax return

stale is true when the period's figures changed since it was prepared or filed. 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
  • entity_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • status
    stringrequired
    One of: prepared, filed, superseded, cancelled, amended.
  • is_amendment
    booleanrequired
  • tax_due
    stringrequired
  • evidence_hash
    stringrequired
  • stale
    boolean | nullrequired
  • figures
    objectrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • filed_by_id
    integer | nullrequired
  • filed_at
    string | null (date-time)required
  • filed_on
    string | null (date)required
  • confirmation_number
    string | nullrequired
  • cancel_reason
    string | nullrequired
  • payment
    null | objectrequired
  • payment.source
    stringrequired
  • payment.source_id
    integerrequired
  • payment.entry_id
    integerrequired
  • payment.amount
    string | nullrequired
  • payment.linked_by_id
    integer | nullrequired
  • payment.linked_at
    string | null (date-time)required
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/decision

Mark a return filed, or cancel it

mark_filed (approve_journal, never the preparer) recomputes the figures (409 if they moved) and records filed_on and the confirmation number; cancel (post_journal) needs a reason. No e-filing. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.action
    stringrequired
    One of: mark_filed, cancel.
  • decision.filed_on
    string (date)
  • decision.confirmation_number
    string
  • decision.reason
    string

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • status
    stringrequired
    One of: prepared, filed, superseded, cancelled, amended.
  • is_amendment
    booleanrequired
  • tax_due
    stringrequired
  • evidence_hash
    stringrequired
  • stale
    boolean | nullrequired
  • figures
    objectrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • filed_by_id
    integer | nullrequired
  • filed_at
    string | null (date-time)required
  • filed_on
    string | null (date)required
  • confirmation_number
    string | nullrequired
  • cancel_reason
    string | nullrequired
  • payment
    null | objectrequired
  • payment.source
    stringrequired
  • payment.source_id
    integerrequired
  • payment.entry_id
    integerrequired
  • payment.amount
    string | nullrequired
  • payment.linked_by_id
    integer | nullrequired
  • payment.linked_at
    string | null (date-time)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/filings/1/decision" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": {
    "action": "mark_filed"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/export

Filing-prep export (CSV)

Jurisdiction and rate lines, exempt certificates and the GL tie-out of a return. Text only; no e-filing. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · string

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/payment

Link a return's payment

A posted journal entry, or a posted AP bill's entry, in the return's entity that debits its liability accounts. One entry pays one return. Needs approve_journal; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • payment
    objectrequired
  • payment.source
    stringrequired
    One of: journal_entry, ap_bill.
  • payment.id
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • jurisdiction_id
    integerrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • status
    stringrequired
    One of: prepared, filed, superseded, cancelled, amended.
  • is_amendment
    booleanrequired
  • tax_due
    stringrequired
  • evidence_hash
    stringrequired
  • stale
    boolean | nullrequired
  • figures
    objectrequired
  • prepared_by_id
    integerrequired
  • prepared_at
    string (date-time)required
  • filed_by_id
    integer | nullrequired
  • filed_at
    string | null (date-time)required
  • filed_on
    string | null (date)required
  • confirmation_number
    string | nullrequired
  • cancel_reason
    string | nullrequired
  • payment
    null | objectrequired
  • payment.source
    stringrequired
  • payment.source_id
    integerrequired
  • payment.entry_id
    integerrequired
  • payment.amount
    string | nullrequired
  • payment.linked_by_id
    integer | nullrequired
  • payment.linked_at
    string | null (date-time)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/filings/1/payment" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "payment": {
    "source": "journal_entry",
    "id": 1
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets

List jurisdiction sets

The jurisdictions that tax one place, chosen per job site. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • jurisdictions
    object[]required
  • jurisdictions[].id
    integerrequired
  • jurisdictions[].code
    stringrequired
  • jurisdictions[].name
    stringrequired
  • jurisdictions[].level
    stringrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets

Add a jurisdiction set

Jurisdictions of one state. Needs manage_coa; audited. 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

  • jurisdiction_set
    objectrequired
  • jurisdiction_set.code
    stringrequired
  • jurisdiction_set.name
    stringrequired
  • jurisdiction_set.description
    string | null
  • jurisdiction_set.jurisdiction_ids
    integer[]required

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • jurisdictions
    object[]required
  • jurisdictions[].id
    integerrequired
  • jurisdictions[].code
    stringrequired
  • jurisdictions[].name
    stringrequired
  • jurisdictions[].level
    stringrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/jurisdiction_sets" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "jurisdiction_set": {
    "code": "string",
    "name": "string",
    "jurisdiction_ids": []
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}

Show a jurisdiction set

Any accounting grant. 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
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • jurisdictions
    object[]required
  • jurisdictions[].id
    integerrequired
  • jurisdictions[].code
    stringrequired
  • jurisdictions[].name
    stringrequired
  • jurisdictions[].level
    stringrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}

Change a jurisdiction set

Documents already taxed keep their jurisdictions. Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • jurisdiction_set
    objectrequired
  • jurisdiction_set.name
    string
  • jurisdiction_set.description
    string | null
  • jurisdiction_set.jurisdiction_ids
    integer[]

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • jurisdictions
    object[]required
  • jurisdictions[].id
    integerrequired
  • jurisdictions[].code
    stringrequired
  • jurisdictions[].name
    stringrequired
  • jurisdictions[].level
    stringrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/jurisdiction_sets/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "jurisdiction_set": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions

List tax jurisdictions

State, county, city and special-district jurisdictions the company maintains. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • state_code
    stringquery
    Filter by state

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • level
    stringrequired
    One of: state, county, city, special_district.
  • state_code
    stringrequired
  • parent_id
    integer | nullrequired
  • files_with_id
    integer | nullrequired
  • filing_frequency
    stringrequired
    One of: monthly, quarterly, annual.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • is_demo
    booleanrequired
  • is_active
    booleanrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions

Add a tax jurisdiction

Needs manage_coa over every entity; audited. State code ZZ marks fictional demo data. 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

  • jurisdiction
    objectrequired
  • jurisdiction.code
    stringrequired
  • jurisdiction.name
    stringrequired
  • jurisdiction.level
    stringrequired
    One of: state, county, city, special_district.
  • jurisdiction.state_code
    stringrequired
  • jurisdiction.parent_id
    integer | null
  • jurisdiction.files_with_id
    integer | null
  • jurisdiction.filing_frequency
    string
    One of: monthly, quarterly, annual.
  • jurisdiction.sales_payable_account_id
    integer | null
  • jurisdiction.use_payable_account_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • level
    stringrequired
    One of: state, county, city, special_district.
  • state_code
    stringrequired
  • parent_id
    integer | nullrequired
  • files_with_id
    integer | nullrequired
  • filing_frequency
    stringrequired
    One of: monthly, quarterly, annual.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • is_demo
    booleanrequired
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/jurisdictions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "jurisdiction": {
    "code": "string",
    "name": "string",
    "level": "state",
    "state_code": "string"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}

Show a tax jurisdiction

With its rate history, newest first. Any accounting grant. 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
  • code
    stringrequired
  • name
    stringrequired
  • level
    stringrequired
    One of: state, county, city, special_district.
  • state_code
    stringrequired
  • parent_id
    integer | nullrequired
  • files_with_id
    integer | nullrequired
  • filing_frequency
    stringrequired
    One of: monthly, quarterly, annual.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • is_demo
    booleanrequired
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • rates
    object[]required
  • rates[].id
    integerrequired
  • rates[].jurisdiction_id
    integerrequired
  • rates[].jurisdiction_code
    string | nullrequired
  • rates[].effective_from
    string (date)required
  • rates[].sales_rate
    stringrequired
  • rates[].use_rate
    stringrequired
  • rates[].source
    stringrequired
    One of: csv, provider, seed.
  • rates[].source_citation
    string | nullrequired
  • rates[].import_ref
    string | nullrequired
  • rates[].needs_review
    booleanrequired
  • rates[].reviewed_by_id
    integer | nullrequired
  • rates[].reviewed_at
    string | null (date-time)required
  • rates[].review_note
    string | nullrequired
  • rates[].used
    booleanrequired
  • rates[].used_at
    string | null (date-time)required
  • rates[].created_by_id
    integerrequired
  • rates[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}

Change a tax jurisdiction

Name, parent, files-with, filing frequency, liability accounts, active. Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • jurisdiction
    objectrequired
  • jurisdiction.name
    string
  • jurisdiction.parent_id
    integer | null
  • jurisdiction.files_with_id
    integer | null
  • jurisdiction.filing_frequency
    string
    One of: monthly, quarterly, annual.
  • jurisdiction.sales_payable_account_id
    integer | null
  • jurisdiction.use_payable_account_id
    integer | null
  • jurisdiction.is_active
    boolean

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • level
    stringrequired
    One of: state, county, city, special_district.
  • state_code
    stringrequired
  • parent_id
    integer | nullrequired
  • files_with_id
    integer | nullrequired
  • filing_frequency
    stringrequired
    One of: monthly, quarterly, annual.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • is_demo
    booleanrequired
  • is_active
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/jurisdictions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "jurisdiction": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/liability

Sales and use tax liability by jurisdiction

Tax collected and use tax accrued from GL lines tagged to determinations; taxable, exempt (with certificates) and nontaxable bases from documents posted or reversed in the period; rates; and the GL tie-out per liability account. Project-scoped grants refused. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • from
    string (date)queryrequired
    Period start
  • to
    string (date)queryrequired
    Period end
  • entity_id
    integerquery
    Entity
  • jurisdiction_id
    integerquery
    A filing jurisdiction and those that file with it

Response · 200 · object

  • from
    string (date)required
  • to
    string (date)required
  • entity_ids
    array | nullrequired
  • jurisdictions
    object[]required
  • jurisdictions[].jurisdiction_id
    integerrequired
  • jurisdictions[].code
    stringrequired
  • jurisdictions[].name
    stringrequired
  • jurisdictions[].level
    stringrequired
  • jurisdictions[].files_with_id
    integer | nullrequired
  • jurisdictions[].sales
    objectrequired
  • jurisdictions[].use
    objectrequired
  • jurisdictions[].by_rate
    object[]required
  • jurisdictions[].exempt_certificates
    object[]required
  • totals
    objectrequired
  • totals.sales_tax
    stringrequired
  • totals.use_tax
    stringrequired
  • totals.taxable_sales
    stringrequired
  • totals.exempt_sales
    stringrequired
  • tie_out
    object[]required
  • tie_out[].account_id
    integerrequired
  • tie_out[].number
    stringrequired
  • tie_out[].name
    stringrequired
  • tie_out[].gl_movement
    stringrequired
  • tie_out[].tagged_tax
    stringrequired
  • tie_out[].filing_payments
    stringrequired
  • tie_out[].other
    stringrequired
  • tie_out[].other_entries
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites

List job sites

Each project's job-site address and chosen jurisdiction set. A project-scoped grant sees its projects only. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • project_id
    integerrequired
  • jurisdiction_set_id
    integerrequired
  • address_line1
    stringrequired
  • city
    stringrequired
  • region
    stringrequired
  • postal_code
    stringrequired
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials.
  • contract_nature
    stringrequired
    One of: real_property, retail_sale.
  • default_category
    stringrequired
    One of: material, fixture, labor, equipment.
  • updated_by_id
    integerrequired
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}

Show a project's job site

{id} is the project id. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • project_id
    integerrequired
  • jurisdiction_set_id
    integerrequired
  • address_line1
    stringrequired
  • city
    stringrequired
  • region
    stringrequired
  • postal_code
    stringrequired
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials.
  • contract_nature
    stringrequired
    One of: real_property, retail_sale.
  • default_category
    stringrequired
    One of: material, fixture, labor, equipment.
  • updated_by_id
    integerrequired
  • updated_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}

Set a project's job site

The address as entered and the jurisdiction set the user chose (no geocoding), with the contract type and nature the rules key on. Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • site
    objectrequired
  • site.jurisdiction_set_id
    integerrequired
  • site.address_line1
    stringrequired
  • site.city
    stringrequired
  • site.region
    stringrequired
  • site.postal_code
    stringrequired
  • site.contract_type
    stringrequired
    One of: lump_sum, time_and_materials.
  • site.contract_nature
    stringrequired
    One of: real_property, retail_sale.
  • site.default_category
    string
    One of: material, fixture, labor, equipment.

Response · 200 · object

  • project_id
    integerrequired
  • jurisdiction_set_id
    integerrequired
  • address_line1
    stringrequired
  • city
    stringrequired
  • region
    stringrequired
  • postal_code
    stringrequired
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials.
  • contract_nature
    stringrequired
    One of: real_property, retail_sale.
  • default_category
    stringrequired
    One of: material, fixture, labor, equipment.
  • updated_by_id
    integerrequired
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/project_sites/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "site": {
    "jurisdiction_set_id": 1,
    "address_line1": "string",
    "city": "string",
    "region": "string",
    "postal_code": "string",
    "contract_type": "lump_sum",
    "contract_nature": "real_property"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates

List tax rates

Effective-dated sales and use rates (percent). A used rate is immutable. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • jurisdiction_id
    integerquery
    Filter by jurisdiction
  • needs_review
    stringquery
    Filter by qualified-review state One of: true, false.

Response · 200 · object[]

  • id
    integerrequired
  • jurisdiction_id
    integerrequired
  • jurisdiction_code
    string | nullrequired
  • effective_from
    string (date)required
  • sales_rate
    stringrequired
  • use_rate
    stringrequired
  • source
    stringrequired
    One of: csv, provider, seed.
  • source_citation
    string | nullrequired
  • import_ref
    string | nullrequired
  • needs_review
    booleanrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • used
    booleanrequired
  • used_at
    string | null (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

DELETE /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}

Delete an unused tax rate

A mistaken import; a rate a determination used is locked (409). Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}/review

Record a qualified review of a rate

By a different user than the one who imported it; once. Demo (ZZ) rates are never reviewed. Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • review
    objectrequired
  • review.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • jurisdiction_id
    integerrequired
  • jurisdiction_code
    string | nullrequired
  • effective_from
    string (date)required
  • sales_rate
    stringrequired
  • use_rate
    stringrequired
  • source
    stringrequired
    One of: csv, provider, seed.
  • source_citation
    string | nullrequired
  • import_ref
    string | nullrequired
  • needs_review
    booleanrequired
  • reviewed_by_id
    integer | nullrequired
  • reviewed_at
    string | null (date-time)required
  • review_note
    string | nullrequired
  • used
    booleanrequired
  • used_at
    string | null (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/rates/1/review" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "review": {
    "note": "string"
  }
}'

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/import

Import tax rates from CSV

All or nothing. Columns jurisdiction_code, effective_from, sales_rate, use_rate, source_citation; plus jurisdiction_name, level, state_code, parent_code to create a missing jurisdiction. A real (non-ZZ) jurisdiction's rate needs a citation and is stored needing qualified review. Equal rows are unchanged (a repeat is a no-op); a changed row, a date on or before an already-taxed date, or inside a closed period is refused. Needs manage_coa over every entity; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • import
    objectrequired
  • import.csv
    stringrequired
  • import.dry_run
    boolean

Response · 200 · object

  • dry_run
    booleanrequired
  • sha256
    stringrequired
  • created
    integerrequired
  • unchanged
    integerrequired
  • jurisdictions_created
    integerrequired
  • errors
    object[]required
  • errors[].line
    integerrequired
  • errors[].message
    stringrequired
  • rows
    object[]required
  • rows[].line
    integerrequired
  • rows[].jurisdiction_code
    stringrequired
  • rows[].effective_from
    string (date)required
  • rows[].sales_rate
    stringrequired
  • rows[].use_rate
    stringrequired
  • rows[].source_citation
    string | null
  • rows[].action
    stringrequired
    One of: create, unchanged.
  • rows[].create
    object

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/rates/import" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "import": {
    "csv": "string"
  }
}'

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/provider_sync

Import rates from a provider adapter

Only the fake provider ships (no network call; fictional ZZ rates). Imported under the CSV rules. Needs manage_coa over every entity. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • sync
    objectrequired
  • sync.provider
    stringrequired
  • sync.as_of
    string (date)required
  • sync.jurisdiction_codes
    string[]required
  • sync.dry_run
    boolean

Response · 200 · object

  • dry_run
    booleanrequired
  • sha256
    stringrequired
  • created
    integerrequired
  • unchanged
    integerrequired
  • jurisdictions_created
    integerrequired
  • errors
    object[]required
  • errors[].line
    integerrequired
  • errors[].message
    stringrequired
  • rows
    object[]required
  • rows[].line
    integerrequired
  • rows[].jurisdiction_code
    stringrequired
  • rows[].effective_from
    string (date)required
  • rows[].sales_rate
    stringrequired
  • rows[].use_rate
    stringrequired
  • rows[].source_citation
    string | null
  • rows[].action
    stringrequired
    One of: create, unchanged.
  • rows[].create
    object

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/rates/provider_sync" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "sync": {
    "provider": "string",
    "as_of": "2026-11-01",
    "jurisdiction_codes": []
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/rules

List taxability rules

Per jurisdiction (and its descendants), contract nature and type, and category: contractor role and whether sales and use tax apply. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • jurisdiction_id
    integerquery
    Filter by jurisdiction

Response · 200 · object[]

  • id
    integerrequired
  • jurisdiction_id
    integerrequired
  • contract_nature
    stringrequired
    One of: real_property, retail_sale, any.
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials, any.
  • category
    stringrequired
    One of: material, fixture, labor, equipment, any.
  • contractor_role
    stringrequired
    One of: consumer, retailer.
  • sales_taxable
    booleanrequired
  • use_taxable
    booleanrequired
  • effective_from
    string (date)required
  • effective_to
    string | null (date)required
  • note
    string | nullrequired
  • source_citation
    string | nullrequired
  • needs_review
    booleanrequired
  • used
    booleanrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/rules

Add a taxability rule

A real jurisdiction's rule needs a source citation and is stored needing qualified review; it may not take effect on or before a date already taxed. Needs manage_coa; audited. 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

  • rule
    objectrequired
  • rule.jurisdiction_id
    integerrequired
  • rule.contract_nature
    string
    One of: real_property, retail_sale, any.
  • rule.contract_type
    string
    One of: lump_sum, time_and_materials, any.
  • rule.category
    stringrequired
    One of: material, fixture, labor, equipment, any.
  • rule.contractor_role
    stringrequired
    One of: consumer, retailer.
  • rule.sales_taxable
    booleanrequired
  • rule.use_taxable
    booleanrequired
  • rule.effective_from
    string (date)required
  • rule.effective_to
    string | null (date)
  • rule.note
    string | null
  • rule.source_citation
    string | null

Response · 201 · object

  • id
    integerrequired
  • jurisdiction_id
    integerrequired
  • contract_nature
    stringrequired
    One of: real_property, retail_sale, any.
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials, any.
  • category
    stringrequired
    One of: material, fixture, labor, equipment, any.
  • contractor_role
    stringrequired
    One of: consumer, retailer.
  • sales_taxable
    booleanrequired
  • use_taxable
    booleanrequired
  • effective_from
    string (date)required
  • effective_to
    string | null (date)required
  • note
    string | nullrequired
  • source_citation
    string | nullrequired
  • needs_review
    booleanrequired
  • used
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/rules" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "rule": {
    "jurisdiction_id": 1,
    "category": "material",
    "contractor_role": "consumer",
    "sales_taxable": true,
    "use_taxable": true,
    "effective_from": "2026-11-01"
  }
}'

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/sales_tax/rules/{id}

Change or end a taxability rule

An unused rule may change; a used rule may only be ended (effective_to) on or after its last use. Needs manage_coa; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • rule
    objectrequired
  • rule.effective_to
    string | null (date)
  • rule.note
    string | null
  • rule.source_citation
    string | null
  • rule.sales_taxable
    boolean
  • rule.use_taxable
    boolean
  • rule.contractor_role
    string
    One of: consumer, retailer.

Response · 200 · object

  • id
    integerrequired
  • jurisdiction_id
    integerrequired
  • contract_nature
    stringrequired
    One of: real_property, retail_sale, any.
  • contract_type
    stringrequired
    One of: lump_sum, time_and_materials, any.
  • category
    stringrequired
    One of: material, fixture, labor, equipment, any.
  • contractor_role
    stringrequired
    One of: consumer, retailer.
  • sales_taxable
    booleanrequired
  • use_taxable
    booleanrequired
  • effective_from
    string (date)required
  • effective_to
    string | null (date)required
  • note
    string | nullrequired
  • source_citation
    string | nullrequired
  • needs_review
    booleanrequired
  • used
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/rules/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "rule": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/settings

Sales tax settings

Rounding method (line or invoice) and default sales and use tax payable accounts; unset accounts fall back to the chart's SALES_TAX_PAYABLE and USE_TAX_PAYABLE. Any accounting grant. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • rounding
    stringrequired
    One of: line, invoice.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • home_jurisdiction_set_id
    integer | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/sales_tax/settings

Update sales tax settings

Needs manage_coa over every entity; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • settings
    objectrequired
  • settings.rounding
    string
    One of: line, invoice.
  • settings.sales_payable_account_id
    integer | null
  • settings.use_payable_account_id
    integer | null
  • settings.home_jurisdiction_set_id
    integer | null

Response · 200 · object

  • rounding
    stringrequired
    One of: line, invoice.
  • sales_payable_account_id
    integer | nullrequired
  • use_payable_account_id
    integer | nullrequired
  • home_jurisdiction_set_id
    integer | nullrequired

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals

List use tax accruals

Project-scoped grants refused; entity-scoped grants see their entities. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • bill_id
    integerquery
    Filter by bill

Response · 200 · object[]

  • id
    integerrequired
  • entity_id
    integerrequired
  • bill_id
    integerrequired
  • vendor_id
    integerrequired
  • posting_date
    string (date)required
  • status
    stringrequired
    One of: posted, reversed.
  • vendor_tax_charged
    stringrequired
  • owed_total
    stringrequired
  • accrued_total
    stringrequired
  • overrides
    object[]required
  • overrides[].bill_line_id
    integerrequired
  • overrides[].action
    stringrequired
    One of: exclude, include.
  • overrides[].reason
    stringrequired
  • lines
    object[]required
  • lines[].bill_line_id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].amount
    stringrequired
  • lines[].category
    string | nullrequired
  • lines[].set_id
    integer | nullrequired
  • lines[].disposition
    stringrequired
  • lines[].reason
    string | nullrequired
  • lines[].tax
    stringrequired
  • warnings
    string[]required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • reversal_reason
    string | nullrequired
  • details
    object[]required
  • details[].bill_line_id
    integer | nullrequired
  • details[].jurisdiction_id
    integerrequired
  • details[].taxability
    stringrequired
  • details[].base_amount
    stringrequired
  • details[].rate
    stringrequired
  • details[].tax_amount
    stringrequired
  • details[].account_id
    integer | nullrequired
  • details[].note
    string | nullrequired
  • created_by_id
    integerrequired
  • reversed_by_id
    integer | nullrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals

Accrue use tax on a posted bill

Dr each line's cost (job cost or expense) / Cr each jurisdiction's use tax payable, on the bill's posting date or the date given (closed periods refused). vendor_tax_charged is credited against the tax owed. Overrides (exclude or include a line) need a reason and are audited. One posted accrual per bill: the same request returns it (200), a different one is 409. Needs post_journal. 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

  • accrual
    objectrequired
  • accrual.bill_id
    integerrequired
  • accrual.posting_date
    string | null (date)
  • accrual.vendor_tax_charged
    string
  • accrual.overrides
    object[]
  • accrual.overrides[].bill_line_id
    integerrequired
  • accrual.overrides[].action
    stringrequired
    One of: exclude, include.
  • accrual.overrides[].reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • bill_id
    integerrequired
  • vendor_id
    integerrequired
  • posting_date
    string (date)required
  • status
    stringrequired
    One of: posted, reversed.
  • vendor_tax_charged
    stringrequired
  • owed_total
    stringrequired
  • accrued_total
    stringrequired
  • overrides
    object[]required
  • overrides[].bill_line_id
    integerrequired
  • overrides[].action
    stringrequired
    One of: exclude, include.
  • overrides[].reason
    stringrequired
  • lines
    object[]required
  • lines[].bill_line_id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].amount
    stringrequired
  • lines[].category
    string | nullrequired
  • lines[].set_id
    integer | nullrequired
  • lines[].disposition
    stringrequired
  • lines[].reason
    string | nullrequired
  • lines[].tax
    stringrequired
  • warnings
    string[]required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • reversal_reason
    string | nullrequired
  • details
    object[]required
  • details[].bill_line_id
    integer | nullrequired
  • details[].jurisdiction_id
    integerrequired
  • details[].taxability
    stringrequired
  • details[].base_amount
    stringrequired
  • details[].rate
    stringrequired
  • details[].tax_amount
    stringrequired
  • details[].account_id
    integer | nullrequired
  • details[].note
    string | nullrequired
  • created_by_id
    integerrequired
  • reversed_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/use_tax/accruals" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "accrual": {
    "bill_id": 1
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}

Show a use tax accrual

With its determinations. Project-scoped grants refused. 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
  • entity_id
    integerrequired
  • bill_id
    integerrequired
  • vendor_id
    integerrequired
  • posting_date
    string (date)required
  • status
    stringrequired
    One of: posted, reversed.
  • vendor_tax_charged
    stringrequired
  • owed_total
    stringrequired
  • accrued_total
    stringrequired
  • overrides
    object[]required
  • overrides[].bill_line_id
    integerrequired
  • overrides[].action
    stringrequired
    One of: exclude, include.
  • overrides[].reason
    stringrequired
  • lines
    object[]required
  • lines[].bill_line_id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].amount
    stringrequired
  • lines[].category
    string | nullrequired
  • lines[].set_id
    integer | nullrequired
  • lines[].disposition
    stringrequired
  • lines[].reason
    string | nullrequired
  • lines[].tax
    stringrequired
  • warnings
    string[]required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • reversal_reason
    string | nullrequired
  • details
    object[]required
  • details[].bill_line_id
    integer | nullrequired
  • details[].jurisdiction_id
    integerrequired
  • details[].taxability
    stringrequired
  • details[].base_amount
    stringrequired
  • details[].rate
    stringrequired
  • details[].tax_amount
    stringrequired
  • details[].account_id
    integer | nullrequired
  • details[].note
    string | nullrequired
  • created_by_id
    integerrequired
  • reversed_by_id
    integer | nullrequired
  • 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, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

POST /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}/reverse

Reverse a use tax accrual

Posts the reversal on the date given; the bill may then be accrued again. Needs approve_journal; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • reversal
    objectrequired
  • reversal.date
    string (date)required
  • reversal.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • entity_id
    integerrequired
  • bill_id
    integerrequired
  • vendor_id
    integerrequired
  • posting_date
    string (date)required
  • status
    stringrequired
    One of: posted, reversed.
  • vendor_tax_charged
    stringrequired
  • owed_total
    stringrequired
  • accrued_total
    stringrequired
  • overrides
    object[]required
  • overrides[].bill_line_id
    integerrequired
  • overrides[].action
    stringrequired
    One of: exclude, include.
  • overrides[].reason
    stringrequired
  • lines
    object[]required
  • lines[].bill_line_id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].amount
    stringrequired
  • lines[].category
    string | nullrequired
  • lines[].set_id
    integer | nullrequired
  • lines[].disposition
    stringrequired
  • lines[].reason
    string | nullrequired
  • lines[].tax
    stringrequired
  • warnings
    string[]required
  • entry_id
    integer | nullrequired
  • reversal_entry_id
    integer | nullrequired
  • reversal_reason
    string | nullrequired
  • details
    object[]required
  • details[].bill_line_id
    integer | nullrequired
  • details[].jurisdiction_id
    integerrequired
  • details[].taxability
    stringrequired
  • details[].base_amount
    stringrequired
  • details[].rate
    stringrequired
  • details[].tax_amount
    stringrequired
  • details[].account_id
    integer | nullrequired
  • details[].note
    string | nullrequired
  • created_by_id
    integerrequired
  • reversed_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON body or Idempotency-Key header
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 404Not found in this company
  • 409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/sales_tax/use_tax/accruals/1/reverse" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reversal": {
    "date": "2026-11-01",
    "reason": "string"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/candidates

Bills that may owe use tax

Posted bills in [from, to] with no accrual, each with the line review and the use tax owed if the vendor charged none. Preview only. Project-scoped grants refused. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • from
    string (date)queryrequired
    Posting date from
  • to
    string (date)queryrequired
    Posting date to
  • entity_id
    integerquery
    Entity

Response · 200 · object[]

  • bill_id
    integerrequired
  • number
    stringrequired
  • vendor_id
    integerrequired
  • entity_id
    integerrequired
  • posting_date
    string (date)required
  • invoice_date
    string (date)required
  • owed
    stringrequired
  • gaps
    string[]required
  • warnings
    string[]required
  • lines
    object[]required
  • lines[].bill_line_id
    integerrequired
  • lines[].line_no
    integerrequired
  • lines[].amount
    stringrequired
  • lines[].category
    string | nullrequired
  • lines[].set_id
    integer | nullrequired
  • lines[].disposition
    stringrequired
  • lines[].reason
    string | nullrequired
  • lines[].tax
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token
  • 422Validation failed, a setup gap, a closed period, or a refused import

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/settings

Show accounting settings

Base currency, fiscal year start month, default entity, the manual journal approval threshold and the control-account map (one account per system role such as AP_CONTROL or RETAINED_EARNINGS). Any accounting grant can read it. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • company_id
    integerrequired
  • base_currency
    stringrequired
  • fiscal_year_start_month
    integerrequired
  • default_entity_id
    integer | nullrequired
  • posting_method
    anyrequired
    Stored and echoed only: every report is accrual basis. Cash-basis reporting is not built yet.
  • require_approval_above
    string | nullrequired
    Decimal amount as a string, 2 dp
  • recon_adjustment_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • transfer_approval_cross_entity
    boolean
    Bank transfers between entities wait for a second person holding release_payments (default true).
  • transfer_approval_above
    string | null
    Bank transfers at or above this amount wait for a second person holding release_payments; null = require_approval_above when that is set, else no amount rule.
  • timezone
    stringrequired
    IANA time zone that decides the company's today: recurring and auto-reversal runs and every date default (form dates, report and REST as_of/to, void and reversal dates), never the UTC date. E.g. America/Los_Angeles
  • control_accounts
    object[]required
  • control_accounts[].role
    stringrequired
  • control_accounts[].label
    stringrequired
  • control_accounts[].account_id
    integer | nullrequired
  • control_accounts[].account_number
    string | nullrequired
  • control_accounts[].account_name
    string | nullrequired
  • updated_at
    string (date-time)required
  • loss_provision_unit
    stringrequired
    Loss provision unit of account (ASU 2016-20 election), recorded on each WIP row (lossProvisionUnit). Each WIP row is one contract with a single performance obligation. One of: contract, performance_obligation.
  • finance_charge_monthly_pct
    string | nullrequired
    Monthly finance charge percent on past-due AR; null = none
  • finance_charge_grace_days
    integerrequired
    Days past due before a finance charge applies
  • finance_charge_account_id
    integer | nullrequired
    Income account finance-charge invoices credit
  • cecl_policy
    object | nullrequired
    ASC 326 (CECL) loss-rate policy used by the cecl_allowance report and posting; null = not set (the allowance refuses with 422).
  • cecl_policy.ar_rates
    objectrequired
  • cecl_policy.retainage_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • cecl_policy.contract_asset_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • sod_mode
    anyrequired
    strict (default): a maker never approves their own document. small_team: a maker may approve or release their own bill, payment run or journal entry with a reason, flagged self_approved. One of: strict, small_team.
  • scheduler_user_id
    integer | nullrequired
    User the daily accounting jobs (recurring entries, auto-reversals, lease runs) run and are audited as; null = the first active company admin, flagged on the accounting home page. Must be an active company user with post_journal for every entity (422); only an accounting owner or a user who manages grants may change it (403).
  • require_mfa_for
    any[]required
    Flags that refuse a session or token whose user has no MFA (403 mfa_required). One of: view_ledger, post_journal, approve_journal, manage_coa, close_period, ap_enter, ap_approve, release_payments, manage_vendor_banking, ar_enter, ar_approve, payroll_view, payroll_run, view_payroll_pii, bank_reconcile, manage_integrations, manage_grants, job_forecast_edit.
  • require_mfa_for_accounting
    booleanrequired
    Every accounting call needs MFA; the accounting pages send a user without a factor to enrol.
  • step_up_minutes
    integerrequired
    How long an authenticator re-entry (step-up) stays valid. Default 10.

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/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/settings

Update accounting settings

Changes settings and remaps control accounts: control_accounts maps a system role to a postable account id (null clears it). Needs the manage_coa permission. Audited in the same transaction. Requires the accounting:write scope. Changing require_mfa_for, require_mfa_for_accounting or step_up_minutes needs an accounting owner or manage_grants (403), is audited as mfa_policy_changed, and, like a sod_mode change, needs step-up. Step-up: from a browser session this needs an authenticator code re-entered within settings step_up_minutes (401 step_up_required); a user without a factor is refused (403 mfa_required) unless the MFA policy is off entirely (require_mfa_for empty and require_mfa_for_accounting off). An API token cannot re-enter a code: it passes only when it holds the accounting:step_up scope (403 step_up_required otherwise; the MFA policy still applies to its user); each such use writes a step_up_token audit row.

v1.0Implemented

Parameters

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

Request body

  • settings
    objectrequired
  • settings.base_currency
    string
  • settings.fiscal_year_start_month
    integer
  • settings.default_entity_id
    integer | null
  • settings.require_approval_above
    string | null
  • settings.recon_adjustment_limit
    string | null
    Largest bank reconciliation difference one person may post as an adjustment; null = under require_approval_above (none when that is null). Owner or manage_grants only.
  • settings.transfer_approval_cross_entity
    boolean
    Bank transfers between entities wait for a second person holding release_payments (default true). Owner or manage_grants only; audited.
  • settings.transfer_approval_above
    string | null
    Bank transfers at or above this amount wait for a second person holding release_payments; null = require_approval_above when that is set, else no amount rule. Owner or manage_grants only; audited.
  • settings.timezone
    string
    IANA time zone that decides the company's today: recurring and auto-reversal runs and every date default (form dates, report and REST as_of/to, void and reversal dates), never the UTC date. E.g. America/Los_Angeles
  • settings.control_accounts
    object
  • settings.reclass_control_accounts
    boolean
    Allow moving a system role off an account that already has posted activity (a deliberate reclass).
  • settings.loss_provision_unit
    string
    Loss provision unit of account (ASU 2016-20 election), recorded on each WIP row (lossProvisionUnit). Each WIP row is one contract with a single performance obligation. One of: contract, performance_obligation.
  • settings.finance_charge_monthly_pct
    string | null
    Monthly finance charge percent on past-due AR; null = none
  • settings.finance_charge_grace_days
    integer
    Days past due before a finance charge applies
  • settings.finance_charge_account_id
    integer | null
    Income account finance-charge invoices credit
  • settings.cecl_policy
    object | null
    ASC 326 (CECL) loss-rate policy used by the cecl_allowance report and posting; null = not set (the allowance refuses with 422).
  • settings.cecl_policy.ar_rates
    objectrequired
  • settings.cecl_policy.ar_rates.current
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.ar_rates.d1_30
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.ar_rates.d31_60
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.ar_rates.d61_90
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.ar_rates.d91_plus
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.ar_rates.disputed
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.retainage_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.cecl_policy.contract_asset_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • settings.sod_mode
    any
    Only a user with manage_coa and unrestricted entity access may change it (audited as sod_mode_changed). One of: strict, small_team.
  • settings.scheduler_user_id
    integer | null
    User the daily accounting jobs (recurring entries, auto-reversals, lease runs) run and are audited as; null = the first active company admin, flagged on the accounting home page. Must be an active company user with post_journal for every entity (422); only an accounting owner or a user who manages grants may change it (403).
  • settings.require_mfa_for
    any[]
    One of: view_ledger, post_journal, approve_journal, manage_coa, close_period, ap_enter, ap_approve, release_payments, manage_vendor_banking, ar_enter, ar_approve, payroll_view, payroll_run, view_payroll_pii, bank_reconcile, manage_integrations, manage_grants, job_forecast_edit.
  • settings.require_mfa_for_accounting
    boolean
  • settings.step_up_minutes
    integer

Response · 200 · object

  • company_id
    integerrequired
  • base_currency
    stringrequired
  • fiscal_year_start_month
    integerrequired
  • default_entity_id
    integer | nullrequired
  • posting_method
    anyrequired
    Stored and echoed only: every report is accrual basis. Cash-basis reporting is not built yet.
  • require_approval_above
    string | nullrequired
    Decimal amount as a string, 2 dp
  • recon_adjustment_limit
    string | nullrequired
    Decimal amount as a string, 2 dp
  • transfer_approval_cross_entity
    boolean
    Bank transfers between entities wait for a second person holding release_payments (default true).
  • transfer_approval_above
    string | null
    Bank transfers at or above this amount wait for a second person holding release_payments; null = require_approval_above when that is set, else no amount rule.
  • timezone
    stringrequired
    IANA time zone that decides the company's today: recurring and auto-reversal runs and every date default (form dates, report and REST as_of/to, void and reversal dates), never the UTC date. E.g. America/Los_Angeles
  • control_accounts
    object[]required
  • control_accounts[].role
    stringrequired
  • control_accounts[].label
    stringrequired
  • control_accounts[].account_id
    integer | nullrequired
  • control_accounts[].account_number
    string | nullrequired
  • control_accounts[].account_name
    string | nullrequired
  • updated_at
    string (date-time)required
  • loss_provision_unit
    stringrequired
    Loss provision unit of account (ASU 2016-20 election), recorded on each WIP row (lossProvisionUnit). Each WIP row is one contract with a single performance obligation. One of: contract, performance_obligation.
  • finance_charge_monthly_pct
    string | nullrequired
    Monthly finance charge percent on past-due AR; null = none
  • finance_charge_grace_days
    integerrequired
    Days past due before a finance charge applies
  • finance_charge_account_id
    integer | nullrequired
    Income account finance-charge invoices credit
  • cecl_policy
    object | nullrequired
    ASC 326 (CECL) loss-rate policy used by the cecl_allowance report and posting; null = not set (the allowance refuses with 422).
  • cecl_policy.ar_rates
    objectrequired
  • cecl_policy.retainage_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • cecl_policy.contract_asset_rate
    stringrequired
    Loss rate as a fraction of amortized cost (0.015 = 1.5%)
  • sod_mode
    anyrequired
    strict (default): a maker never approves their own document. small_team: a maker may approve or release their own bill, payment run or journal entry with a reason, flagged self_approved. One of: strict, small_team.
  • scheduler_user_id
    integer | nullrequired
    User the daily accounting jobs (recurring entries, auto-reversals, lease runs) run and are audited as; null = the first active company admin, flagged on the accounting home page. Must be an active company user with post_journal for every entity (422); only an accounting owner or a user who manages grants may change it (403).
  • require_mfa_for
    any[]required
    Flags that refuse a session or token whose user has no MFA (403 mfa_required). One of: view_ledger, post_journal, approve_journal, manage_coa, close_period, ap_enter, ap_approve, release_payments, manage_vendor_banking, ar_enter, ar_approve, payroll_view, payroll_run, view_payroll_pii, bank_reconcile, manage_integrations, manage_grants, job_forecast_edit.
  • require_mfa_for_accounting
    booleanrequired
    Every accounting call needs MFA; the accounting pages send a user without a factor to enrol.
  • step_up_minutes
    integerrequired
    How long an authenticator re-entry (step-up) stays valid. Default 10.

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/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/settings/edition

Get the accounting edition

The edition, its areas with admin overrides, the control policies in force, kept controls, recommended roles and the edition catalog. Any accounting grant (view_ledger). Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • edition
    string | nullrequired
    One of: essentials, professional, enterprise, null.
  • edition_name
    string | nullrequired
  • features
    objectrequired
  • features.apAutomation
    boolean
  • features.collections
    boolean
  • features.customerPortal
    boolean
  • features.qualifiedReviews
    boolean
  • features.wip
    boolean
  • features.retainage
    boolean
  • features.commitments
    boolean
  • features.closeCockpit
    boolean
  • features.reportBuilder
    boolean
  • features.fpa
    boolean
  • features.fixedAssets
    boolean
  • features.leases
    boolean
  • features.multiEntity
    boolean
  • features.intercompany
    boolean
  • features.consolidation
    boolean
  • features.multiCurrency
    boolean
  • features.dimensions
    boolean
  • overrides
    objectrequired
  • policies
    objectrequired
  • policies.sod_mode
    stringrequired
    One of: strict, small_team.
  • policies.require_approval_above
    string | nullrequired
  • policies.transfer_approval_above
    string | nullrequired
  • policies.transfer_approval_cross_entity
    booleanrequired
  • policies.recon_adjustment_limit
    string | nullrequired
  • policies.close_require_tasks
    booleanrequired
  • policies.close_require_recs
    booleanrequired
  • policies.require_mfa_for_accounting
    booleanrequired
  • policies.step_up_minutes
    integerrequired
  • policies.dunning
    booleanrequired
  • kept_controls
    string[]required
  • recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • areas
    object[]required
  • areas[].key
    stringrequired
  • areas[].label
    stringrequired
  • areas[].note
    stringrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required
  • editions
    object[]required
  • editions[].key
    stringrequired
    One of: essentials, professional, enterprise.
  • editions[].name
    stringrequired
  • editions[].audience
    stringrequired
  • editions[].features
    objectrequired
  • editions[].policies
    objectrequired
  • editions[].recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • applied
    object
  • applied.revision
    integerrequired
  • applied.kept_controls
    string[]required
  • applied.diff
    objectrequired

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/settings/edition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/settings/edition

Override edition areas

Shows or hides individual areas on top of the edition (setting an area back to its edition default clears the override) and switches AR dunning reminders (written to the collections settings; a reason is needed to switch them off, and switching off is refused while invoices are mid-cadence). Areas are navigation only. Audited (edition_overridden). Needs manage_coa on an unrestricted grant and an edition. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • edition
    objectrequired
  • edition.features
    object
  • edition.features.apAutomation
    boolean
  • edition.features.collections
    boolean
  • edition.features.customerPortal
    boolean
  • edition.features.qualifiedReviews
    boolean
  • edition.features.wip
    boolean
  • edition.features.retainage
    boolean
  • edition.features.commitments
    boolean
  • edition.features.closeCockpit
    boolean
  • edition.features.reportBuilder
    boolean
  • edition.features.fpa
    boolean
  • edition.features.fixedAssets
    boolean
  • edition.features.leases
    boolean
  • edition.features.multiEntity
    boolean
  • edition.features.intercompany
    boolean
  • edition.features.consolidation
    boolean
  • edition.features.multiCurrency
    boolean
  • edition.features.dimensions
    boolean
  • edition.dunning
    boolean
    AR collections dunning switch (acct_ar_collection_settings.dunning_enabled). Changing it needs ar_approve too. Switching it on creates the default policy when the company has none; switching it off needs reason and is refused (422 edition_downgrade_blocked) while open invoices are part-way through a dunning cadence.
  • edition.reason
    string
    Required when switching dunning off (422 edition_weaker_reason_required otherwise); audited.

Response · 200 · object

  • edition
    string | nullrequired
    One of: essentials, professional, enterprise, null.
  • edition_name
    string | nullrequired
  • features
    objectrequired
  • features.apAutomation
    boolean
  • features.collections
    boolean
  • features.customerPortal
    boolean
  • features.qualifiedReviews
    boolean
  • features.wip
    boolean
  • features.retainage
    boolean
  • features.commitments
    boolean
  • features.closeCockpit
    boolean
  • features.reportBuilder
    boolean
  • features.fpa
    boolean
  • features.fixedAssets
    boolean
  • features.leases
    boolean
  • features.multiEntity
    boolean
  • features.intercompany
    boolean
  • features.consolidation
    boolean
  • features.multiCurrency
    boolean
  • features.dimensions
    boolean
  • overrides
    objectrequired
  • policies
    objectrequired
  • policies.sod_mode
    stringrequired
    One of: strict, small_team.
  • policies.require_approval_above
    string | nullrequired
  • policies.transfer_approval_above
    string | nullrequired
  • policies.transfer_approval_cross_entity
    booleanrequired
  • policies.recon_adjustment_limit
    string | nullrequired
  • policies.close_require_tasks
    booleanrequired
  • policies.close_require_recs
    booleanrequired
  • policies.require_mfa_for_accounting
    booleanrequired
  • policies.step_up_minutes
    integerrequired
  • policies.dunning
    booleanrequired
  • kept_controls
    string[]required
  • recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • areas
    object[]required
  • areas[].key
    stringrequired
  • areas[].label
    stringrequired
  • areas[].note
    stringrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required
  • editions
    object[]required
  • editions[].key
    stringrequired
    One of: essentials, professional, enterprise.
  • editions[].name
    stringrequired
  • editions[].audience
    stringrequired
  • editions[].features
    objectrequired
  • editions[].policies
    objectrequired
  • editions[].recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • applied
    object
  • applied.revision
    integerrequired
  • applied.kept_controls
    string[]required
  • applied.diff
    objectrequired

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
  • 422No edition chosen yet, or an invalid body

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/settings/edition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "edition": {}
}'

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/settings/edition

Apply an edition

Applies the edition previewed with GET settings/edition/preview: confirm_hash must equal that preview's hash (409 edition_preview_stale otherwise). A weaker control needs a reason (422 edition_weaker_reason_required) unless keep_controls keeps every weaker control at its current value; an in-use control (required reconciliations or close tasks in open periods, or dunning while open invoices are mid-cadence) is refused (422 edition_downgrade_blocked) unless keep_controls. Area overrides reset to the edition. Dunning is written to the AR collections settings (ar_approve), creating the default policy when switched on in a company with none. Never deletes data. Audited (edition_applied, plus the settings control actions). Needs manage_coa and manage_grants on an unrestricted grant, and step-up. Requires the accounting:write scope.

v1.0Implemented

Parameters

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

Request body

  • edition
    objectrequired
  • edition.key
    stringrequired
    One of: essentials, professional, enterprise.
  • edition.confirm_hash
    stringrequired
  • edition.keep_controls
    boolean
  • edition.reason
    string

Response · 200 · object

  • edition
    string | nullrequired
    One of: essentials, professional, enterprise, null.
  • edition_name
    string | nullrequired
  • features
    objectrequired
  • features.apAutomation
    boolean
  • features.collections
    boolean
  • features.customerPortal
    boolean
  • features.qualifiedReviews
    boolean
  • features.wip
    boolean
  • features.retainage
    boolean
  • features.commitments
    boolean
  • features.closeCockpit
    boolean
  • features.reportBuilder
    boolean
  • features.fpa
    boolean
  • features.fixedAssets
    boolean
  • features.leases
    boolean
  • features.multiEntity
    boolean
  • features.intercompany
    boolean
  • features.consolidation
    boolean
  • features.multiCurrency
    boolean
  • features.dimensions
    boolean
  • overrides
    objectrequired
  • policies
    objectrequired
  • policies.sod_mode
    stringrequired
    One of: strict, small_team.
  • policies.require_approval_above
    string | nullrequired
  • policies.transfer_approval_above
    string | nullrequired
  • policies.transfer_approval_cross_entity
    booleanrequired
  • policies.recon_adjustment_limit
    string | nullrequired
  • policies.close_require_tasks
    booleanrequired
  • policies.close_require_recs
    booleanrequired
  • policies.require_mfa_for_accounting
    booleanrequired
  • policies.step_up_minutes
    integerrequired
  • policies.dunning
    booleanrequired
  • kept_controls
    string[]required
  • recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • areas
    object[]required
  • areas[].key
    stringrequired
  • areas[].label
    stringrequired
  • areas[].note
    stringrequired
  • revision
    integerrequired
  • updated_at
    string | null (date-time)required
  • editions
    object[]required
  • editions[].key
    stringrequired
    One of: essentials, professional, enterprise.
  • editions[].name
    stringrequired
  • editions[].audience
    stringrequired
  • editions[].features
    objectrequired
  • editions[].policies
    objectrequired
  • editions[].recommended_roles
    string[]required
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
  • applied
    object
  • applied.revision
    integerrequired
  • applied.kept_controls
    string[]required
  • applied.diff
    objectrequired

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 edition change differs from the confirmed preview
  • 422Weaker controls without a reason, or an in-use control the edition would switch off

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/settings/edition" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "edition": {
    "key": "essentials",
    "confirm_hash": "string"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/settings/edition/preview

Preview an edition change

Every area and policy the edition would change, the direction of each control change (stronger or weaker), warnings for hidden areas that hold data, blocked in-use controls, and the hash to confirm with. edition defaults to the current edition. Needs manage_coa. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • edition
    stringquery
    One of: essentials, professional, enterprise.

Response · 200 · object

  • from
    string | nullrequired
  • to
    stringrequired
    One of: essentials, professional, enterprise.
  • hash
    stringrequired
  • weaker
    string[]required
  • blocked
    string[]required
  • features
    object[]required
  • features[].key
    stringrequired
  • features[].label
    stringrequired
  • features[].from
    booleanrequired
  • features[].to
    booleanrequired
  • features[].warning
    string | nullrequired
  • policies
    object[]required
  • policies[].key
    stringrequired
  • policies[].label
    stringrequired
  • policies[].from
    string | boolean | integer | nullrequired
  • policies[].to
    string | boolean | integer | nullrequired
  • policies[].direction
    stringrequired
    One of: stronger, weaker, same, changed.
  • policies[].control
    booleanrequired
  • policies[].blocked
    string | nullrequired
  • policies[].warning
    string | nullrequired

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 edition

Example request

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

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/settings/setup

Get guided setup progress

Each step's status (an explicit mark, else what the data proves), the first open step, the profile and its recommendation, and the go-live checklist. Needs manage_coa. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object

  • steps
    object[]required
  • steps[].key
    stringrequired
    One of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
  • steps[].title
    stringrequired
  • steps[].status
    stringrequired
    One of: done, skipped, pending.
  • steps[].marked
    booleanrequired
  • steps[].skippable
    booleanrequired
  • current
    string | nullrequired
    One of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live, null.
  • profile
    object | nullrequired
  • profile.industry
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • profile.employees
    integerrequired
  • profile.entities
    integerrequired
  • profile.foreign_operations
    booleanrequired
  • profile.audited
    booleanrequired
  • profile.payroll
    booleanrequired
  • industry_pack
    string | nullrequired
  • recommendation
    object | nullrequired
  • recommendation.edition
    stringrequired
    One of: essentials, professional, enterprise.
  • recommendation.pack
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • checklist
    object[]required
  • checklist[].key
    stringrequired
  • checklist[].label
    stringrequired
  • checklist[].ok
    booleanrequired
  • checklist[].detail
    stringrequired
  • checklist[].href
    string | nullrequired
  • completed_at
    string | null (date-time)required
  • revision
    integerrequired

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/settings/setup" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

PUT /rest/v1.0/companies/{company_id}/accounting/settings/setup

Record a setup step

Marks a step done, skipped (bank accounts, opening balances, users only) or pending again. Idempotent: the same mark again writes nothing. Steps proved by data (edition, chart, entities, bank accounts, opening balances) are done only when the data exists; go_live only when every checklist item passes. Audited (setup_step_recorded, setup_completed). 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

Request body

  • setup
    objectrequired
  • setup.step
    stringrequired
    One of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
  • setup.status
    stringrequired
    One of: done, skipped, pending.
  • setup.profile
    object
  • setup.profile.industry
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • setup.profile.employees
    integerrequired
  • setup.profile.entities
    integerrequired
  • setup.profile.foreign_operations
    booleanrequired
  • setup.profile.audited
    booleanrequired
  • setup.profile.payroll
    booleanrequired

Response · 200 · object

  • steps
    object[]required
  • steps[].key
    stringrequired
    One of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
  • steps[].title
    stringrequired
  • steps[].status
    stringrequired
    One of: done, skipped, pending.
  • steps[].marked
    booleanrequired
  • steps[].skippable
    booleanrequired
  • current
    string | nullrequired
    One of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live, null.
  • profile
    object | nullrequired
  • profile.industry
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • profile.employees
    integerrequired
  • profile.entities
    integerrequired
  • profile.foreign_operations
    booleanrequired
  • profile.audited
    booleanrequired
  • profile.payroll
    booleanrequired
  • industry_pack
    string | nullrequired
  • recommendation
    object | nullrequired
  • recommendation.edition
    stringrequired
    One of: essentials, professional, enterprise.
  • recommendation.pack
    stringrequired
    One of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
  • checklist
    object[]required
  • checklist[].key
    stringrequired
  • checklist[].label
    stringrequired
  • checklist[].ok
    booleanrequired
  • checklist[].detail
    stringrequired
  • checklist[].href
    string | nullrequired
  • completed_at
    string | null (date-time)required
  • revision
    integerrequired

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
  • 422A step that cannot be skipped, unfinished data, or a failing go-live checklist

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/settings/setup" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "setup": {
    "step": "profile",
    "status": "done"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/tax_codes

List tax codes

Sales and use tax codes. Each code has one or more components, each with its own rate and liability account; total_rate is their sum. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: sales, use.
  • is_active
    booleanrequired
  • total_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components
    object[]required
  • components[].id
    integerrequired
  • components[].name
    stringrequired
  • components[].rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components[].account_id
    integerrequired

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/tax_codes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

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

Create a tax code

Adds a tax code with its components. Component accounts must be postable accounts of this company. 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

  • tax_code
    objectrequired
  • tax_code.code
    stringrequired
  • tax_code.name
    stringrequired
  • tax_code.kind
    any
    One of: sales, use.
  • tax_code.is_active
    boolean
  • tax_code.components
    object[]required
  • tax_code.components[].name
    stringrequired
  • tax_code.components[].rate
    stringrequired
    Percent, up to 6 dp
  • tax_code.components[].account_id
    integerrequired

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: sales, use.
  • is_active
    booleanrequired
  • total_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components
    object[]required
  • components[].id
    integerrequired
  • components[].name
    stringrequired
  • components[].rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components[].account_id
    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
  • 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/tax_codes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "tax_code": {
    "code": "string",
    "name": "string",
    "components": [
      {
        "name": "string",
        "rate": "0.00",
        "account_id": 1
      }
    ]
  }
}'

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/tax_codes/{id}

Update a tax code

Edits a tax code; components replaces every component. 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

  • tax_code
    objectrequired
  • tax_code.code
    string
  • tax_code.name
    string
  • tax_code.kind
    any
    One of: sales, use.
  • tax_code.is_active
    boolean
  • tax_code.components
    object[]
  • tax_code.components[].name
    stringrequired
  • tax_code.components[].rate
    stringrequired
    Percent, up to 6 dp
  • tax_code.components[].account_id
    integerrequired

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • kind
    anyrequired
    One of: sales, use.
  • is_active
    booleanrequired
  • total_rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components
    object[]required
  • components[].id
    integerrequired
  • components[].name
    stringrequired
  • components[].rate
    stringrequired
    Decimal rate or quantity as a string, 6 dp
  • components[].account_id
    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
  • 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/tax_codes/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "tax_code": {}
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificates

List customer tax exemption certificates

Up to 500, optionally for one customer. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • customer_id
    integerrequired
  • state_code
    stringrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string (date) | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace
  • 422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)

Example request

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

Accounting / Accounting Settings

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

Record a customer tax exemption certificate

A certificate valid on the invoice date in the job state removes sales tax from pay-app invoices and blocks it on manual invoices; once expired, tax applies and the invoice carries a warning. 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

  • certificate
    objectrequired
  • certificate.customer_id
    integerrequired
  • certificate.state_code
    stringrequired
  • certificate.certificate_number
    stringrequired
  • certificate.reason
    stringrequired
  • certificate.effective_from
    string (date)required
  • certificate.expires_on
    string (date) | null

Response · 201 · object

  • id
    integerrequired
  • customer_id
    integerrequired
  • state_code
    stringrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string (date) | nullrequired

Errors

  • 400Malformed JSON body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace
  • 404Not found in this company
  • 422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/tax_exemption_certificates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "certificate": {
    "customer_id": 1,
    "state_code": "string",
    "certificate_number": "string",
    "reason": "string",
    "effective_from": "2026-11-01"
  }
}'

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificates/{id}

Change a certificate expiry

Only expires_on changes; enter a new certificate for other corrections. 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

  • certificate
    objectrequired
  • certificate.expires_on
    string (date) | nullrequired

Response · 200 · object

  • id
    integerrequired
  • customer_id
    integerrequired
  • state_code
    stringrequired
  • certificate_number
    stringrequired
  • reason
    stringrequired
  • effective_from
    string (date)required
  • expires_on
    string (date) | nullrequired

Errors

  • 400Malformed JSON body
  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace
  • 404Not found in this company
  • 422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/tax_exemption_certificates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "certificate": {
    "expires_on": "2026-11-01"
  }
}'

Accounting / Accounting Settings

GET /rest/v1.0/companies/{company_id}/accounting/terms

List payment terms

Company payment terms with due days and optional early-payment discount. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • due_days
    integerrequired
  • discount_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • discount_days
    integer | nullrequired
  • is_active
    booleanrequired

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/terms" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Accounting / Accounting Settings

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

Create a payment term

Adds a term such as Net 30 or 2% 10, net 30. 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

  • term
    objectrequired
  • term.code
    stringrequired
  • term.name
    stringrequired
  • term.due_days
    integerrequired
  • term.discount_percent
    string | null
  • term.discount_days
    integer | null
  • term.is_active
    boolean

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • due_days
    integerrequired
  • discount_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • discount_days
    integer | nullrequired
  • is_active
    booleanrequired

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
  • 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/terms" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "term": {
    "code": "string",
    "name": "string",
    "due_days": 1
  }
}'

Accounting / Accounting Settings

PATCH /rest/v1.0/companies/{company_id}/accounting/terms/{id}

Update a payment term

Edits or deactivates a term. 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

  • term
    objectrequired
  • term.code
    string
  • term.name
    string
  • term.due_days
    integer
  • term.discount_percent
    string | null
  • term.discount_days
    integer | null
  • term.is_active
    boolean

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • due_days
    integerrequired
  • discount_percent
    string | nullrequired
    Decimal rate or quantity as a string, 6 dp
  • discount_days
    integer | nullrequired
  • is_active
    booleanrequired

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/terms/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "term": {}
}'

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