Approvals
Review accounting work with approval rules and delegated authority. 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 Approvals guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/approval_delegationsList approval delegations - POST
/rest/v1.0/companies/{company_id}/accounting/approval_delegationsCreate an approval delegation - DELETE
/rest/v1.0/companies/{company_id}/accounting/approval_delegations/{id}Revoke an approval delegation - GET
/rest/v1.0/companies/{company_id}/accounting/approval_rulesList approval rules - POST
/rest/v1.0/companies/{company_id}/accounting/approval_rulesCreate an approval rule - DELETE
/rest/v1.0/companies/{company_id}/accounting/approval_rules/{id}Deactivate an approval rule - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/historyApproval escalation history of an item - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/policiesList approval escalation policies - POST
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/policiesSave an approval escalation policy - POST
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/runRun reminders and escalation now - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/settingsApproval escalation settings - PUT
/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/settingsSave approval escalation settings - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/inboxApprovals inbox - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/overdueOverdue approvals - GET
/rest/v1.0/companies/{company_id}/accounting/approvals/self_approvedSelf-approved documents
Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approval_delegationsList approval delegations
Delegations from or to the caller; every delegation with manage_grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- from_user_idintegerrequired
- to_user_idintegerrequired
- doc_typesany[]requiredOne of: ap_bill, payment_batch, journal_entry.
- max_amountstring | nullrequired
- entity_idsinteger[]required
- starts_atstring (date-time)required
- ends_atstring (date-time)required
- reasonstringrequired
- created_by_idintegerrequired
- revoked_atstring | null (date-time)required
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_delegations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
POST/rest/v1.0/companies/{company_id}/accounting/approval_delegationsCreate an approval delegation
Lets to_user fill from_user's approval slots between starts_at and ends_at for the listed doc types, up to max_amount and within entity_ids (empty = all). The delegate needs the same approve flag and entity scope, never approves a document they or the delegator prepared, and the step records who they acted for. Delegating your own approvals needs each doc type's approve flag; from_user_id for someone else needs manage_grants and can't name yourself as to_user_id (403 self_delegation); a delegation someone created to themselves never fills a slot. 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
- delegationobjectrequired
- delegation.from_user_idinteger
- delegation.to_user_idintegerrequired
- delegation.doc_typesany[]requiredOne of: ap_bill, payment_batch, journal_entry.
- delegation.max_amountstring | null
- delegation.entity_idsinteger[]
- delegation.starts_atstring (date-time)required
- delegation.ends_atstring (date-time)required
- delegation.reasonstringrequired
Response · 201 · object
- idintegerrequired
- from_user_idintegerrequired
- to_user_idintegerrequired
- doc_typesany[]requiredOne of: ap_bill, payment_batch, journal_entry.
- max_amountstring | nullrequired
- entity_idsinteger[]required
- starts_atstring (date-time)required
- ends_atstring (date-time)required
- reasonstringrequired
- created_by_idintegerrequired
- revoked_atstring | null (date-time)required
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_delegations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"delegation": {
"to_user_id": 1,
"doc_types": "ap_bill",
"starts_at": "2026-11-01T12:00:00Z",
"ends_at": "2026-11-01T12:00:00Z",
"reason": "string"
}
}'Accounting / Approvals
DELETE/rest/v1.0/companies/{company_id}/accounting/approval_delegations/{id}Revoke an approval delegation
The delegator or manage_grants. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_delegations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approval_rulesList approval rules
Approval routing rules for ap_bill and payment_batch (WORKFLOWS §2), active first by priority. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry.
- namestringrequired
- priorityintegerrequired
- min_amountstring | nullrequired
- max_amountstring | nullrequired
- entity_idsinteger[]required
- project_idsinteger[]required
- vendor_riskany[]requiredOne of: new_vendor, compliance_hold, bank_changed.
- stepsobject[]required
- steps[].approversstring[]required
- steps[].quoruminteger
- is_activebooleanrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_rules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
POST/rest/v1.0/companies/{company_id}/accounting/approval_rulesCreate an approval rule
Needs manage_grants. Among active rules for a doc type whose every non-empty condition matches (amount in [min_amount, max_amount), any entity, any line project, any vendor risk), the lowest priority routes the document; no match uses the AP approval bands (bills) or a single releaser (payment runs). Steps run in order; each step's approvers are grant:any (anyone with the doc type's approve flag), grant:<role>, project:<team role> (resolved from the project team when the route is snapshotted, leaving out the document's makers and members without the approve flag) or user:<id> (must hold the doc type's approve flag, else 422); quorum defaults to all of them (N-of-M otherwise) and shrinks to the approvers left after resolution. An equal priority among active rules of the doc type is 409 priority_taken. Rules are not edited in place: deactivate and create. 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
- approval_ruleobjectrequired
- approval_rule.doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry.
- approval_rule.namestringrequired
- approval_rule.priorityintegerrequired
- approval_rule.min_amountstring | null
- approval_rule.max_amountstring | null
- approval_rule.entity_idsinteger[]
- approval_rule.project_idsinteger[]
- approval_rule.vendor_riskany[]One of: new_vendor, compliance_hold, bank_changed.
- approval_rule.stepsobject[]required
- approval_rule.steps[].approversstring[]required
- approval_rule.steps[].quoruminteger
Response · 201 · object
- idintegerrequired
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry.
- namestringrequired
- priorityintegerrequired
- min_amountstring | nullrequired
- max_amountstring | nullrequired
- entity_idsinteger[]required
- project_idsinteger[]required
- vendor_riskany[]requiredOne of: new_vendor, compliance_hold, bank_changed.
- stepsobject[]required
- steps[].approversstring[]required
- steps[].quoruminteger
- is_activebooleanrequired
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_rules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"approval_rule": {
"doc_type": "ap_bill",
"name": "string",
"priority": 1,
"steps": [
{
"approvers": []
}
]
}
}'Accounting / Approvals
DELETE/rest/v1.0/companies/{company_id}/accounting/approval_rules/{id}Deactivate an approval rule
Needs manage_grants. Documents already routed keep the steps they snapshotted. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/approval_rules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/historyApproval escalation history of an item
Every reminder and escalation of one approval item (all revisions), newest first, with recipients, re-routed steps and who was left out and why. Needs view_ledger and the item's entities in scope (404 otherwise); refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- doc_typeanyqueryrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- doc_idintegerqueryrequired
Response · 200 · object[]
- idintegerrequired
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- doc_idintegerrequired
- doc_revisionintegerrequired
- kindanyrequiredOne of: reminder, escalation.
- seqintegerrequired
- run_datestring (date)required
- business_days_waitingintegerrequired
- recipient_idsinteger[]required
- reroute_step_idsinteger[]required
- detailobject | nullrequired
- statusanyrequiredOne of: sent, skipped.
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant404Item not found or outside the viewer's scope422Invalid query
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/history" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/policiesList approval escalation policies
One policy per item kind. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- is_activebooleanrequired
- reminder_every_daysintegerrequired
- escalate_after_daysintegerrequired
- max_levelsintegerrequired
- targetstringrequired
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/policies" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
POST/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/policiesSave an approval escalation policy
Create or replace the policy of one item kind (natural key: doc_type; 201 when created, 200 when replaced). target: next_role, principal, role:controller, role:owner or user:<id> (a user target must hold the kind's approve grant). Needs manage_grants and step-up. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- escalation_policyobjectrequired
- escalation_policy.doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- escalation_policy.is_activeboolean
- escalation_policy.reminder_every_daysintegerrequired
- escalation_policy.escalate_after_daysintegerrequired
- escalation_policy.max_levelsinteger
- escalation_policy.targetstring
Response · 200 · object
- idintegerrequired
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- is_activebooleanrequired
- reminder_every_daysintegerrequired
- escalate_after_daysintegerrequired
- max_levelsintegerrequired
- targetstringrequired
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403Missing manage_grants or step-up, or read-only workspace404Target user not found422The target user cannot approve that kind
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/policies" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"escalation_policy": {
"doc_type": "ap_bill",
"reminder_every_days": 1,
"escalate_after_days": 1
}
}'Accounting / Approvals
POST/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/runRun reminders and escalation now
The same run as the daily job, as of the company's today: due escalations (re-routing named steps to eligible targets) and due reminders. Idempotent: a reminder or escalation already sent is never sent again. Needs manage_grants. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- as_ofstring (date)required
- statusanyrequiredOne of: ran, disabled, not_business_day.
- remindersintegerrequired
- escalationsintegerrequired
- reroutedintegerrequired
- emailsintegerrequired
- skippedintegerrequired
- duplicatesintegerrequired
Errors
401Missing or invalid bearer token403Missing manage_grants or read-only workspace
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/run" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/settingsApproval escalation settings
Whether reminders and escalation run, the business-day calendar and the policy of each item kind. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- enabledbooleanrequired
- business_daysinteger[]required
- holidaysstring[]required
- revisionintegerrequired
- updated_atstring | null (date-time)required
- policiesobject[]required
- policies[].idintegerrequired
- policies[].doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- policies[].is_activebooleanrequired
- policies[].reminder_every_daysintegerrequired
- policies[].escalate_after_daysintegerrequired
- policies[].max_levelsintegerrequired
- policies[].targetstringrequired
- policies[].updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
PUT/rest/v1.0/companies/{company_id}/accounting/approvals/escalation/settingsSave approval escalation settings
Turn reminders and escalation on or off and set the business days (ISO weekdays) and holidays. Needs manage_grants and step-up (routing is a control, like approval rules). Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- escalation_settingsobjectrequired
- escalation_settings.enabledbooleanrequired
- escalation_settings.business_daysinteger[]required
- escalation_settings.holidaysstring (date)[]required
Response · 200 · object
- enabledbooleanrequired
- business_daysinteger[]required
- holidaysstring[]required
- revisionintegerrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403Missing manage_grants or step-up, or read-only workspace422Invalid body
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/escalation/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"escalation_settings": {
"enabled": true,
"business_days": [],
"holidays": []
}
}'Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/inboxApprovals inbox
The caller's open approval slots across journal entries, AP bills and payment runs (directly, or as the delegate of a user within an active delegation), plus pending vendor bank/TIN changes for manage_vendor_banking users, and the caller's own documents an approver returned in the last 30 days (returned). Only documents the approve call would accept are listed. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- itemsobject[]required
- items[].doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, vendor_bank_change, period_reopen, bank_transfer, budget, fx_revaluation.
- items[].doc_idintegerrequired
- items[].labelstringrequired
- items[].amountstring | null
- items[].pathstringrequiredIn-app path below /companies/{company_id}/accounting.
- items[].submitted_atstring | null (date-time)
- items[].exceptionstring | nullWhy it can't be bulk approved (match exception, self-approval, bank change review).
- items[].delegate_of_idinteger | nullSet when the caller acts as this user's delegate.
- returnedobject[]required
- returned[].doc_typeanyOne of: ap_bill, payment_batch, journal_entry.
- returned[].doc_idinteger
- returned[].labelstring
- returned[].pathstring
- returned[].reasonstring
- returned[].rejected_atstring (date-time)
- returned[].rejected_by_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, or wrong company404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/inbox" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/overdueOverdue approvals
Approval items waiting at least their kind's escalation threshold in business days (the reminder cadence when the policy does not escalate; 3 without a policy), longest first, in the viewer's entity scope, with who they wait on and their escalation level. Needs view_ledger; refused to project-scoped grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- doc_typeanyrequiredOne of: ap_bill, payment_batch, journal_entry, bank_transfer, vendor_bank_change, budget, fx_revaluation.
- doc_idintegerrequired
- doc_revisionintegerrequired
- labelstringrequired
- amountstring | nullrequired
- pathstringrequired
- entity_idsinteger[]required
- waiting_sincestring (date-time)required
- business_days_waitingintegerrequired
- threshold_daysintegerrequired
- escalation_levelintegerrequired
- reminders_sentintegerrequired
- last_notified_atstring | null (date-time)required
- waiting_onobject[]required
- waiting_on[].idintegerrequired
- waiting_on[].namestring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access or a project-scoped grant
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/overdue" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Approvals
GET/rest/v1.0/companies/{company_id}/accounting/approvals/self_approvedSelf-approved documents
Approvals a maker made on their own document in small-team SoD mode, with the reason (close-checklist review). Needs close_period (403 otherwise); entity-scoped grants get an empty list. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- fromstring (date)query
- tostring (date)query
Response · 200 · object[]
- idinteger
- item_typestring
- item_idinteger
- actor_idinteger
- summarystring
- reasonstring | null
- created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, or wrong company404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/approvals/self_approved" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"