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.
- GET
/rest/v1.0/companies/{company_id}/accounting/dimensionsList dimensions - POST
/rest/v1.0/companies/{company_id}/accounting/dimensionsCreate a dimension - GET
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}Show a dimension - PATCH
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}Update a dimension - GET
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/historyDimension history - GET
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rulesList a dimension's requirement rules - PUT
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/rulesReplace a dimension's requirement rules - GET
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/valuesList a dimension's values - POST
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/valuesCreate a dimension value - GET
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}Show a dimension value - PATCH
/rest/v1.0/companies/{company_id}/accounting/dimensions/{id}/values/{value_id}Update a dimension value - GET
/rest/v1.0/companies/{company_id}/accounting/entitiesList legal entities - POST
/rest/v1.0/companies/{company_id}/accounting/entitiesCreate a legal entity - GET
/rest/v1.0/companies/{company_id}/accounting/entities/{id}Show a legal entity - PATCH
/rest/v1.0/companies/{company_id}/accounting/entities/{id}Update a legal entity - GET
/rest/v1.0/companies/{company_id}/accounting/job_tax_profiles/{id}Get a job tax profile - PUT
/rest/v1.0/companies/{company_id}/accounting/job_tax_profiles/{id}Set a job tax profile - GET
/rest/v1.0/companies/{company_id}/accounting/party_profilesList party profiles - POST
/rest/v1.0/companies/{company_id}/accounting/party_profilesCreate a party profile - GET
/rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}Show a party profile - PATCH
/rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}Update a party profile - POST
/rest/v1.0/companies/{company_id}/accounting/party_profiles/{id}/sensitive_changeApprove or reject a routing/bank/TIN change - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/ar_invoices/{id}/determinationsAn invoice's sales tax determinations - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappingsList cost type taxability categories - PUT
/rest/v1.0/companies/{company_id}/accounting/sales_tax/category_mappingsSet a cost type taxability category - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/certificatesList exemption and resale certificates - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/certificatesAdd a certificate - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}Show a certificate - PATCH
/rest/v1.0/companies/{company_id}/accounting/sales_tax/certificates/{id}Renew or revoke a certificate - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filingsList sales tax returns - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filingsPrepare a sales tax return - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}Show a sales tax return - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/decisionMark a return filed, or cancel it - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/exportFiling-prep export (CSV) - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/filings/{id}/paymentLink a return's payment - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_setsList jurisdiction sets - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_setsAdd a jurisdiction set - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}Show a jurisdiction set - PATCH
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdiction_sets/{id}Change a jurisdiction set - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictionsList tax jurisdictions - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictionsAdd a tax jurisdiction - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}Show a tax jurisdiction - PATCH
/rest/v1.0/companies/{company_id}/accounting/sales_tax/jurisdictions/{id}Change a tax jurisdiction - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/liabilitySales and use tax liability by jurisdiction - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sitesList job sites - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}Show a project's job site - PUT
/rest/v1.0/companies/{company_id}/accounting/sales_tax/project_sites/{id}Set a project's job site - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/ratesList tax rates - DELETE
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}Delete an unused tax rate - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/{id}/reviewRecord a qualified review of a rate - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/importImport tax rates from CSV - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rates/provider_syncImport rates from a provider adapter - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rulesList taxability rules - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rulesAdd a taxability rule - PATCH
/rest/v1.0/companies/{company_id}/accounting/sales_tax/rules/{id}Change or end a taxability rule - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/settingsSales tax settings - PUT
/rest/v1.0/companies/{company_id}/accounting/sales_tax/settingsUpdate sales tax settings - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accrualsList use tax accruals - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accrualsAccrue use tax on a posted bill - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}Show a use tax accrual - POST
/rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/accruals/{id}/reverseReverse a use tax accrual - GET
/rest/v1.0/companies/{company_id}/accounting/sales_tax/use_tax/candidatesBills that may owe use tax - GET
/rest/v1.0/companies/{company_id}/accounting/settingsShow accounting settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/settingsUpdate accounting settings - GET
/rest/v1.0/companies/{company_id}/accounting/settings/editionGet the accounting edition - PATCH
/rest/v1.0/companies/{company_id}/accounting/settings/editionOverride edition areas - PUT
/rest/v1.0/companies/{company_id}/accounting/settings/editionApply an edition - GET
/rest/v1.0/companies/{company_id}/accounting/settings/edition/previewPreview an edition change - GET
/rest/v1.0/companies/{company_id}/accounting/settings/setupGet guided setup progress - PUT
/rest/v1.0/companies/{company_id}/accounting/settings/setupRecord a setup step - GET
/rest/v1.0/companies/{company_id}/accounting/tax_codesList tax codes - POST
/rest/v1.0/companies/{company_id}/accounting/tax_codesCreate a tax code - PATCH
/rest/v1.0/companies/{company_id}/accounting/tax_codes/{id}Update a tax code - GET
/rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificatesList customer tax exemption certificates - POST
/rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificatesRecord a customer tax exemption certificate - PATCH
/rest/v1.0/companies/{company_id}/accounting/tax_exemption_certificates/{id}Change a certificate expiry - GET
/rest/v1.0/companies/{company_id}/accounting/termsList payment terms - POST
/rest/v1.0/companies/{company_id}/accounting/termsCreate a payment term - 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/dimensionsList dimensions
Every dimension with its values and requirement rules, by position then code. active=true lists active dimensions only. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- activestringqueryOne of: true, false.
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- kindstringrequiredOne of: department, division, location, custom.
- descriptionstring | nullrequired
- default_requirementstringrequiredOne of: optional, required.
- is_activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- valuesobject[]required
- values[].idintegerrequired
- values[].dimension_idintegerrequired
- values[].codestringrequired
- values[].namestringrequired
- values[].descriptionstring | nullrequired
- values[].parent_idinteger | nullrequired
- values[].effective_fromstring | null (date)required
- values[].effective_tostring | null (date)required
- values[].entity_idsinteger[]required
- values[].is_activebooleanrequired
- values[].created_atstring (date-time)required
- values[].updated_atstring (date-time)required
- rulesobject[]required
- rules[].idintegerrequired
- rules[].account_idinteger | nullrequired
- rules[].account_typestring | nullrequiredOne 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_fromstring | nullrequired
- rules[].account_tostring | nullrequired
- rules[].requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace
Example request
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/dimensionsCreate a dimension
Needs manage_coa on an unrestricted grant. Codes are unique per company (case-insensitive). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- dimensionobjectrequired
- dimension.codestringrequired
- dimension.namestringrequired
- dimension.kindstringOne of: department, division, location, custom.
- dimension.descriptionstring | null
- dimension.default_requirementstringOne of: optional, required.
- dimension.is_activeboolean
- dimension.positioninteger
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindstringrequiredOne of: department, division, location, custom.
- descriptionstring | nullrequired
- default_requirementstringrequiredOne of: optional, required.
- is_activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- valuesobject[]required
- values[].idintegerrequired
- values[].dimension_idintegerrequired
- values[].codestringrequired
- values[].namestringrequired
- values[].descriptionstring | nullrequired
- values[].parent_idinteger | nullrequired
- values[].effective_fromstring | null (date)required
- values[].effective_tostring | null (date)required
- values[].entity_idsinteger[]required
- values[].is_activebooleanrequired
- values[].created_atstring (date-time)required
- values[].updated_atstring (date-time)required
- rulesobject[]required
- rules[].idintegerrequired
- rules[].account_idinteger | nullrequired
- rules[].account_typestring | nullrequiredOne 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_fromstring | nullrequired
- rules[].account_tostring | nullrequired
- rules[].requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace409Idempotency-Key conflict422Validation failed
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindstringrequiredOne of: department, division, location, custom.
- descriptionstring | nullrequired
- default_requirementstringrequiredOne of: optional, required.
- is_activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- valuesobject[]required
- values[].idintegerrequired
- values[].dimension_idintegerrequired
- values[].codestringrequired
- values[].namestringrequired
- values[].descriptionstring | nullrequired
- values[].parent_idinteger | nullrequired
- values[].effective_fromstring | null (date)required
- values[].effective_tostring | null (date)required
- values[].entity_idsinteger[]required
- values[].is_activebooleanrequired
- values[].created_atstring (date-time)required
- values[].updated_atstring (date-time)required
- rulesobject[]required
- rules[].idintegerrequired
- rules[].account_idinteger | nullrequired
- rules[].account_typestring | nullrequiredOne 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_fromstring | nullrequired
- rules[].account_tostring | nullrequired
- rules[].requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- dimensionobjectrequired
- dimension.codestring
- dimension.namestring
- dimension.kindstringOne of: department, division, location, custom.
- dimension.descriptionstring | null
- dimension.default_requirementstringOne of: optional, required.
- dimension.is_activeboolean
- dimension.positioninteger
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindstringrequiredOne of: department, division, location, custom.
- descriptionstring | nullrequired
- default_requirementstringrequiredOne of: optional, required.
- is_activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- valuesobject[]required
- values[].idintegerrequired
- values[].dimension_idintegerrequired
- values[].codestringrequired
- values[].namestringrequired
- values[].descriptionstring | nullrequired
- values[].parent_idinteger | nullrequired
- values[].effective_fromstring | null (date)required
- values[].effective_tostring | null (date)required
- values[].entity_idsinteger[]required
- values[].is_activebooleanrequired
- values[].created_atstring (date-time)required
- values[].updated_atstring (date-time)required
- rulesobject[]required
- rules[].idintegerrequired
- rules[].account_idinteger | nullrequired
- rules[].account_typestring | nullrequiredOne 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_fromstring | nullrequired
- rules[].account_tostring | nullrequired
- rules[].requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found422Validation failed
Example request
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}/historyDimension 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- item_typestringrequiredOne of: AcctDimension, AcctDimensionValue.
- item_idintegerrequired
- actionstringrequired
- summarystringrequired
- actor_idintegerrequired
- changesobject | array | nullrequired
- atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found
Example request
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}/rulesList a dimension's requirement rules
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- account_idinteger | nullrequired
- account_typestring | nullrequiredOne 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_fromstring | nullrequired
- account_tostring | nullrequired
- requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found
Example request
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}/rulesReplace 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rulesobject[]required
- rules[].account_idinteger | null
- rules[].account_typestring | nullOne 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_fromstring | null
- rules[].account_tostring | null
- rules[].requirementstringrequiredOne of: optional, required.
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindstringrequiredOne of: department, division, location, custom.
- descriptionstring | nullrequired
- default_requirementstringrequiredOne of: optional, required.
- is_activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- valuesobject[]required
- values[].idintegerrequired
- values[].dimension_idintegerrequired
- values[].codestringrequired
- values[].namestringrequired
- values[].descriptionstring | nullrequired
- values[].parent_idinteger | nullrequired
- values[].effective_fromstring | null (date)required
- values[].effective_tostring | null (date)required
- values[].entity_idsinteger[]required
- values[].is_activebooleanrequired
- values[].created_atstring (date-time)required
- values[].updated_atstring (date-time)required
- rulesobject[]required
- rules[].idintegerrequired
- rules[].account_idinteger | nullrequired
- rules[].account_typestring | nullrequiredOne 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_fromstring | nullrequired
- rules[].account_tostring | nullrequired
- rules[].requirementstringrequiredOne of: optional, required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found422Validation failed
Example request
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}/valuesList a dimension's values
By code; parent_id gives the roll-up hierarchy. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- dimension_idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- parent_idinteger | nullrequired
- effective_fromstring | null (date)required
- effective_tostring | null (date)required
- entity_idsinteger[]required
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found
Example request
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}/valuesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- valueobjectrequired
- value.codestringrequired
- value.namestringrequired
- value.descriptionstring | null
- value.parent_idinteger | null
- value.effective_fromstring | null (date)
- value.effective_tostring | null (date)
- value.entity_idsinteger[]
- value.is_activeboolean
Response · 201 · object
- idintegerrequired
- dimension_idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- parent_idinteger | nullrequired
- effective_fromstring | null (date)required
- effective_tostring | null (date)required
- entity_idsinteger[]required
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found409Idempotency-Key conflict422Validation failed
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- value_idintegerpathrequired
Response · 200 · object
- idintegerrequired
- dimension_idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- parent_idinteger | nullrequired
- effective_fromstring | null (date)required
- effective_tostring | null (date)required
- entity_idsinteger[]required
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- value_idintegerpathrequired
Request body
- valueobjectrequired
- value.codestring
- value.namestring
- value.descriptionstring | null
- value.parent_idinteger | null
- value.effective_fromstring | null (date)
- value.effective_tostring | null (date)
- value.entity_idsinteger[]
- value.is_activeboolean
Response · 200 · object
- idintegerrequired
- dimension_idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- parent_idinteger | nullrequired
- effective_fromstring | null (date)required
- effective_tostring | null (date)required
- entity_idsinteger[]required
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission (manage_coa for writes), an entity-restricted or project-scoped grant writing, wrong company, or read-only workspace404Not found422Validation failed
Example request
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/entitiesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- legal_namestring | nullrequired
- is_activebooleanrequired
- intercompany_due_to_account_idinteger | nullrequired
- intercompany_due_from_account_idinteger | nullrequired
- tax_id_last4string | nullrequired
- addressstring | nullrequired
- citystring | nullrequired
- statestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- is_eliminationbooleanrequiredThe consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
- retained_earnings_account_idinteger | nullrequiredRetained 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 token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/entities" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
POST/rest/v1.0/companies/{company_id}/accounting/entitiesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- entityobjectrequired
- entity.codestringrequired
- entity.namestringrequired
- entity.legal_namestring | null
- entity.is_activeboolean
- entity.intercompany_due_to_account_idinteger | null
- entity.intercompany_due_from_account_idinteger | null
- entity.is_eliminationbooleanCreate the consolidation elimination entity (one per company).
- entity.tax_idstring | nullPayer EIN for 1099 issuer records; stored encrypted, only tax_id_last4 is returned.
- entity.addressstring | null
- entity.citystring | null
- entity.statestring | null
- entity.zipstring | null
- entity.phonestring | null
- entity.retained_earnings_account_idinteger | nullRetained 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
- idintegerrequired
- codestringrequired
- namestringrequired
- legal_namestring | nullrequired
- is_activebooleanrequired
- intercompany_due_to_account_idinteger | nullrequired
- intercompany_due_from_account_idinteger | nullrequired
- tax_id_last4string | nullrequired
- addressstring | nullrequired
- citystring | nullrequired
- statestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- is_eliminationbooleanrequiredThe consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
- retained_earnings_account_idinteger | nullrequiredRetained 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- legal_namestring | nullrequired
- is_activebooleanrequired
- intercompany_due_to_account_idinteger | nullrequired
- intercompany_due_from_account_idinteger | nullrequired
- tax_id_last4string | nullrequired
- addressstring | nullrequired
- citystring | nullrequired
- statestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- is_eliminationbooleanrequiredThe consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
- retained_earnings_account_idinteger | nullrequiredRetained 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- entityobjectrequired
- entity.codestring
- entity.namestring
- entity.legal_namestring | null
- entity.is_activeboolean
- entity.intercompany_due_to_account_idinteger | null
- entity.intercompany_due_from_account_idinteger | null
- entity.tax_idstring | nullPayer EIN for 1099 issuer records; stored encrypted, only tax_id_last4 is returned.
- entity.addressstring | null
- entity.citystring | null
- entity.statestring | null
- entity.zipstring | null
- entity.phonestring | null
- entity.retained_earnings_account_idinteger | nullRetained 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
- idintegerrequired
- codestringrequired
- namestringrequired
- legal_namestring | nullrequired
- is_activebooleanrequired
- intercompany_due_to_account_idinteger | nullrequired
- intercompany_due_from_account_idinteger | nullrequired
- tax_id_last4string | nullrequired
- addressstring | nullrequired
- citystring | nullrequired
- statestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- is_eliminationbooleanrequiredThe consolidation elimination book: takes only CL entries; never the default entity. Set at creation only; at most one per company.
- retained_earnings_account_idinteger | nullrequiredRetained 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- as_ofstring (date)query
Response · 200 · object
- project_idintegerrequired
- state_codestringrequired
- contract_typestringrequiredOne of: lump_sum, separated.
- sales_tax_code_idinteger | nullrequiredJob-site sales tax code billed to the owner (retailer and gross-receipts models); the pay-app bridge applies it.
- use_tax_code_idinteger | nullrequiredUse tax code accrued on untaxed material bills (consumer model).
- as_ofstring (date)required
- modelstringrequiredOne of: consumer, retailer_on_separated, gross_receipts, retail_sale_of_construction.
- charge_customerbooleanrequired
- accrue_use_taxbooleanrequired
- fixturesstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace404Not found in this company422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- tax_profileobjectrequired
- tax_profile.state_codestringrequired
- tax_profile.contract_typestringrequiredOne of: lump_sum, separated.
- tax_profile.sales_tax_code_idinteger | null
- tax_profile.use_tax_code_idinteger | null
Response · 200 · object
- project_idintegerrequired
- state_codestringrequired
- contract_typestringrequiredOne of: lump_sum, separated.
- sales_tax_code_idinteger | nullrequiredJob-site sales tax code billed to the owner (retailer and gross-receipts models); the pay-app bridge applies it.
- use_tax_code_idinteger | nullrequiredUse tax code accrued on untaxed material bills (consumer model).
- as_ofstring (date)required
- modelstringrequiredOne of: consumer, retailer_on_separated, gross_receipts, retail_sale_of_construction.
- charge_customerbooleanrequired
- accrue_use_taxbooleanrequired
- fixturesstring | nullrequired
Errors
400Malformed JSON body401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace404Not found in this company422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)
Example request
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_profilesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- filters[role]anyqueryVendors or customers One of: vendor, customer.
- searchstringqueryVendor name
- pageintegerquery
- per_pageintegerquery
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- is_vendorbooleanrequired
- is_customerbooleanrequired
- tax_id_maskedstring | nullrequired
- tax_id_typestring | nullrequired
- is_1099booleanrequired
- form_1099_typestring | nullrequired
- form_1099_boxstring | nullrequired
- tax_classificationstring | nullrequiredW-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_statusanyrequiredOne of: not_requested, requested, received, expired.
- w9_received_atstring | null (date)required
- term_idinteger | nullrequired
- remit_to_namestring | nullrequired
- remit_to_addressstring | nullrequired
- remit_to_citystring | nullrequired
- remit_to_statestring | nullrequired
- remit_to_zipstring | nullrequired
- default_expense_account_idinteger | nullrequired
- payment_methodanyrequiredOne of: check, ach, wire, card.
- bank_account_maskedstring | nullrequired
- bank_account_typestring | nullrequired
- has_bank_routingbooleanrequired
- retainage_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- compliance_holdbooleanrequired
- compliance_hold_reasonstring | nullrequired
- credit_limitstring | nullrequiredDecimal amount as a string, 2 dp
- billing_contact_namestring | nullrequired
- billing_emailstring | null (email)required
- billing_addressstring | nullrequired
- pending_sensitive_changeobject | nullrequired
- pending_sensitive_change.reasonstring | nullReason entered by the proposer.
- pending_sensitive_change.requested_by_idintegerrequired
- pending_sensitive_change.fieldsstring[]required
- pending_sensitive_change.changesobject[]requiredWhat the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
- pending_sensitive_change.change_hashstringrequiredSHA-256 of the pending change; echo it when deciding.
- revealedobject
- revealed.tax_idstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- tin_match_codeinteger | nullrequiredLatest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
- tin_matched_atstring | null (date)required
- bank_account_ownershipstring | nullWho owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/party_profiles" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
POST/rest/v1.0/companies/{company_id}/accounting/party_profilesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- party_profileobjectrequired
- party_profile.vendor_idintegerrequired
- party_profile.is_vendorboolean
- party_profile.is_customerboolean
- party_profile.is_1099boolean
- party_profile.form_1099_typestring | null
- party_profile.form_1099_boxstring | null
- party_profile.tax_classificationstring | nullW-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_statusanyOne of: not_requested, requested, received, expired.
- party_profile.w9_received_atstring | null (date)
- party_profile.term_idinteger | null
- party_profile.reasonstring | nullRequired for non-default remit-to/payment method proposals.
- party_profile.remit_to_namestring | null
- party_profile.remit_to_addressstring | null
- party_profile.remit_to_citystring | null
- party_profile.remit_to_statestring | null
- party_profile.remit_to_zipstring | null
- party_profile.default_expense_account_idinteger | null
- party_profile.payment_methodanyOne of: check, ach, wire, card.
- party_profile.bank_account_typestring | null
- party_profile.compliance_holdboolean
- party_profile.compliance_hold_reasonstring | null
- party_profile.tax_idstring | null9-digit EIN or SSN; applied only after a second person approves
- party_profile.tax_id_typeanyOne of: ein, ssn, null.
- party_profile.bank_account_numberstring | null
- party_profile.bank_routing_numberstring | null
- party_profile.retainage_percentstring | null
- party_profile.credit_limitstring | null
- party_profile.billing_contact_namestring | null
- party_profile.billing_emailstring | null (email)
- party_profile.billing_addressstring | null
- party_profile.bank_account_ownershipstring | nullNeeds manage_vendor_banking. One of: business, consumer, null.
Response · 201 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- is_vendorbooleanrequired
- is_customerbooleanrequired
- tax_id_maskedstring | nullrequired
- tax_id_typestring | nullrequired
- is_1099booleanrequired
- form_1099_typestring | nullrequired
- form_1099_boxstring | nullrequired
- tax_classificationstring | nullrequiredW-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_statusanyrequiredOne of: not_requested, requested, received, expired.
- w9_received_atstring | null (date)required
- term_idinteger | nullrequired
- remit_to_namestring | nullrequired
- remit_to_addressstring | nullrequired
- remit_to_citystring | nullrequired
- remit_to_statestring | nullrequired
- remit_to_zipstring | nullrequired
- default_expense_account_idinteger | nullrequired
- payment_methodanyrequiredOne of: check, ach, wire, card.
- bank_account_maskedstring | nullrequired
- bank_account_typestring | nullrequired
- has_bank_routingbooleanrequired
- retainage_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- compliance_holdbooleanrequired
- compliance_hold_reasonstring | nullrequired
- credit_limitstring | nullrequiredDecimal amount as a string, 2 dp
- billing_contact_namestring | nullrequired
- billing_emailstring | null (email)required
- billing_addressstring | nullrequired
- pending_sensitive_changeobject | nullrequired
- pending_sensitive_change.reasonstring | nullReason entered by the proposer.
- pending_sensitive_change.requested_by_idintegerrequired
- pending_sensitive_change.fieldsstring[]required
- pending_sensitive_change.changesobject[]requiredWhat the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
- pending_sensitive_change.change_hashstringrequiredSHA-256 of the pending change; echo it when deciding.
- revealedobject
- revealed.tax_idstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- tin_match_codeinteger | nullrequiredLatest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
- tin_matched_atstring | null (date)required
- bank_account_ownershipstring | nullWho 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- revealanyqueryDecrypt TIN and bank numbers One of: true, false.
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- is_vendorbooleanrequired
- is_customerbooleanrequired
- tax_id_maskedstring | nullrequired
- tax_id_typestring | nullrequired
- is_1099booleanrequired
- form_1099_typestring | nullrequired
- form_1099_boxstring | nullrequired
- tax_classificationstring | nullrequiredW-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_statusanyrequiredOne of: not_requested, requested, received, expired.
- w9_received_atstring | null (date)required
- term_idinteger | nullrequired
- remit_to_namestring | nullrequired
- remit_to_addressstring | nullrequired
- remit_to_citystring | nullrequired
- remit_to_statestring | nullrequired
- remit_to_zipstring | nullrequired
- default_expense_account_idinteger | nullrequired
- payment_methodanyrequiredOne of: check, ach, wire, card.
- bank_account_maskedstring | nullrequired
- bank_account_typestring | nullrequired
- has_bank_routingbooleanrequired
- retainage_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- compliance_holdbooleanrequired
- compliance_hold_reasonstring | nullrequired
- credit_limitstring | nullrequiredDecimal amount as a string, 2 dp
- billing_contact_namestring | nullrequired
- billing_emailstring | null (email)required
- billing_addressstring | nullrequired
- pending_sensitive_changeobject | nullrequired
- pending_sensitive_change.reasonstring | nullReason entered by the proposer.
- pending_sensitive_change.requested_by_idintegerrequired
- pending_sensitive_change.fieldsstring[]required
- pending_sensitive_change.changesobject[]requiredWhat the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
- pending_sensitive_change.change_hashstringrequiredSHA-256 of the pending change; echo it when deciding.
- revealedobject
- revealed.tax_idstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- tin_match_codeinteger | nullrequiredLatest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
- tin_matched_atstring | null (date)required
- bank_account_ownershipstring | nullWho owns the receiving bank account: consumer (personal) accounts get PPD entries, business accounts CCD. One of: business, consumer, null.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company429Too many reveals; retry after the Retry-After seconds.
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- party_profileobjectrequired
- party_profile.is_vendorboolean
- party_profile.is_customerboolean
- party_profile.is_1099boolean
- party_profile.form_1099_typestring | null
- party_profile.form_1099_boxstring | null
- party_profile.tax_classificationstring | nullW-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_statusanyOne of: not_requested, requested, received, expired.
- party_profile.w9_received_atstring | null (date)
- party_profile.term_idinteger | null
- party_profile.remit_to_namestring | null
- party_profile.remit_to_addressstring | null
- party_profile.remit_to_citystring | null
- party_profile.remit_to_statestring | null
- party_profile.remit_to_zipstring | null
- party_profile.default_expense_account_idinteger | null
- party_profile.payment_methodanyOne of: check, ach, wire, card.
- party_profile.bank_account_typestring | null
- party_profile.compliance_holdboolean
- party_profile.compliance_hold_reasonstring | null
- party_profile.reasonstring | nullRequired (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_idstring | null9-digit EIN or SSN; applied only after a second person approves
- party_profile.tax_id_typeanyOne of: ein, ssn, null.
- party_profile.bank_account_numberstring | null
- party_profile.bank_routing_numberstring | null
- party_profile.retainage_percentstring | null
- party_profile.credit_limitstring | null
- party_profile.billing_contact_namestring | null
- party_profile.billing_emailstring | null (email)
- party_profile.billing_addressstring | null
- party_profile.bank_account_ownershipstring | nullNeeds manage_vendor_banking. One of: business, consumer, null.
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- is_vendorbooleanrequired
- is_customerbooleanrequired
- tax_id_maskedstring | nullrequired
- tax_id_typestring | nullrequired
- is_1099booleanrequired
- form_1099_typestring | nullrequired
- form_1099_boxstring | nullrequired
- tax_classificationstring | nullrequiredW-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_statusanyrequiredOne of: not_requested, requested, received, expired.
- w9_received_atstring | null (date)required
- term_idinteger | nullrequired
- remit_to_namestring | nullrequired
- remit_to_addressstring | nullrequired
- remit_to_citystring | nullrequired
- remit_to_statestring | nullrequired
- remit_to_zipstring | nullrequired
- default_expense_account_idinteger | nullrequired
- payment_methodanyrequiredOne of: check, ach, wire, card.
- bank_account_maskedstring | nullrequired
- bank_account_typestring | nullrequired
- has_bank_routingbooleanrequired
- retainage_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- compliance_holdbooleanrequired
- compliance_hold_reasonstring | nullrequired
- credit_limitstring | nullrequiredDecimal amount as a string, 2 dp
- billing_contact_namestring | nullrequired
- billing_emailstring | null (email)required
- billing_addressstring | nullrequired
- pending_sensitive_changeobject | nullrequired
- pending_sensitive_change.reasonstring | nullReason entered by the proposer.
- pending_sensitive_change.requested_by_idintegerrequired
- pending_sensitive_change.fieldsstring[]required
- pending_sensitive_change.changesobject[]requiredWhat the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
- pending_sensitive_change.change_hashstringrequiredSHA-256 of the pending change; echo it when deciding.
- revealedobject
- revealed.tax_idstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- tin_match_codeinteger | nullrequiredLatest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
- tin_matched_atstring | null (date)required
- bank_account_ownershipstring | nullWho 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/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_changeApprove 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionanyrequiredOne of: approve, reject.
- change_hashstringrequiredpending_sensitive_change.change_hash of the change you reviewed.
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- is_vendorbooleanrequired
- is_customerbooleanrequired
- tax_id_maskedstring | nullrequired
- tax_id_typestring | nullrequired
- is_1099booleanrequired
- form_1099_typestring | nullrequired
- form_1099_boxstring | nullrequired
- tax_classificationstring | nullrequiredW-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_statusanyrequiredOne of: not_requested, requested, received, expired.
- w9_received_atstring | null (date)required
- term_idinteger | nullrequired
- remit_to_namestring | nullrequired
- remit_to_addressstring | nullrequired
- remit_to_citystring | nullrequired
- remit_to_statestring | nullrequired
- remit_to_zipstring | nullrequired
- default_expense_account_idinteger | nullrequired
- payment_methodanyrequiredOne of: check, ach, wire, card.
- bank_account_maskedstring | nullrequired
- bank_account_typestring | nullrequired
- has_bank_routingbooleanrequired
- retainage_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- compliance_holdbooleanrequired
- compliance_hold_reasonstring | nullrequired
- credit_limitstring | nullrequiredDecimal amount as a string, 2 dp
- billing_contact_namestring | nullrequired
- billing_emailstring | null (email)required
- billing_addressstring | nullrequired
- pending_sensitive_changeobject | nullrequired
- pending_sensitive_change.reasonstring | nullReason entered by the proposer.
- pending_sensitive_change.requested_by_idintegerrequired
- pending_sensitive_change.fieldsstring[]required
- pending_sensitive_change.changesobject[]requiredWhat the approver reviews: exact before/after remit-to, payment method and types; TIN and bank numbers masked to last 4.
- pending_sensitive_change.change_hashstringrequiredSHA-256 of the pending change; echo it when deciding.
- revealedobject
- revealed.tax_idstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- tin_match_codeinteger | nullrequiredLatest IRS TIN Matching result indicator; 1-3 hold payments (tin_mismatch). Cleared when the TIN changes.
- tin_matched_atstring | null (date)required
- bank_account_ownershipstring | nullWho 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company409The 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
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}/determinationsAn 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: ar_invoice, use_tax_accrual.
- line_nointegerrequired
- ar_invoice_line_idinteger | nullrequired
- accrual_idinteger | nullrequired
- bill_line_idinteger | nullrequired
- entity_idintegerrequired
- project_idinteger | nullrequired
- party_idintegerrequired
- jurisdiction_idintegerrequired
- jurisdiction_codestring | nullrequired
- kindstringrequiredOne of: sales, use.
- tax_datestring (date)required
- categorystring | nullrequired
- taxabilitystringrequiredOne of: taxable, exempt, nontaxable.
- base_amountstringrequired
- ratestringrequired
- tax_amountstringrequired
- rate_idinteger | nullrequired
- rule_idinteger | nullrequired
- certificate_idinteger | nullrequired
- account_idinteger | nullrequired
- notestring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_mappingsList cost type taxability categories
AP lines without their own tax category take their cost type's. Any accounting grant. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- cost_type_idintegerrequired
- categorystringrequiredOne of: material, fixture, labor, equipment.
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_mappingsSet a cost type taxability category
category null clears it (response null). Needs manage_coa; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- mappingobjectrequired
- mapping.cost_type_idintegerrequired
- mapping.categorystring | nullrequiredOne of: material, fixture, labor, equipment, null.
Response · 200 · object | null
- cost_type_idintegerrequired
- categorystringrequiredOne of: material, fixture, labor, equipment.
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/certificatesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- party_typestringqueryFilter by party type One of: customer, vendor.
- party_idintegerqueryFilter by party
Response · 200 · object[]
- idintegerrequired
- party_typestringrequiredOne of: customer, vendor.
- party_idintegerrequired
- kindstringrequiredOne of: exemption, resale.
- jurisdiction_idintegerrequired
- project_idinteger | nullrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring | null (date)required
- revoked_atstring | null (date-time)required
- revoke_reasonstring | nullrequired
- statusstringrequiredOne of: active, expired, revoked, future.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/certificatesAdd 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- certificateobjectrequired
- certificate.party_typestringrequiredOne of: customer, vendor.
- certificate.party_idintegerrequired
- certificate.kindstringrequiredOne of: exemption, resale.
- certificate.jurisdiction_idintegerrequired
- certificate.project_idinteger | null
- certificate.certificate_numberstringrequired
- certificate.reasonstringrequired
- certificate.effective_fromstring (date)required
- certificate.expires_onstring | null (date)
Response · 201 · object
- idintegerrequired
- party_typestringrequiredOne of: customer, vendor.
- party_idintegerrequired
- kindstringrequiredOne of: exemption, resale.
- jurisdiction_idintegerrequired
- project_idinteger | nullrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring | null (date)required
- revoked_atstring | null (date-time)required
- revoke_reasonstring | nullrequired
- statusstringrequiredOne of: active, expired, revoked, future.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- party_typestringrequiredOne of: customer, vendor.
- party_idintegerrequired
- kindstringrequiredOne of: exemption, resale.
- jurisdiction_idintegerrequired
- project_idinteger | nullrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring | null (date)required
- revoked_atstring | null (date-time)required
- revoke_reasonstring | nullrequired
- statusstringrequiredOne of: active, expired, revoked, future.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- certificateobjectrequired
- certificate.expires_onstring | null (date)
- certificate.revoke_reasonstring
Response · 200 · object
- idintegerrequired
- party_typestringrequiredOne of: customer, vendor.
- party_idintegerrequired
- kindstringrequiredOne of: exemption, resale.
- jurisdiction_idintegerrequired
- project_idinteger | nullrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring | null (date)required
- revoked_atstring | null (date-time)required
- revoke_reasonstring | nullrequired
- statusstringrequiredOne of: active, expired, revoked, future.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/filingsList sales tax returns
Project-scoped grants refused; entity-scoped grants see their entities. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- jurisdiction_idintegerqueryFilter by jurisdiction
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- jurisdiction_idintegerrequired
- period_startstring (date)required
- period_endstring (date)required
- statusstringrequiredOne of: prepared, filed, superseded, cancelled, amended.
- is_amendmentbooleanrequired
- tax_duestringrequired
- evidence_hashstringrequired
- staleboolean | nullrequired
- figuresobjectrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- filed_by_idinteger | nullrequired
- filed_atstring | null (date-time)required
- filed_onstring | null (date)required
- confirmation_numberstring | nullrequired
- cancel_reasonstring | nullrequired
- paymentnull | objectrequired
- payment.sourcestringrequired
- payment.source_idintegerrequired
- payment.entry_idintegerrequired
- payment.amountstring | nullrequired
- payment.linked_by_idinteger | nullrequired
- payment.linked_atstring | null (date-time)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/filingsPrepare 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filingobjectrequired
- filing.entity_idintegerrequired
- filing.jurisdiction_idintegerrequired
- filing.period_startstring (date)required
- filing.period_endstring (date)required
- filing.amendmentboolean
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- jurisdiction_idintegerrequired
- period_startstring (date)required
- period_endstring (date)required
- statusstringrequiredOne of: prepared, filed, superseded, cancelled, amended.
- is_amendmentbooleanrequired
- tax_duestringrequired
- evidence_hashstringrequired
- staleboolean | nullrequired
- figuresobjectrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- filed_by_idinteger | nullrequired
- filed_atstring | null (date-time)required
- filed_onstring | null (date)required
- confirmation_numberstring | nullrequired
- cancel_reasonstring | nullrequired
- paymentnull | objectrequired
- payment.sourcestringrequired
- payment.source_idintegerrequired
- payment.entry_idintegerrequired
- payment.amountstring | nullrequired
- payment.linked_by_idinteger | nullrequired
- payment.linked_atstring | null (date-time)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- jurisdiction_idintegerrequired
- period_startstring (date)required
- period_endstring (date)required
- statusstringrequiredOne of: prepared, filed, superseded, cancelled, amended.
- is_amendmentbooleanrequired
- tax_duestringrequired
- evidence_hashstringrequired
- staleboolean | nullrequired
- figuresobjectrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- filed_by_idinteger | nullrequired
- filed_atstring | null (date-time)required
- filed_onstring | null (date)required
- confirmation_numberstring | nullrequired
- cancel_reasonstring | nullrequired
- paymentnull | objectrequired
- payment.sourcestringrequired
- payment.source_idintegerrequired
- payment.entry_idintegerrequired
- payment.amountstring | nullrequired
- payment.linked_by_idinteger | nullrequired
- payment.linked_atstring | null (date-time)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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}/decisionMark 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- decisionobjectrequired
- decision.actionstringrequiredOne of: mark_filed, cancel.
- decision.filed_onstring (date)
- decision.confirmation_numberstring
- decision.reasonstring
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- jurisdiction_idintegerrequired
- period_startstring (date)required
- period_endstring (date)required
- statusstringrequiredOne of: prepared, filed, superseded, cancelled, amended.
- is_amendmentbooleanrequired
- tax_duestringrequired
- evidence_hashstringrequired
- staleboolean | nullrequired
- figuresobjectrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- filed_by_idinteger | nullrequired
- filed_atstring | null (date-time)required
- filed_onstring | null (date)required
- confirmation_numberstring | nullrequired
- cancel_reasonstring | nullrequired
- paymentnull | objectrequired
- payment.sourcestringrequired
- payment.source_idintegerrequired
- payment.entry_idintegerrequired
- payment.amountstring | nullrequired
- payment.linked_by_idinteger | nullrequired
- payment.linked_atstring | null (date-time)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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}/exportFiling-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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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}/paymentLink 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- paymentobjectrequired
- payment.sourcestringrequiredOne of: journal_entry, ap_bill.
- payment.idintegerrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- jurisdiction_idintegerrequired
- period_startstring (date)required
- period_endstring (date)required
- statusstringrequiredOne of: prepared, filed, superseded, cancelled, amended.
- is_amendmentbooleanrequired
- tax_duestringrequired
- evidence_hashstringrequired
- staleboolean | nullrequired
- figuresobjectrequired
- prepared_by_idintegerrequired
- prepared_atstring (date-time)required
- filed_by_idinteger | nullrequired
- filed_atstring | null (date-time)required
- filed_onstring | null (date)required
- confirmation_numberstring | nullrequired
- cancel_reasonstring | nullrequired
- paymentnull | objectrequired
- payment.sourcestringrequired
- payment.source_idintegerrequired
- payment.entry_idintegerrequired
- payment.amountstring | nullrequired
- payment.linked_by_idinteger | nullrequired
- payment.linked_atstring | null (date-time)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_setsList jurisdiction sets
The jurisdictions that tax one place, chosen per job site. Any accounting grant. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- jurisdictionsobject[]required
- jurisdictions[].idintegerrequired
- jurisdictions[].codestringrequired
- jurisdictions[].namestringrequired
- jurisdictions[].levelstringrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_setsAdd a jurisdiction set
Jurisdictions of one state. Needs manage_coa; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- jurisdiction_setobjectrequired
- jurisdiction_set.codestringrequired
- jurisdiction_set.namestringrequired
- jurisdiction_set.descriptionstring | null
- jurisdiction_set.jurisdiction_idsinteger[]required
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- jurisdictionsobject[]required
- jurisdictions[].idintegerrequired
- jurisdictions[].codestringrequired
- jurisdictions[].namestringrequired
- jurisdictions[].levelstringrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- jurisdictionsobject[]required
- jurisdictions[].idintegerrequired
- jurisdictions[].codestringrequired
- jurisdictions[].namestringrequired
- jurisdictions[].levelstringrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- jurisdiction_setobjectrequired
- jurisdiction_set.namestring
- jurisdiction_set.descriptionstring | null
- jurisdiction_set.jurisdiction_idsinteger[]
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- descriptionstring | nullrequired
- jurisdictionsobject[]required
- jurisdictions[].idintegerrequired
- jurisdictions[].codestringrequired
- jurisdictions[].namestringrequired
- jurisdictions[].levelstringrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/jurisdictionsList tax jurisdictions
State, county, city and special-district jurisdictions the company maintains. Any accounting grant. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- state_codestringqueryFilter by state
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- levelstringrequiredOne of: state, county, city, special_district.
- state_codestringrequired
- parent_idinteger | nullrequired
- files_with_idinteger | nullrequired
- filing_frequencystringrequiredOne of: monthly, quarterly, annual.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- is_demobooleanrequired
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/jurisdictionsAdd a tax jurisdiction
Needs manage_coa over every entity; audited. State code ZZ marks fictional demo data. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- jurisdictionobjectrequired
- jurisdiction.codestringrequired
- jurisdiction.namestringrequired
- jurisdiction.levelstringrequiredOne of: state, county, city, special_district.
- jurisdiction.state_codestringrequired
- jurisdiction.parent_idinteger | null
- jurisdiction.files_with_idinteger | null
- jurisdiction.filing_frequencystringOne of: monthly, quarterly, annual.
- jurisdiction.sales_payable_account_idinteger | null
- jurisdiction.use_payable_account_idinteger | null
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- levelstringrequiredOne of: state, county, city, special_district.
- state_codestringrequired
- parent_idinteger | nullrequired
- files_with_idinteger | nullrequired
- filing_frequencystringrequiredOne of: monthly, quarterly, annual.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- is_demobooleanrequired
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- levelstringrequiredOne of: state, county, city, special_district.
- state_codestringrequired
- parent_idinteger | nullrequired
- files_with_idinteger | nullrequired
- filing_frequencystringrequiredOne of: monthly, quarterly, annual.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- is_demobooleanrequired
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- ratesobject[]required
- rates[].idintegerrequired
- rates[].jurisdiction_idintegerrequired
- rates[].jurisdiction_codestring | nullrequired
- rates[].effective_fromstring (date)required
- rates[].sales_ratestringrequired
- rates[].use_ratestringrequired
- rates[].sourcestringrequiredOne of: csv, provider, seed.
- rates[].source_citationstring | nullrequired
- rates[].import_refstring | nullrequired
- rates[].needs_reviewbooleanrequired
- rates[].reviewed_by_idinteger | nullrequired
- rates[].reviewed_atstring | null (date-time)required
- rates[].review_notestring | nullrequired
- rates[].usedbooleanrequired
- rates[].used_atstring | null (date-time)required
- rates[].created_by_idintegerrequired
- rates[].created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- jurisdictionobjectrequired
- jurisdiction.namestring
- jurisdiction.parent_idinteger | null
- jurisdiction.files_with_idinteger | null
- jurisdiction.filing_frequencystringOne of: monthly, quarterly, annual.
- jurisdiction.sales_payable_account_idinteger | null
- jurisdiction.use_payable_account_idinteger | null
- jurisdiction.is_activeboolean
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- levelstringrequiredOne of: state, county, city, special_district.
- state_codestringrequired
- parent_idinteger | nullrequired
- files_with_idinteger | nullrequired
- filing_frequencystringrequiredOne of: monthly, quarterly, annual.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- is_demobooleanrequired
- is_activebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/liabilitySales 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)queryrequiredPeriod start
- tostring (date)queryrequiredPeriod end
- entity_idintegerqueryEntity
- jurisdiction_idintegerqueryA filing jurisdiction and those that file with it
Response · 200 · object
- fromstring (date)required
- tostring (date)required
- entity_idsarray | nullrequired
- jurisdictionsobject[]required
- jurisdictions[].jurisdiction_idintegerrequired
- jurisdictions[].codestringrequired
- jurisdictions[].namestringrequired
- jurisdictions[].levelstringrequired
- jurisdictions[].files_with_idinteger | nullrequired
- jurisdictions[].salesobjectrequired
- jurisdictions[].useobjectrequired
- jurisdictions[].by_rateobject[]required
- jurisdictions[].exempt_certificatesobject[]required
- totalsobjectrequired
- totals.sales_taxstringrequired
- totals.use_taxstringrequired
- totals.taxable_salesstringrequired
- totals.exempt_salesstringrequired
- tie_outobject[]required
- tie_out[].account_idintegerrequired
- tie_out[].numberstringrequired
- tie_out[].namestringrequired
- tie_out[].gl_movementstringrequired
- tie_out[].tagged_taxstringrequired
- tie_out[].filing_paymentsstringrequired
- tie_out[].otherstringrequired
- tie_out[].other_entriesobject[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_sitesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- project_idintegerrequired
- jurisdiction_set_idintegerrequired
- address_line1stringrequired
- citystringrequired
- regionstringrequired
- postal_codestringrequired
- contract_typestringrequiredOne of: lump_sum, time_and_materials.
- contract_naturestringrequiredOne of: real_property, retail_sale.
- default_categorystringrequiredOne of: material, fixture, labor, equipment.
- updated_by_idintegerrequired
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- project_idintegerrequired
- jurisdiction_set_idintegerrequired
- address_line1stringrequired
- citystringrequired
- regionstringrequired
- postal_codestringrequired
- contract_typestringrequiredOne of: lump_sum, time_and_materials.
- contract_naturestringrequiredOne of: real_property, retail_sale.
- default_categorystringrequiredOne of: material, fixture, labor, equipment.
- updated_by_idintegerrequired
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- siteobjectrequired
- site.jurisdiction_set_idintegerrequired
- site.address_line1stringrequired
- site.citystringrequired
- site.regionstringrequired
- site.postal_codestringrequired
- site.contract_typestringrequiredOne of: lump_sum, time_and_materials.
- site.contract_naturestringrequiredOne of: real_property, retail_sale.
- site.default_categorystringOne of: material, fixture, labor, equipment.
Response · 200 · object
- project_idintegerrequired
- jurisdiction_set_idintegerrequired
- address_line1stringrequired
- citystringrequired
- regionstringrequired
- postal_codestringrequired
- contract_typestringrequiredOne of: lump_sum, time_and_materials.
- contract_naturestringrequiredOne of: real_property, retail_sale.
- default_categorystringrequiredOne of: material, fixture, labor, equipment.
- updated_by_idintegerrequired
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/ratesList tax rates
Effective-dated sales and use rates (percent). A used rate is immutable. Any accounting grant. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- jurisdiction_idintegerqueryFilter by jurisdiction
- needs_reviewstringqueryFilter by qualified-review state One of: true, false.
Response · 200 · object[]
- idintegerrequired
- jurisdiction_idintegerrequired
- jurisdiction_codestring | nullrequired
- effective_fromstring (date)required
- sales_ratestringrequired
- use_ratestringrequired
- sourcestringrequiredOne of: csv, provider, seed.
- source_citationstring | nullrequired
- import_refstring | nullrequired
- needs_reviewbooleanrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- usedbooleanrequired
- used_atstring | null (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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}/reviewRecord 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- jurisdiction_idintegerrequired
- jurisdiction_codestring | nullrequired
- effective_fromstring (date)required
- sales_ratestringrequired
- use_ratestringrequired
- sourcestringrequiredOne of: csv, provider, seed.
- source_citationstring | nullrequired
- import_refstring | nullrequired
- needs_reviewbooleanrequired
- reviewed_by_idinteger | nullrequired
- reviewed_atstring | null (date-time)required
- review_notestring | nullrequired
- usedbooleanrequired
- used_atstring | null (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/importImport 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- importobjectrequired
- import.csvstringrequired
- import.dry_runboolean
Response · 200 · object
- dry_runbooleanrequired
- sha256stringrequired
- createdintegerrequired
- unchangedintegerrequired
- jurisdictions_createdintegerrequired
- errorsobject[]required
- errors[].lineintegerrequired
- errors[].messagestringrequired
- rowsobject[]required
- rows[].lineintegerrequired
- rows[].jurisdiction_codestringrequired
- rows[].effective_fromstring (date)required
- rows[].sales_ratestringrequired
- rows[].use_ratestringrequired
- rows[].source_citationstring | null
- rows[].actionstringrequiredOne of: create, unchanged.
- rows[].createobject
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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_syncImport 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- syncobjectrequired
- sync.providerstringrequired
- sync.as_ofstring (date)required
- sync.jurisdiction_codesstring[]required
- sync.dry_runboolean
Response · 200 · object
- dry_runbooleanrequired
- sha256stringrequired
- createdintegerrequired
- unchangedintegerrequired
- jurisdictions_createdintegerrequired
- errorsobject[]required
- errors[].lineintegerrequired
- errors[].messagestringrequired
- rowsobject[]required
- rows[].lineintegerrequired
- rows[].jurisdiction_codestringrequired
- rows[].effective_fromstring (date)required
- rows[].sales_ratestringrequired
- rows[].use_ratestringrequired
- rows[].source_citationstring | null
- rows[].actionstringrequiredOne of: create, unchanged.
- rows[].createobject
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/rulesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- jurisdiction_idintegerqueryFilter by jurisdiction
Response · 200 · object[]
- idintegerrequired
- jurisdiction_idintegerrequired
- contract_naturestringrequiredOne of: real_property, retail_sale, any.
- contract_typestringrequiredOne of: lump_sum, time_and_materials, any.
- categorystringrequiredOne of: material, fixture, labor, equipment, any.
- contractor_rolestringrequiredOne of: consumer, retailer.
- sales_taxablebooleanrequired
- use_taxablebooleanrequired
- effective_fromstring (date)required
- effective_tostring | null (date)required
- notestring | nullrequired
- source_citationstring | nullrequired
- needs_reviewbooleanrequired
- usedbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/rulesAdd 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- ruleobjectrequired
- rule.jurisdiction_idintegerrequired
- rule.contract_naturestringOne of: real_property, retail_sale, any.
- rule.contract_typestringOne of: lump_sum, time_and_materials, any.
- rule.categorystringrequiredOne of: material, fixture, labor, equipment, any.
- rule.contractor_rolestringrequiredOne of: consumer, retailer.
- rule.sales_taxablebooleanrequired
- rule.use_taxablebooleanrequired
- rule.effective_fromstring (date)required
- rule.effective_tostring | null (date)
- rule.notestring | null
- rule.source_citationstring | null
Response · 201 · object
- idintegerrequired
- jurisdiction_idintegerrequired
- contract_naturestringrequiredOne of: real_property, retail_sale, any.
- contract_typestringrequiredOne of: lump_sum, time_and_materials, any.
- categorystringrequiredOne of: material, fixture, labor, equipment, any.
- contractor_rolestringrequiredOne of: consumer, retailer.
- sales_taxablebooleanrequired
- use_taxablebooleanrequired
- effective_fromstring (date)required
- effective_tostring | null (date)required
- notestring | nullrequired
- source_citationstring | nullrequired
- needs_reviewbooleanrequired
- usedbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- ruleobjectrequired
- rule.effective_tostring | null (date)
- rule.notestring | null
- rule.source_citationstring | null
- rule.sales_taxableboolean
- rule.use_taxableboolean
- rule.contractor_rolestringOne of: consumer, retailer.
Response · 200 · object
- idintegerrequired
- jurisdiction_idintegerrequired
- contract_naturestringrequiredOne of: real_property, retail_sale, any.
- contract_typestringrequiredOne of: lump_sum, time_and_materials, any.
- categorystringrequiredOne of: material, fixture, labor, equipment, any.
- contractor_rolestringrequiredOne of: consumer, retailer.
- sales_taxablebooleanrequired
- use_taxablebooleanrequired
- effective_fromstring (date)required
- effective_tostring | null (date)required
- notestring | nullrequired
- source_citationstring | nullrequired
- needs_reviewbooleanrequired
- usedbooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/settingsSales 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- roundingstringrequiredOne of: line, invoice.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- home_jurisdiction_set_idinteger | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/settingsUpdate sales tax settings
Needs manage_coa over every entity; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- settingsobjectrequired
- settings.roundingstringOne of: line, invoice.
- settings.sales_payable_account_idinteger | null
- settings.use_payable_account_idinteger | null
- settings.home_jurisdiction_set_idinteger | null
Response · 200 · object
- roundingstringrequiredOne of: line, invoice.
- sales_payable_account_idinteger | nullrequired
- use_payable_account_idinteger | nullrequired
- home_jurisdiction_set_idinteger | nullrequired
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/accrualsList use tax accruals
Project-scoped grants refused; entity-scoped grants see their entities. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- bill_idintegerqueryFilter by bill
Response · 200 · object[]
- idintegerrequired
- entity_idintegerrequired
- bill_idintegerrequired
- vendor_idintegerrequired
- posting_datestring (date)required
- statusstringrequiredOne of: posted, reversed.
- vendor_tax_chargedstringrequired
- owed_totalstringrequired
- accrued_totalstringrequired
- overridesobject[]required
- overrides[].bill_line_idintegerrequired
- overrides[].actionstringrequiredOne of: exclude, include.
- overrides[].reasonstringrequired
- linesobject[]required
- lines[].bill_line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].categorystring | nullrequired
- lines[].set_idinteger | nullrequired
- lines[].dispositionstringrequired
- lines[].reasonstring | nullrequired
- lines[].taxstringrequired
- warningsstring[]required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- reversal_reasonstring | nullrequired
- detailsobject[]required
- details[].bill_line_idinteger | nullrequired
- details[].jurisdiction_idintegerrequired
- details[].taxabilitystringrequired
- details[].base_amountstringrequired
- details[].ratestringrequired
- details[].tax_amountstringrequired
- details[].account_idinteger | nullrequired
- details[].notestring | nullrequired
- created_by_idintegerrequired
- reversed_by_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/accrualsAccrue 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- accrualobjectrequired
- accrual.bill_idintegerrequired
- accrual.posting_datestring | null (date)
- accrual.vendor_tax_chargedstring
- accrual.overridesobject[]
- accrual.overrides[].bill_line_idintegerrequired
- accrual.overrides[].actionstringrequiredOne of: exclude, include.
- accrual.overrides[].reasonstringrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- bill_idintegerrequired
- vendor_idintegerrequired
- posting_datestring (date)required
- statusstringrequiredOne of: posted, reversed.
- vendor_tax_chargedstringrequired
- owed_totalstringrequired
- accrued_totalstringrequired
- overridesobject[]required
- overrides[].bill_line_idintegerrequired
- overrides[].actionstringrequiredOne of: exclude, include.
- overrides[].reasonstringrequired
- linesobject[]required
- lines[].bill_line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].categorystring | nullrequired
- lines[].set_idinteger | nullrequired
- lines[].dispositionstringrequired
- lines[].reasonstring | nullrequired
- lines[].taxstringrequired
- warningsstring[]required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- reversal_reasonstring | nullrequired
- detailsobject[]required
- details[].bill_line_idinteger | nullrequired
- details[].jurisdiction_idintegerrequired
- details[].taxabilitystringrequired
- details[].base_amountstringrequired
- details[].ratestringrequired
- details[].tax_amountstringrequired
- details[].account_idinteger | nullrequired
- details[].notestring | nullrequired
- created_by_idintegerrequired
- reversed_by_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- bill_idintegerrequired
- vendor_idintegerrequired
- posting_datestring (date)required
- statusstringrequiredOne of: posted, reversed.
- vendor_tax_chargedstringrequired
- owed_totalstringrequired
- accrued_totalstringrequired
- overridesobject[]required
- overrides[].bill_line_idintegerrequired
- overrides[].actionstringrequiredOne of: exclude, include.
- overrides[].reasonstringrequired
- linesobject[]required
- lines[].bill_line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].categorystring | nullrequired
- lines[].set_idinteger | nullrequired
- lines[].dispositionstringrequired
- lines[].reasonstring | nullrequired
- lines[].taxstringrequired
- warningsstring[]required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- reversal_reasonstring | nullrequired
- detailsobject[]required
- details[].bill_line_idinteger | nullrequired
- details[].jurisdiction_idintegerrequired
- details[].taxabilitystringrequired
- details[].base_amountstringrequired
- details[].ratestringrequired
- details[].tax_amountstringrequired
- details[].account_idinteger | nullrequired
- details[].notestring | nullrequired
- created_by_idintegerrequired
- reversed_by_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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}/reverseReverse 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reversalobjectrequired
- reversal.datestring (date)required
- reversal.reasonstringrequired
Response · 200 · object
- idintegerrequired
- entity_idintegerrequired
- bill_idintegerrequired
- vendor_idintegerrequired
- posting_datestring (date)required
- statusstringrequiredOne of: posted, reversed.
- vendor_tax_chargedstringrequired
- owed_totalstringrequired
- accrued_totalstringrequired
- overridesobject[]required
- overrides[].bill_line_idintegerrequired
- overrides[].actionstringrequiredOne of: exclude, include.
- overrides[].reasonstringrequired
- linesobject[]required
- lines[].bill_line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].categorystring | nullrequired
- lines[].set_idinteger | nullrequired
- lines[].dispositionstringrequired
- lines[].reasonstring | nullrequired
- lines[].taxstringrequired
- warningsstring[]required
- entry_idinteger | nullrequired
- reversal_entry_idinteger | nullrequired
- reversal_reasonstring | nullrequired
- detailsobject[]required
- details[].bill_line_idinteger | nullrequired
- details[].jurisdiction_idintegerrequired
- details[].taxabilitystringrequired
- details[].base_amountstringrequired
- details[].ratestringrequired
- details[].tax_amountstringrequired
- details[].account_idinteger | nullrequired
- details[].notestring | nullrequired
- created_by_idintegerrequired
- reversed_by_idinteger | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token404Not found in this company409Conflict: a used rate or rule, a standing accrual, a filed return, changed figures, or an Idempotency-Key reuse422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/candidatesBills 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)queryrequiredPosting date from
- tostring (date)queryrequiredPosting date to
- entity_idintegerqueryEntity
Response · 200 · object[]
- bill_idintegerrequired
- numberstringrequired
- vendor_idintegerrequired
- entity_idintegerrequired
- posting_datestring (date)required
- invoice_datestring (date)required
- owedstringrequired
- gapsstring[]required
- warningsstring[]required
- linesobject[]required
- lines[].bill_line_idintegerrequired
- lines[].line_nointegerrequired
- lines[].amountstringrequired
- lines[].categorystring | nullrequired
- lines[].set_idinteger | nullrequired
- lines[].dispositionstringrequired
- lines[].reasonstring | nullrequired
- lines[].taxstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity outside the grant, a project-scoped grant, or read-only token422Validation failed, a setup gap, a closed period, or a refused import
Example request
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/settingsShow 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- company_idintegerrequired
- base_currencystringrequired
- fiscal_year_start_monthintegerrequired
- default_entity_idinteger | nullrequired
- posting_methodanyrequiredStored and echoed only: every report is accrual basis. Cash-basis reporting is not built yet.
- require_approval_abovestring | nullrequiredDecimal amount as a string, 2 dp
- recon_adjustment_limitstring | nullrequiredDecimal amount as a string, 2 dp
- transfer_approval_cross_entitybooleanBank transfers between entities wait for a second person holding release_payments (default true).
- transfer_approval_abovestring | nullBank 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.
- timezonestringrequiredIANA 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_accountsobject[]required
- control_accounts[].rolestringrequired
- control_accounts[].labelstringrequired
- control_accounts[].account_idinteger | nullrequired
- control_accounts[].account_numberstring | nullrequired
- control_accounts[].account_namestring | nullrequired
- updated_atstring (date-time)required
- loss_provision_unitstringrequiredLoss 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_pctstring | nullrequiredMonthly finance charge percent on past-due AR; null = none
- finance_charge_grace_daysintegerrequiredDays past due before a finance charge applies
- finance_charge_account_idinteger | nullrequiredIncome account finance-charge invoices credit
- cecl_policyobject | nullrequiredASC 326 (CECL) loss-rate policy used by the cecl_allowance report and posting; null = not set (the allowance refuses with 422).
- cecl_policy.ar_ratesobjectrequired
- cecl_policy.retainage_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- cecl_policy.contract_asset_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- sod_modeanyrequiredstrict (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_idinteger | nullrequiredUser 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_forany[]requiredFlags 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_accountingbooleanrequiredEvery accounting call needs MFA; the accounting pages send a user without a factor to enrol.
- step_up_minutesintegerrequiredHow long an authenticator re-entry (step-up) stays valid. Default 10.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
PATCH/rest/v1.0/companies/{company_id}/accounting/settingsUpdate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- settingsobjectrequired
- settings.base_currencystring
- settings.fiscal_year_start_monthinteger
- settings.default_entity_idinteger | null
- settings.require_approval_abovestring | null
- settings.recon_adjustment_limitstring | nullLargest 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_entitybooleanBank transfers between entities wait for a second person holding release_payments (default true). Owner or manage_grants only; audited.
- settings.transfer_approval_abovestring | nullBank 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.timezonestringIANA 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_accountsobject
- settings.reclass_control_accountsbooleanAllow moving a system role off an account that already has posted activity (a deliberate reclass).
- settings.loss_provision_unitstringLoss 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_pctstring | nullMonthly finance charge percent on past-due AR; null = none
- settings.finance_charge_grace_daysintegerDays past due before a finance charge applies
- settings.finance_charge_account_idinteger | nullIncome account finance-charge invoices credit
- settings.cecl_policyobject | nullASC 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_ratesobjectrequired
- settings.cecl_policy.ar_rates.currentstringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.ar_rates.d1_30stringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.ar_rates.d31_60stringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.ar_rates.d61_90stringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.ar_rates.d91_plusstringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.ar_rates.disputedstringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.retainage_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.cecl_policy.contract_asset_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- settings.sod_modeanyOnly 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_idinteger | nullUser 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_forany[]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_accountingboolean
- settings.step_up_minutesinteger
Response · 200 · object
- company_idintegerrequired
- base_currencystringrequired
- fiscal_year_start_monthintegerrequired
- default_entity_idinteger | nullrequired
- posting_methodanyrequiredStored and echoed only: every report is accrual basis. Cash-basis reporting is not built yet.
- require_approval_abovestring | nullrequiredDecimal amount as a string, 2 dp
- recon_adjustment_limitstring | nullrequiredDecimal amount as a string, 2 dp
- transfer_approval_cross_entitybooleanBank transfers between entities wait for a second person holding release_payments (default true).
- transfer_approval_abovestring | nullBank 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.
- timezonestringrequiredIANA 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_accountsobject[]required
- control_accounts[].rolestringrequired
- control_accounts[].labelstringrequired
- control_accounts[].account_idinteger | nullrequired
- control_accounts[].account_numberstring | nullrequired
- control_accounts[].account_namestring | nullrequired
- updated_atstring (date-time)required
- loss_provision_unitstringrequiredLoss 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_pctstring | nullrequiredMonthly finance charge percent on past-due AR; null = none
- finance_charge_grace_daysintegerrequiredDays past due before a finance charge applies
- finance_charge_account_idinteger | nullrequiredIncome account finance-charge invoices credit
- cecl_policyobject | nullrequiredASC 326 (CECL) loss-rate policy used by the cecl_allowance report and posting; null = not set (the allowance refuses with 422).
- cecl_policy.ar_ratesobjectrequired
- cecl_policy.retainage_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- cecl_policy.contract_asset_ratestringrequiredLoss rate as a fraction of amortized cost (0.015 = 1.5%)
- sod_modeanyrequiredstrict (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_idinteger | nullrequiredUser 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_forany[]requiredFlags 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_accountingbooleanrequiredEvery accounting call needs MFA; the accounting pages send a user without a factor to enrol.
- step_up_minutesintegerrequiredHow 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 token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/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/editionGet 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- editionstring | nullrequiredOne of: essentials, professional, enterprise, null.
- edition_namestring | nullrequired
- featuresobjectrequired
- features.apAutomationboolean
- features.collectionsboolean
- features.customerPortalboolean
- features.qualifiedReviewsboolean
- features.wipboolean
- features.retainageboolean
- features.commitmentsboolean
- features.closeCockpitboolean
- features.reportBuilderboolean
- features.fpaboolean
- features.fixedAssetsboolean
- features.leasesboolean
- features.multiEntityboolean
- features.intercompanyboolean
- features.consolidationboolean
- features.multiCurrencyboolean
- features.dimensionsboolean
- overridesobjectrequired
- policiesobjectrequired
- policies.sod_modestringrequiredOne of: strict, small_team.
- policies.require_approval_abovestring | nullrequired
- policies.transfer_approval_abovestring | nullrequired
- policies.transfer_approval_cross_entitybooleanrequired
- policies.recon_adjustment_limitstring | nullrequired
- policies.close_require_tasksbooleanrequired
- policies.close_require_recsbooleanrequired
- policies.require_mfa_for_accountingbooleanrequired
- policies.step_up_minutesintegerrequired
- policies.dunningbooleanrequired
- kept_controlsstring[]required
- recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- areasobject[]required
- areas[].keystringrequired
- areas[].labelstringrequired
- areas[].notestringrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
- editionsobject[]required
- editions[].keystringrequiredOne of: essentials, professional, enterprise.
- editions[].namestringrequired
- editions[].audiencestringrequired
- editions[].featuresobjectrequired
- editions[].policiesobjectrequired
- editions[].recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- appliedobject
- applied.revisionintegerrequired
- applied.kept_controlsstring[]required
- applied.diffobjectrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/settings/edition" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
PATCH/rest/v1.0/companies/{company_id}/accounting/settings/editionOverride 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- editionobjectrequired
- edition.featuresobject
- edition.features.apAutomationboolean
- edition.features.collectionsboolean
- edition.features.customerPortalboolean
- edition.features.qualifiedReviewsboolean
- edition.features.wipboolean
- edition.features.retainageboolean
- edition.features.commitmentsboolean
- edition.features.closeCockpitboolean
- edition.features.reportBuilderboolean
- edition.features.fpaboolean
- edition.features.fixedAssetsboolean
- edition.features.leasesboolean
- edition.features.multiEntityboolean
- edition.features.intercompanyboolean
- edition.features.consolidationboolean
- edition.features.multiCurrencyboolean
- edition.features.dimensionsboolean
- edition.dunningbooleanAR 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.reasonstringRequired when switching dunning off (422 edition_weaker_reason_required otherwise); audited.
Response · 200 · object
- editionstring | nullrequiredOne of: essentials, professional, enterprise, null.
- edition_namestring | nullrequired
- featuresobjectrequired
- features.apAutomationboolean
- features.collectionsboolean
- features.customerPortalboolean
- features.qualifiedReviewsboolean
- features.wipboolean
- features.retainageboolean
- features.commitmentsboolean
- features.closeCockpitboolean
- features.reportBuilderboolean
- features.fpaboolean
- features.fixedAssetsboolean
- features.leasesboolean
- features.multiEntityboolean
- features.intercompanyboolean
- features.consolidationboolean
- features.multiCurrencyboolean
- features.dimensionsboolean
- overridesobjectrequired
- policiesobjectrequired
- policies.sod_modestringrequiredOne of: strict, small_team.
- policies.require_approval_abovestring | nullrequired
- policies.transfer_approval_abovestring | nullrequired
- policies.transfer_approval_cross_entitybooleanrequired
- policies.recon_adjustment_limitstring | nullrequired
- policies.close_require_tasksbooleanrequired
- policies.close_require_recsbooleanrequired
- policies.require_mfa_for_accountingbooleanrequired
- policies.step_up_minutesintegerrequired
- policies.dunningbooleanrequired
- kept_controlsstring[]required
- recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- areasobject[]required
- areas[].keystringrequired
- areas[].labelstringrequired
- areas[].notestringrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
- editionsobject[]required
- editions[].keystringrequiredOne of: essentials, professional, enterprise.
- editions[].namestringrequired
- editions[].audiencestringrequired
- editions[].featuresobjectrequired
- editions[].policiesobjectrequired
- editions[].recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- appliedobject
- applied.revisionintegerrequired
- applied.kept_controlsstring[]required
- applied.diffobjectrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA422No edition chosen yet, or an invalid body
Example request
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/editionApply 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- editionobjectrequired
- edition.keystringrequiredOne of: essentials, professional, enterprise.
- edition.confirm_hashstringrequired
- edition.keep_controlsboolean
- edition.reasonstring
Response · 200 · object
- editionstring | nullrequiredOne of: essentials, professional, enterprise, null.
- edition_namestring | nullrequired
- featuresobjectrequired
- features.apAutomationboolean
- features.collectionsboolean
- features.customerPortalboolean
- features.qualifiedReviewsboolean
- features.wipboolean
- features.retainageboolean
- features.commitmentsboolean
- features.closeCockpitboolean
- features.reportBuilderboolean
- features.fpaboolean
- features.fixedAssetsboolean
- features.leasesboolean
- features.multiEntityboolean
- features.intercompanyboolean
- features.consolidationboolean
- features.multiCurrencyboolean
- features.dimensionsboolean
- overridesobjectrequired
- policiesobjectrequired
- policies.sod_modestringrequiredOne of: strict, small_team.
- policies.require_approval_abovestring | nullrequired
- policies.transfer_approval_abovestring | nullrequired
- policies.transfer_approval_cross_entitybooleanrequired
- policies.recon_adjustment_limitstring | nullrequired
- policies.close_require_tasksbooleanrequired
- policies.close_require_recsbooleanrequired
- policies.require_mfa_for_accountingbooleanrequired
- policies.step_up_minutesintegerrequired
- policies.dunningbooleanrequired
- kept_controlsstring[]required
- recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- areasobject[]required
- areas[].keystringrequired
- areas[].labelstringrequired
- areas[].notestringrequired
- revisionintegerrequired
- updated_atstring | null (date-time)required
- editionsobject[]required
- editions[].keystringrequiredOne of: essentials, professional, enterprise.
- editions[].namestringrequired
- editions[].audiencestringrequired
- editions[].featuresobjectrequired
- editions[].policiesobjectrequired
- editions[].recommended_rolesstring[]requiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly.
- appliedobject
- applied.revisionintegerrequired
- applied.kept_controlsstring[]required
- applied.diffobjectrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA409The edition change differs from the confirmed preview422Weaker controls without a reason, or an in-use control the edition would switch off
Example request
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/previewPreview 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- editionstringqueryOne of: essentials, professional, enterprise.
Response · 200 · object
- fromstring | nullrequired
- tostringrequiredOne of: essentials, professional, enterprise.
- hashstringrequired
- weakerstring[]required
- blockedstring[]required
- featuresobject[]required
- features[].keystringrequired
- features[].labelstringrequired
- features[].frombooleanrequired
- features[].tobooleanrequired
- features[].warningstring | nullrequired
- policiesobject[]required
- policies[].keystringrequired
- policies[].labelstringrequired
- policies[].fromstring | boolean | integer | nullrequired
- policies[].tostring | boolean | integer | nullrequired
- policies[].directionstringrequiredOne of: stronger, weaker, same, changed.
- policies[].controlbooleanrequired
- policies[].blockedstring | nullrequired
- policies[].warningstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA422Unknown edition
Example request
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/setupGet 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- stepsobject[]required
- steps[].keystringrequiredOne of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
- steps[].titlestringrequired
- steps[].statusstringrequiredOne of: done, skipped, pending.
- steps[].markedbooleanrequired
- steps[].skippablebooleanrequired
- currentstring | nullrequiredOne of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live, null.
- profileobject | nullrequired
- profile.industrystringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- profile.employeesintegerrequired
- profile.entitiesintegerrequired
- profile.foreign_operationsbooleanrequired
- profile.auditedbooleanrequired
- profile.payrollbooleanrequired
- industry_packstring | nullrequired
- recommendationobject | nullrequired
- recommendation.editionstringrequiredOne of: essentials, professional, enterprise.
- recommendation.packstringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- checklistobject[]required
- checklist[].keystringrequired
- checklist[].labelstringrequired
- checklist[].okbooleanrequired
- checklist[].detailstringrequired
- checklist[].hrefstring | nullrequired
- completed_atstring | null (date-time)required
- revisionintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/settings/setup" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
PUT/rest/v1.0/companies/{company_id}/accounting/settings/setupRecord 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- setupobjectrequired
- setup.stepstringrequiredOne of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
- setup.statusstringrequiredOne of: done, skipped, pending.
- setup.profileobject
- setup.profile.industrystringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- setup.profile.employeesintegerrequired
- setup.profile.entitiesintegerrequired
- setup.profile.foreign_operationsbooleanrequired
- setup.profile.auditedbooleanrequired
- setup.profile.payrollbooleanrequired
Response · 200 · object
- stepsobject[]required
- steps[].keystringrequiredOne of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live.
- steps[].titlestringrequired
- steps[].statusstringrequiredOne of: done, skipped, pending.
- steps[].markedbooleanrequired
- steps[].skippablebooleanrequired
- currentstring | nullrequiredOne of: profile, edition, coa, entities, bank_accounts, opening_balances, approvals, users, go_live, null.
- profileobject | nullrequired
- profile.industrystringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- profile.employeesintegerrequired
- profile.entitiesintegerrequired
- profile.foreign_operationsbooleanrequired
- profile.auditedbooleanrequired
- profile.payrollbooleanrequired
- industry_packstring | nullrequired
- recommendationobject | nullrequired
- recommendation.editionstringrequiredOne of: essentials, professional, enterprise.
- recommendation.packstringrequiredOne of: general_contractor, specialty_contractor, home_builder, heavy_civil, construction_management.
- checklistobject[]required
- checklist[].keystringrequired
- checklist[].labelstringrequired
- checklist[].okbooleanrequired
- checklist[].detailstringrequired
- checklist[].hrefstring | nullrequired
- completed_atstring | null (date-time)required
- revisionintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, an entity-restricted or project-scoped grant writing, wrong company, read-only workspace, or (edition changes) missing step-up or MFA422A step that cannot be skipped, unfinished data, or a failing go-live checklist
Example request
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_codesList 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- kindanyrequiredOne of: sales, use.
- is_activebooleanrequired
- total_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- componentsobject[]required
- components[].idintegerrequired
- components[].namestringrequired
- components[].ratestringrequiredDecimal rate or quantity as a string, 6 dp
- components[].account_idintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/tax_codes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
POST/rest/v1.0/companies/{company_id}/accounting/tax_codesCreate 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- tax_codeobjectrequired
- tax_code.codestringrequired
- tax_code.namestringrequired
- tax_code.kindanyOne of: sales, use.
- tax_code.is_activeboolean
- tax_code.componentsobject[]required
- tax_code.components[].namestringrequired
- tax_code.components[].ratestringrequiredPercent, up to 6 dp
- tax_code.components[].account_idintegerrequired
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindanyrequiredOne of: sales, use.
- is_activebooleanrequired
- total_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- componentsobject[]required
- components[].idintegerrequired
- components[].namestringrequired
- components[].ratestringrequiredDecimal rate or quantity as a string, 6 dp
- components[].account_idintegerrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- tax_codeobjectrequired
- tax_code.codestring
- tax_code.namestring
- tax_code.kindanyOne of: sales, use.
- tax_code.is_activeboolean
- tax_code.componentsobject[]
- tax_code.components[].namestringrequired
- tax_code.components[].ratestringrequiredPercent, up to 6 dp
- tax_code.components[].account_idintegerrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- kindanyrequiredOne of: sales, use.
- is_activebooleanrequired
- total_ratestringrequiredDecimal rate or quantity as a string, 6 dp
- componentsobject[]required
- components[].idintegerrequired
- components[].namestringrequired
- components[].ratestringrequiredDecimal rate or quantity as a string, 6 dp
- components[].account_idintegerrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/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_certificatesList customer tax exemption certificates
Up to 500, optionally for one customer. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- customer_idintegerquery
Response · 200 · object[]
- idintegerrequired
- customer_idintegerrequired
- state_codestringrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring (date) | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)
Example request
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_certificatesRecord 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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- certificateobjectrequired
- certificate.customer_idintegerrequired
- certificate.state_codestringrequired
- certificate.certificate_numberstringrequired
- certificate.reasonstringrequired
- certificate.effective_fromstring (date)required
- certificate.expires_onstring (date) | null
Response · 201 · object
- idintegerrequired
- customer_idintegerrequired
- state_codestringrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring (date) | nullrequired
Errors
400Malformed JSON body401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace404Not found in this company422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)
Example request
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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- certificateobjectrequired
- certificate.expires_onstring (date) | nullrequired
Response · 200 · object
- idintegerrequired
- customer_idintegerrequired
- state_codestringrequired
- certificate_numberstringrequired
- reasonstringrequired
- effective_fromstring (date)required
- expires_onstring (date) | nullrequired
Errors
400Malformed JSON body401Missing or invalid bearer token403No accounting access, missing permission, wrong company, entity out of scope, or read-only workspace404Not found in this company422Validation failed, or a named setup gap (state with no encoded contractor tax rule, missing job-site sales or use tax code)
Example request
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/termsList payment terms
Company payment terms with due days and optional early-payment discount. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- due_daysintegerrequired
- discount_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- discount_daysinteger | nullrequired
- is_activebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/terms" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Settings
POST/rest/v1.0/companies/{company_id}/accounting/termsCreate a payment term
Adds a term such as Net 30 or 2% 10, net 30. Needs manage_coa. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- termobjectrequired
- term.codestringrequired
- term.namestringrequired
- term.due_daysintegerrequired
- term.discount_percentstring | null
- term.discount_daysinteger | null
- term.is_activeboolean
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- due_daysintegerrequired
- discount_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- discount_daysinteger | nullrequired
- is_activebooleanrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/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.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- termobjectrequired
- term.codestring
- term.namestring
- term.due_daysinteger
- term.discount_percentstring | null
- term.discount_daysinteger | null
- term.is_activeboolean
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- due_daysintegerrequired
- discount_percentstring | nullrequiredDecimal rate or quantity as a string, 6 dp
- discount_daysinteger | nullrequired
- is_activebooleanrequired
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only workspace404Not found in this company422Validation failed (field errors) or the ledger refused the change (message list)
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/terms/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"term": {}
}'