Accounting Access
Assign accounting roles, entity scope and access reviews. 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 Access guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/access_reviewsList access review campaigns - POST
/rest/v1.0/companies/{company_id}/accounting/access_reviewsOpen an access review campaign - GET
/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}Get an access review campaign with its snapshot - POST
/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/cancelCancel an access review campaign - POST
/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/completeComplete an access review campaign - POST
/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/items/{item_id}/decisionDecide one access review item - GET
/rest/v1.0/companies/{company_id}/accounting/compliance/policy_areasPolicy areas and their qualified sign-off status - GET
/rest/v1.0/companies/{company_id}/accounting/compliance/reviewersList registered qualified reviewers - POST
/rest/v1.0/companies/{company_id}/accounting/compliance/reviewersRegister a qualified reviewer - POST
/rest/v1.0/companies/{company_id}/accounting/compliance/reviewers/{id}/revokeRevoke a qualified reviewer registration - GET
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffsList qualified sign-offs - POST
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffsRecord a qualified sign-off - GET
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}Show a qualified sign-off - GET
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsList evidence on a qualified sign-off - POST
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsAttach evidence to a qualified sign-off - POST
/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/revokeRevoke a qualified sign-off - GET
/rest/v1.0/companies/{company_id}/accounting/control_objectivesSOC 1 control register - GET
/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Get a control objective with its evidence - PUT
/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Assign a control objective's owner and frequency - POST
/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}/evidenceRecord control evidence - GET
/rest/v1.0/companies/{company_id}/accounting/grantsList accounting access - PATCH
/rest/v1.0/companies/{company_id}/accounting/grants/{id}Set a member's accounting access - POST
/rest/v1.0/companies/{company_id}/accounting/grants/access_reviewCertify an access review - GET
/rest/v1.0/companies/{company_id}/accounting/sod_conflictsSegregation of duties conflict report - GET
/rest/v1.0/companies/{company_id}/accounting/sod_rulesList segregation of duties rules - PUT
/rest/v1.0/companies/{company_id}/accounting/sod_rules/{rule_key}Create or change a segregation of duties rule
Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/access_reviewsList access review campaigns
Campaigns newest first with decision counts. An entity-limited grant sees only its entities' campaigns. Filter with status (open, completed, cancelled). Paginated (page, per_page). Needs manage_grants. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- statusstringqueryOne of: open, completed, cancelled.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- kindstringrequiredOne of: quarterly, ad_hoc.
- titlestringrequired
- periodstring | nullrequired
- entity_idinteger | nullrequired
- statusstringrequiredOne of: open, completed, cancelled.
- due_onstring (date)required
- dormant_daysintegerrequired
- reviewersobject[]required
- reviewers[].idintegerrequired
- reviewers[].namestring | nullrequired
- snapshot_atstring (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- countsobjectrequired
- counts.itemsintegerrequired
- counts.decidedintegerrequired
- counts.dormantintegerrequired
- counts.sodintegerrequired
- counts.keepintegerrequired
- counts.modifyintegerrequired
- counts.revokeintegerrequired
- summaryobject | nullrequiredDecision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note
Errors
401Missing or invalid bearer token403Missing manage_grants, a project-scoped grant, wrong company or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/access_reviewsOpen an access review campaign
Snapshots, immutably, every accounting grant in scope (the company, or the grants that reach one entity; expired grants and inactive members included) and every company administrator: flags, entity and project scope, delegations given and received, live API tokens with an accounting scope (never the token), MFA, last accounting activity, dormancy (no activity for dormant_days, default 90) and the SoD conflicts of the person's effective duties. Every reviewer needs manage_grants over the whole scope; when a reviewer's own access is in scope a second reviewer is required. A quarterly campaign names its period (one per scope and quarter, else 409). Needs manage_grants (unrestricted for a company-wide campaign). Honors Idempotency-Key. 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
- access_reviewobjectrequired
- access_review.kindstringrequiredOne of: quarterly, ad_hoc.
- access_review.titlestring
- access_review.periodstringRequired for quarterly campaigns, e.g. 2026-Q4
- access_review.entity_idinteger | nullOmit or null for the whole company
- access_review.due_onstring (date)required
- access_review.dormant_daysinteger
- access_review.reviewer_idsinteger[]required
Response · 201 · object
- idintegerrequired
- kindstringrequiredOne of: quarterly, ad_hoc.
- titlestringrequired
- periodstring | nullrequired
- entity_idinteger | nullrequired
- statusstringrequiredOne of: open, completed, cancelled.
- due_onstring (date)required
- dormant_daysintegerrequired
- reviewersobject[]required
- reviewers[].idintegerrequired
- reviewers[].namestring | nullrequired
- snapshot_atstring (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- countsobjectrequired
- counts.itemsintegerrequired
- counts.decidedintegerrequired
- counts.dormantintegerrequired
- counts.sodintegerrequired
- counts.keepintegerrequired
- counts.modifyintegerrequired
- counts.revokeintegerrequired
- summaryobject | nullrequiredDecision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note
Errors
401Missing or invalid bearer token403Missing manage_grants, an entity outside the caller's grant, wrong company or a read-only token404Unknown entity or reviewer409A quarterly campaign already exists for this scope and period, or an Idempotency-Key conflict422Invalid body, a past due date, a reviewer without manage_grants over the scope, or a reviewer who would review their own access alone
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"access_review": {
"kind": "quarterly",
"due_on": "2026-11-01",
"reviewer_ids": []
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}Get an access review campaign with its snapshot
The campaign, its counts and every snapshotted item with the decision recorded so far. Needs manage_grants over the campaign's scope. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: quarterly, ad_hoc.
- titlestringrequired
- periodstring | nullrequired
- entity_idinteger | nullrequired
- statusstringrequiredOne of: open, completed, cancelled.
- due_onstring (date)required
- dormant_daysintegerrequired
- reviewersobject[]required
- reviewers[].idintegerrequired
- reviewers[].namestring | nullrequired
- snapshot_atstring (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- countsobjectrequired
- counts.itemsintegerrequired
- counts.decidedintegerrequired
- counts.dormantintegerrequired
- counts.sodintegerrequired
- counts.keepintegerrequired
- counts.modifyintegerrequired
- counts.revokeintegerrequired
- summaryobject | nullrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].review_idintegerrequired
- items[].userobjectrequired
- items[].kindstringrequiredOne of: grant, implicit_owner.
- items[].grant_idinteger | nullrequired
- items[].rolestringrequired
- items[].flagsstring[]requiredOne 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.
- items[].delegated_flagsstring[]requiredOne 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.
- items[].entity_idsinteger[]required
- items[].project_scopedbooleanrequired
- items[].expires_atstring | null (date-time)required
- items[].certified_atstring | null (date-time)required
- items[].mfabooleanrequired
- items[].delegationsobject[]requiredid, direction (received or given), other_user_id, other_name, doc_types, flags, max_amount, entity_ids, starts_at, ends_at
- items[].api_tokensobject[]requiredid, scopes (accounting scopes; ["*"] for a legacy full-access token), created_at, expires_at. Never the token.
- items[].last_activity_atstring | null (date-time)required
- items[].dormantbooleanrequired
- items[].sod_conflictsobject[]requiredrule, name, severity, flags, via_delegation, delegation_ids
- items[].decisionstring | nullrequiredOne of: keep, modify, revoke, null.
- items[].reasonstring | nullrequired
- items[].changeobject | nullrequiredThe grant a modify decision applied
- items[].decided_bynull | objectrequired
- items[].decided_atstring | null (date-time)required
- items[].drift_at_decisionboolean | nullrequired
- items[].applied_audit_idinteger | nullrequired
Errors
401Missing or invalid bearer token403Missing manage_grants, wrong company or a token without the required scope404No such campaign in the caller's scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/cancelCancel an access review campaign
Cancels an open campaign with a reason; decisions already applied stand. The campaign's creator or a designated reviewer. Needs manage_grants. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- cancelobjectrequired
- cancel.reasonstringrequired
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: quarterly, ad_hoc.
- titlestringrequired
- periodstring | nullrequired
- entity_idinteger | nullrequired
- statusstringrequiredOne of: open, completed, cancelled.
- due_onstring (date)required
- dormant_daysintegerrequired
- reviewersobject[]required
- reviewers[].idintegerrequired
- reviewers[].namestring | nullrequired
- snapshot_atstring (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- countsobjectrequired
- counts.itemsintegerrequired
- counts.decidedintegerrequired
- counts.dormantintegerrequired
- counts.sodintegerrequired
- counts.keepintegerrequired
- counts.modifyintegerrequired
- counts.revokeintegerrequired
- summaryobject | nullrequiredDecision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note
Errors
401Missing or invalid bearer token403Missing manage_grants, or neither creator nor reviewer404No such campaign409Already completed or cancelled422Invalid body
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews/1/cancel" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"cancel": {
"reason": "string"
}
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/completeComplete an access review campaign
Closes the campaign once every item is decided (422 access_review_incomplete otherwise) and stores the decision counts. The completed campaign is evidence for control objective CO-1. A designated reviewer only. Needs manage_grants. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- completeobjectrequired
- complete.notestring
Response · 200 · object
- idintegerrequired
- kindstringrequiredOne of: quarterly, ad_hoc.
- titlestringrequired
- periodstring | nullrequired
- entity_idinteger | nullrequired
- statusstringrequiredOne of: open, completed, cancelled.
- due_onstring (date)required
- dormant_daysintegerrequired
- reviewersobject[]required
- reviewers[].idintegerrequired
- reviewers[].namestring | nullrequired
- snapshot_atstring (date-time)required
- created_by_idintegerrequired
- created_atstring (date-time)required
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- cancel_reasonstring | nullrequired
- countsobjectrequired
- counts.itemsintegerrequired
- counts.decidedintegerrequired
- counts.dormantintegerrequired
- counts.sodintegerrequired
- counts.keepintegerrequired
- counts.modifyintegerrequired
- counts.revokeintegerrequired
- summaryobject | nullrequiredDecision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note
Errors
401Missing or invalid bearer token403Missing manage_grants or not a designated reviewer404No such campaign409Already completed or cancelled422Undecided items remain
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews/1/complete" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"complete": {}
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/items/{item_id}/decisionDecide one access review item
Records keep, modify or revoke with a reason, once. Only a designated reviewer may decide, and never the item's own holder (403). Revoke and modify apply through the grant-change path (step-up, entity limits, no flags the reviewer lacks, segregation of duties, its own grant_changed or grant_revoked audit row) and the item records that audit event; keep stamps the grant certified when it still matches the snapshot. A company administrator's item can only be kept. drift_at_decision records that the live grant differed from the snapshot. Needs manage_grants and step-up (a token needs accounting:step_up). Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- item_idintegerpathrequiredItem id
Request body
- decisionobjectrequired
- decision.decisionstringrequiredOne of: keep, modify, revoke.
- decision.reasonstringrequired
- decision.grantobjectmodify only: the grant to apply, as PATCH grants/{id} (role, entity_ids, expires_at and any permission flag as a boolean)
- decision.grant.rolestringrequired
- decision.grant.entity_idsinteger[]
- decision.grant.expires_atstring | null (date)
Response · 200 · object
- idintegerrequired
- review_idintegerrequired
- userobjectrequired
- user.idintegerrequired
- user.namestringrequired
- user.loginstringrequired
- user.is_activebooleanrequired
- kindstringrequiredOne of: grant, implicit_owner.
- grant_idinteger | nullrequired
- rolestringrequired
- flagsstring[]requiredOne 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.
- delegated_flagsstring[]requiredOne 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.
- entity_idsinteger[]required
- project_scopedbooleanrequired
- expires_atstring | null (date-time)required
- certified_atstring | null (date-time)required
- mfabooleanrequired
- delegationsobject[]requiredid, direction (received or given), other_user_id, other_name, doc_types, flags, max_amount, entity_ids, starts_at, ends_at
- api_tokensobject[]requiredid, scopes (accounting scopes; ["*"] for a legacy full-access token), created_at, expires_at. Never the token.
- last_activity_atstring | null (date-time)required
- dormantbooleanrequired
- sod_conflictsobject[]requiredrule, name, severity, flags, via_delegation, delegation_ids
- decisionstring | nullrequiredOne of: keep, modify, revoke, null.
- reasonstring | nullrequired
- changeobject | nullrequiredThe grant a modify decision applied
- decided_bynull | objectrequired
- decided_by.idintegerrequired
- decided_by.namestring | nullrequired
- decided_atstring | null (date-time)required
- drift_at_decisionboolean | nullrequired
- applied_audit_idinteger | nullrequired
Errors
401Missing or invalid bearer token403Missing manage_grants, step-up required, not a designated reviewer, or the caller's own item404No such campaign or item409Already decided, campaign not open, or a modify on a grant that no longer exists422Invalid body, a non-keep decision on an administrator, or a grant change the grant path refuses (sod_blocked, sod_reason_required)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/access_reviews/1/items/1/decision" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"decision": {
"decision": "keep",
"reason": "string"
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/compliance/policy_areasPolicy areas and their qualified sign-off status
Every policy area that needs qualified review, the policy version in force, the credentials that may sign it, and for each jurisdiction it is encoded for: current, awaiting_evidence, expired, outdated (signed for an older version), revoked or not_reviewed, as of the company's business date. A jurisdiction that is not listed is unsupported, not exempt. Needs view_ledger. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- as_ofstring (date)required
- areasobject[]required
- areas[].areastringrequired
- areas[].titlestringrequired
- areas[].coversstringrequired
- areas[].policy_versionstringrequired
- areas[].credential_typesstring[]requiredOne of: cpa, payroll_specialist, tax_advisor.
- areas[].max_validity_monthsintegerrequired
- areas[].countsobjectrequired
- areas[].jurisdictionsobject[]required
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/policy_areas" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/compliance/reviewersList registered qualified reviewers
Every registration, revoked ones included, oldest first. Needs view_ledger. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- userobjectrequired
- user.idintegerrequired
- user.namestring | nullrequired
- credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- credential_numberstringrequired
- credential_issuerstringrequired
- credential_jurisdictionstringrequired
- areasstring[]required
- valid_fromstring (date)required
- valid_untilstring (date)required
- registered_byobjectrequired
- registered_by.idintegerrequired
- registered_by.namestring | nullrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/reviewers" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/compliance/reviewersRegister a qualified reviewer
Registers an active company member as a qualified reviewer: credential type, number, issuer and jurisdiction, the policy areas they may sign (each must accept the credential type) and the validity window. Nobody may register themselves. Immutable once written except one revocation; audited. Needs manage_grants with company-wide access and step-up (a token needs accounting:step_up). Honors Idempotency-Key. 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
- reviewerobjectrequired
- reviewer.user_idintegerrequiredAn active member of this company (not the caller)
- reviewer.credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- reviewer.credential_numberstringrequired
- reviewer.credential_issuerstringrequired
- reviewer.credential_jurisdictionstringrequiredCountry or region code, e.g. US or US-TX
- reviewer.areasstring[]requiredPolicy area keys (GET compliance/policy_areas)
- reviewer.valid_fromstring (date)required
- reviewer.valid_untilstring (date)required
Response · 201 · object
- idintegerrequired
- userobjectrequired
- user.idintegerrequired
- user.namestring | nullrequired
- credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- credential_numberstringrequired
- credential_issuerstringrequired
- credential_jurisdictionstringrequired
- areasstring[]required
- valid_fromstring (date)required
- valid_untilstring (date)required
- registered_byobjectrequired
- registered_by.idintegerrequired
- registered_by.namestring | nullrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
Errors
400Invalid body401Missing or invalid bearer token403Missing manage_grants, entity-restricted grant, step-up required, self-registration or a read-only token404The member is not in this company409Idempotency-Key reused with a different body or caller, or still running422Inactive member, a credential an area does not accept, or an ended window
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/reviewers" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"reviewer": {
"user_id": 1,
"credential_type": "cpa",
"credential_number": "string",
"credential_issuer": "string",
"credential_jurisdiction": "string",
"areas": [],
"valid_from": "2026-11-01",
"valid_until": "2026-11-01"
}
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/compliance/reviewers/{id}/revokeRevoke a qualified reviewer registration
Records the one permitted revocation with an audited reason; the reviewer can sign nothing afterwards. Earlier sign-offs stand until revoked themselves. A repeat is 409. Needs manage_grants with company-wide access and step-up. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- revokeobjectrequired
- revoke.reasonstringrequired
Response · 200 · object
- idintegerrequired
- userobjectrequired
- user.idintegerrequired
- user.namestring | nullrequired
- credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- credential_numberstringrequired
- credential_issuerstringrequired
- credential_jurisdictionstringrequired
- areasstring[]required
- valid_fromstring (date)required
- valid_untilstring (date)required
- registered_byobjectrequired
- registered_by.idintegerrequired
- registered_by.namestring | nullrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
Errors
400Invalid body401Missing or invalid bearer token403Missing manage_grants, entity-restricted grant, step-up required or a read-only token404Not found in this company409Already revoked
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/reviewers/1/revoke" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"revoke": {
"reason": "string"
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/compliance/signoffsList qualified sign-offs
Newest first, each with its computed status and evidence count. Paginated (Total, Per-Page, Link). Needs view_ledger. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- areastringqueryOnly this policy area key
- jurisdictionstringqueryOnly this jurisdiction
- pageintegerqueryPage
- per_pageintegerqueryPage size
Response · 200 · object[]
- idintegerrequired
- areastringrequired
- jurisdictionstringrequired
- policy_versionstringrequired
- statusstringrequiredOne of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
- reviewerobjectrequired
- reviewer.registration_idintegerrequired
- reviewer.user_idintegerrequired
- reviewer.namestringrequired
- reviewer.credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- reviewer.credential_numberstringrequired
- reviewer.credential_issuerstringrequired
- scopestringrequired
- conclusionstringrequiredOne of: approved, approved_with_exceptions.
- exceptionsstring | nullrequired
- signed_onstring (date)required
- expires_onstring (date)requiredFirst day the sign-off no longer counts
- evidence_countintegerrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
- attachments_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/compliance/signoffsRecord a qualified sign-off
Only a reviewer registered for the area on the signing date, with a credential the area accepts, may sign; for a jurisdiction the area is encoded for and the policy version in force (409 otherwise). Signed on or up to 90 days before the business date; expires after it is signed and no later than the area's maximum validity. With exceptions, describe them. The record is immutable (one revocation aside) and audited; reviewer identity and credential are copied onto it. It counts as current once evidence is attached. Needs view_ledger and an active registration. Honors Idempotency-Key. 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
- signoffobjectrequired
- signoff.areastringrequiredPolicy area key
- signoff.jurisdictionstringrequiredOne of the area's jurisdictions, e.g. US, US-CA or US-GAAP
- signoff.policy_versionstringrequiredMust equal the area's version in force
- signoff.scopestringrequiredWhat was reviewed: sources, scenarios and implementation
- signoff.conclusionstringrequiredOne of: approved, approved_with_exceptions.
- signoff.exceptionsstring | nullRequired with approved_with_exceptions
- signoff.signed_onstring (date)required
- signoff.expires_onstring (date)required
Response · 201 · object
- idintegerrequired
- areastringrequired
- jurisdictionstringrequired
- policy_versionstringrequired
- statusstringrequiredOne of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
- reviewerobjectrequired
- reviewer.registration_idintegerrequired
- reviewer.user_idintegerrequired
- reviewer.namestringrequired
- reviewer.credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- reviewer.credential_numberstringrequired
- reviewer.credential_issuerstringrequired
- scopestringrequired
- conclusionstringrequiredOne of: approved, approved_with_exceptions.
- exceptionsstring | nullrequired
- signed_onstring (date)required
- expires_onstring (date)requiredFirst day the sign-off no longer counts
- evidence_countintegerrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
- attachments_urlstringrequired
Errors
400Invalid body401Missing or invalid bearer token403No accounting access, not a registered reviewer for the area on that date, or a read-only token409Not the policy version in force, or an Idempotency-Key conflict422Unsupported jurisdiction, future or too-old signing date, expiry out of range, or exceptions not described
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"signoff": {
"area": "string",
"jurisdiction": "string",
"policy_version": "string",
"scope": "string",
"conclusion": "approved",
"signed_on": "2026-11-01",
"expires_on": "2026-11-01"
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}Show a qualified sign-off
The sign-off with its computed status and evidence count. Needs view_ledger. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- areastringrequired
- jurisdictionstringrequired
- policy_versionstringrequired
- statusstringrequiredOne of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
- reviewerobjectrequired
- reviewer.registration_idintegerrequired
- reviewer.user_idintegerrequired
- reviewer.namestringrequired
- reviewer.credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- reviewer.credential_numberstringrequired
- reviewer.credential_issuerstringrequired
- scopestringrequired
- conclusionstringrequiredOne of: approved, approved_with_exceptions.
- exceptionsstring | nullrequired
- signed_onstring (date)required
- expires_onstring (date)requiredFirst day the sign-off no longer counts
- evidence_countintegerrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
- attachments_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsList evidence on a qualified sign-off
Oldest first. Needs view_ledger. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, wrong company, or a token without the required scope404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsAttach evidence to a qualified sign-off
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES): the review memo, workpapers or engagement letter. Only the reviewer who signed may attach, and not after revocation. Writes an attachment_added audit event on the sign-off. Needs view_ledger. 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
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, not the signing reviewer, or a read-only token404Not found in this company409The sign-off is revoked422No file, an empty file, a disallowed type or too large
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/revokeRevoke a qualified sign-off
Records the one permitted revocation with an audited reason; the area falls back to its other sign-offs or shows revoked. A repeat is 409. Needs manage_grants with company-wide access and step-up. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- revokeobjectrequired
- revoke.reasonstringrequired
Response · 200 · object
- idintegerrequired
- areastringrequired
- jurisdictionstringrequired
- policy_versionstringrequired
- statusstringrequiredOne of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
- reviewerobjectrequired
- reviewer.registration_idintegerrequired
- reviewer.user_idintegerrequired
- reviewer.namestringrequired
- reviewer.credential_typestringrequiredOne of: cpa, payroll_specialist, tax_advisor.
- reviewer.credential_numberstringrequired
- reviewer.credential_issuerstringrequired
- scopestringrequired
- conclusionstringrequiredOne of: approved, approved_with_exceptions.
- exceptionsstring | nullrequired
- signed_onstring (date)required
- expires_onstring (date)requiredFirst day the sign-off no longer counts
- evidence_countintegerrequired
- created_atstring (date-time)required
- revoked_atstring | null (date-time)required
- revoked_by_idinteger | nullrequired
- revoke_reasonstring | nullrequired
- attachments_urlstringrequired
Errors
400Invalid body401Missing or invalid bearer token403Missing manage_grants, entity-restricted grant, step-up required or a read-only token404Not found in this company409Already revoked
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/compliance/signoffs/1/revoke" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"revoke": {
"reason": "string"
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/control_objectivesSOC 1 control register
Each control objective (CO-1 to CO-10) with its owner, frequency, procedure, newest evidence (system records read live, and recorded evidence) and state as of the company's business date: current, overdue (newest evidence older than the frequency), no_evidence or unassigned (no owner). Needs view_ledger on an unrestricted grant. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- as_ofstring (date)required
- objectivesobject[]required
- objectives[].keystringrequired
- objectives[].titlestringrequired
- objectives[].objectivestringrequired
- objectives[].expected_evidencestringrequired
- objectives[].default_frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- objectives[].frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- objectives[].system_sourcesstring[]required
- objectives[].ownernull | objectrequired
- objectives[].procedurestring | nullrequired
- objectives[].statestringrequiredOne of: current, overdue, no_evidence, unassigned.
- objectives[].due_onstring | null (date)required
- objectives[].days_overdueintegerrequired
- objectives[].evidence_countintegerrequired
- objectives[].last_evidencenull | objectrequired
- objectives[].updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, a restricted grant, wrong company or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/control_objectives" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Get a control objective with its evidence
The objective and every evidence item, system and recorded, newest first. Needs view_ledger on an unrestricted grant. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- objective_keystringpathrequiredControl objective key, e.g. CO-1
Response · 200 · object
- keystringrequired
- titlestringrequired
- objectivestringrequired
- expected_evidencestringrequired
- default_frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- system_sourcesstring[]required
- ownernull | objectrequired
- owner.idintegerrequired
- owner.namestring | nullrequired
- procedurestring | nullrequired
- statestringrequiredOne of: current, overdue, no_evidence, unassigned.
- due_onstring | null (date)required
- days_overdueintegerrequired
- evidence_countintegerrequired
- last_evidencenull | objectrequired
- last_evidence.sourcestringrequiredOne of: system, recorded.
- last_evidence.kindstringrequired
- last_evidence.titlestringrequired
- last_evidence.datestring (date)required
- last_evidence.ref_idinteger | nullrequired
- last_evidence.hrefstring | nullrequired
- last_evidence.urlstring | nullrequired
- last_evidence.notestring | nullrequired
- last_evidence.idinteger | nullrequired
- last_evidence.recorded_bynull | objectrequired
- updated_atstring | null (date-time)required
- evidenceobject[]required
- evidence[].sourcestringrequiredOne of: system, recorded.
- evidence[].kindstringrequired
- evidence[].titlestringrequired
- evidence[].datestring (date)required
- evidence[].ref_idinteger | nullrequired
- evidence[].hrefstring | nullrequired
- evidence[].urlstring | nullrequired
- evidence[].notestring | nullrequired
- evidence[].idinteger | nullrequired
- evidence[].recorded_bynull | objectrequired
Errors
401Missing or invalid bearer token403No accounting access, a restricted grant, wrong company or a token without the required scope404Unknown objective
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/control_objectives/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
PUT/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Assign a control objective's owner and frequency
Sets the owner (an active member with accounting access, or null), frequency (monthly, quarterly, semiannual, annual) and procedure. Audited with before and after. Needs manage_grants on an unrestricted grant. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- objective_keystringpathrequiredControl objective key, e.g. CO-1
Request body
- control_objectiveobjectrequired
- control_objective.owner_user_idinteger | nullrequired
- control_objective.frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- control_objective.procedurestring | null
Response · 200 · object
- keystringrequired
- titlestringrequired
- objectivestringrequired
- expected_evidencestringrequired
- default_frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- frequencystringrequiredOne of: monthly, quarterly, semiannual, annual.
- system_sourcesstring[]required
- ownernull | objectrequired
- owner.idintegerrequired
- owner.namestring | nullrequired
- procedurestring | nullrequired
- statestringrequiredOne of: current, overdue, no_evidence, unassigned.
- due_onstring | null (date)required
- days_overdueintegerrequired
- evidence_countintegerrequired
- last_evidencenull | objectrequired
- last_evidence.sourcestringrequiredOne of: system, recorded.
- last_evidence.kindstringrequired
- last_evidence.titlestringrequired
- last_evidence.datestring (date)required
- last_evidence.ref_idinteger | nullrequired
- last_evidence.hrefstring | nullrequired
- last_evidence.urlstring | nullrequired
- last_evidence.notestring | nullrequired
- last_evidence.idinteger | nullrequired
- last_evidence.recorded_bynull | objectrequired
- updated_atstring | null (date-time)required
Errors
401Missing or invalid bearer token403Missing manage_grants, a restricted grant or a read-only token404Unknown objective or owner422Invalid body or an owner without accounting access
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/control_objectives/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"control_objective": {
"owner_user_id": 1,
"frequency": "monthly"
}
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}/evidenceRecord control evidence
Appends evidence of a control performance (append-only): a DR rehearsal report, a document link, or a pointer to an access review or qualified sign-off of this company (ref_id). Not dated in the future. The objective's owner or a grant manager. Needs view_ledger on an unrestricted grant. Honors Idempotency-Key. Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- objective_keystringpathrequiredControl objective key, e.g. CO-8
- 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
- evidenceobjectrequired
- evidence.kindstringrequiredOne of: dr_rehearsal, access_review, close_signoff, qualified_signoff, integrity_run, document, other.
- evidence.titlestringrequired
- evidence.urlstring | null (uri)
- evidence.ref_idinteger | null
- evidence.performed_onstring (date)required
- evidence.notestring | null
Response · 201 · object
- idintegerrequired
- objectivestringrequired
- kindstringrequired
- titlestringrequired
- urlstring | nullrequired
- ref_idinteger | nullrequired
- performed_onstring (date)required
- notestring | nullrequired
- recorded_by_idintegerrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403Neither the owner nor a grant manager, a restricted grant or a read-only token404Unknown objective409Idempotency-Key reused with a different body or caller, or still running422Invalid body, a future date, or a ref_id that is not a completed access review or a sign-off of this company
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/control_objectives/1/evidence" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"evidence": {
"kind": "dr_rehearsal",
"title": "string",
"performed_on": "2026-11-01"
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/grantsList accounting access
Every company member with their accounting role and permission flags. Company admins are implicit owners. Needs manage_grants. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- searchstringqueryName or email
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- user_idintegerrequired
- namestringrequired
- emailstringrequired
- is_activebooleanrequired
- is_adminbooleanrequired
- roleanyrequiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
- effective_roleanyrequiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
- flagsobjectrequired
- flags.view_ledgerbooleanrequired
- flags.post_journalbooleanrequired
- flags.approve_journalbooleanrequired
- flags.manage_coabooleanrequired
- flags.close_periodbooleanrequired
- flags.ap_enterbooleanrequired
- flags.ap_approvebooleanrequired
- flags.release_paymentsbooleanrequired
- flags.manage_vendor_bankingbooleanrequired
- flags.ar_enterbooleanrequired
- flags.ar_approvebooleanrequired
- flags.payroll_viewbooleanrequired
- flags.payroll_runbooleanrequired
- flags.view_payroll_piibooleanrequired
- flags.bank_reconcilebooleanrequired
- flags.manage_integrationsbooleanrequired
- flags.manage_grantsbooleanrequired
- flags.job_forecast_editbooleanrequired
- entity_idsinteger[]required
- updated_atstring | null (date-time)required
- expires_atstring | null (date-time)requiredEnd of access; at or after it the grant resolves to no access.
- certified_atstring | null (date-time)requiredLast access-review certification.
- certified_by_idinteger | nullrequired
- sod_conflictsany[]requiredSegregation of duties rules this grant's flags combine. One of: ap_full_cycle, payroll_full_cycle, gl_full_cycle, grants_with_payments.
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/grants" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
PATCH/rest/v1.0/companies/{company_id}/accounting/grants/{id}Set a member's accounting access
Grants a role preset (owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly) or none to revoke. Individual flags override the preset; entity_ids limits the grant to some entities. Needs manage_grants. Audited in the same transaction. Requires the accounting:write scope. 422 when a project_manager_view grant would hold an AP, AR, banking or payroll flag (ap_enter, ap_approve, release_payments, manage_vendor_banking, ar_enter, ar_approve, bank_reconcile, payroll_view, payroll_run, view_payroll_pii): the role is project-scoped and those areas are entity-wide. A grant saved with one before this check resolves with it off, so every AP, AR, banking and payroll endpoint answers it 403. Preventive segregation of duties: rules ap_full_cycle (ap_enter + ap_approve + release_payments + manage_vendor_banking), payroll_full_cycle (payroll_run + view_payroll_pii + manage_vendor_banking) and gl_full_cycle (post_journal + approve_journal + close_period) warn: a grant that gains one needs reason (422 sod_reason_required), and the response lists every conflict it holds in warnings. grants_with_payments (manage_grants + release_payments) blocks (422 sod_blocked) except on the owner role. 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
- idintegerpathrequiredThe member's user id
Request body
- grantobjectrequired
- grant.roleanyrequiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
- grant.entity_idsinteger[]
- grant.view_ledgerboolean
- grant.post_journalboolean
- grant.approve_journalboolean
- grant.manage_coaboolean
- grant.close_periodboolean
- grant.ap_enterboolean
- grant.ap_approveboolean
- grant.release_paymentsboolean
- grant.manage_vendor_bankingboolean
- grant.ar_enterboolean
- grant.ar_approveboolean
- grant.payroll_viewboolean
- grant.payroll_runboolean
- grant.view_payroll_piiboolean
- grant.bank_reconcileboolean
- grant.manage_integrationsboolean
- grant.manage_grantsboolean
- grant.job_forecast_editboolean
- grant.reasonstringWhy a grant that gains a segregation of duties conflict is needed; audited with the change.
- grant.expires_atstring | null (date)Last company-local day of access; null clears it. Must be today or later.
Response · 200 · object
- user_idintegerrequired
- namestringrequired
- emailstringrequired
- is_activebooleanrequired
- is_adminbooleanrequired
- roleanyrequiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
- effective_roleanyrequiredOne of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
- flagsobjectrequired
- flags.view_ledgerbooleanrequired
- flags.post_journalbooleanrequired
- flags.approve_journalbooleanrequired
- flags.manage_coabooleanrequired
- flags.close_periodbooleanrequired
- flags.ap_enterbooleanrequired
- flags.ap_approvebooleanrequired
- flags.release_paymentsbooleanrequired
- flags.manage_vendor_bankingbooleanrequired
- flags.ar_enterbooleanrequired
- flags.ar_approvebooleanrequired
- flags.payroll_viewbooleanrequired
- flags.payroll_runbooleanrequired
- flags.view_payroll_piibooleanrequired
- flags.bank_reconcilebooleanrequired
- flags.manage_integrationsbooleanrequired
- flags.manage_grantsbooleanrequired
- flags.job_forecast_editbooleanrequired
- entity_idsinteger[]required
- updated_atstring | null (date-time)required
- expires_atstring | null (date-time)requiredEnd of access; at or after it the grant resolves to no access.
- certified_atstring | null (date-time)requiredLast access-review certification.
- certified_by_idinteger | nullrequired
- sod_conflictsany[]requiredSegregation of duties rules this grant's flags combine. One of: ap_full_cycle, payroll_full_cycle, gl_full_cycle, grants_with_payments.
- warningsobject[]required
- warnings[].rulestringrequired
- warnings[].severityanyrequiredOne of: warn, block.
- warnings[].flagsstring[]required
- warnings[].riskstringrequired
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/grants/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"grant": {
"role": "owner"
}
}'Accounting / Accounting Access
POST/rest/v1.0/companies/{company_id}/accounting/grants/access_reviewCertify an access review
Quarterly access review: decide every grant inside your entity scope except your own (keep stamps certified_at; revoke deletes the grant), in one transaction with one audit row per grant (grant_certified or grant_revoked). 422 when a grant is undecided or a decision names a member without a reviewable grant. Needs manage_grants. Requires the accounting:write scope. 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
- 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
- access_reviewobjectrequired
- access_review.decisionsobject[]required
- access_review.decisions[].user_idintegerrequired
- access_review.decisions[].decisionanyrequiredOne of: keep, revoke.
- access_review.notestring
Response · 200 · object
- keptintegerrequired
- revokedintegerrequired
- certified_atstring (date-time)required
Errors
400Malformed JSON body, or the request was refused by a business rule (message list)401Missing or invalid bearer token403No accounting access, missing permission, wrong company, or read-only 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/grants/access_review" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"access_review": {
"decisions": [
{
"user_id": 1,
"decision": "keep"
}
]
}
}'Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/sod_conflictsSegregation of duties conflict report
Every member whose effective duties (grant flags plus approval flags reached through active or scheduled delegations) match an enabled rule, with each duty's source and the evidence: the grant, its last audited change and SoD reason, and the delegations completing the combination. Company administrators are implicit owners. Needs manage_grants on an unrestricted grant. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- rulesobject[]required
- rules[].keystringrequired
- rules[].namestringrequired
- rules[].dutiesstring[]requiredOne 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.
- rules[].severitystringrequiredOne of: warn, block.
- rules[].enabledbooleanrequired
- rules[].riskstringrequired
- rules[].sourcestringrequiredOne of: default, customized, custom.
- rules[].updated_atstring | null (date-time)required
- rules[].updated_by_idinteger | nullrequired
- totalsobjectrequired
- totals.membersintegerrequired
- totals.with_conflictsintegerrequired
- totals.blockintegerrequired
- totals.via_delegationintegerrequired
- membersobject[]required
- members[].userobjectrequired
- members[].kindstringrequiredOne of: grant, implicit_owner.
- members[].rolestringrequired
- members[].entity_idsinteger[]required
- members[].project_scopedbooleanrequired
- members[].dutiesobject[]required
- members[].conflictsobject[]required
- members[].evidenceobjectrequired
Errors
401Missing or invalid bearer token403Missing manage_grants, a restricted grant, wrong company or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/sod_conflicts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
GET/rest/v1.0/companies/{company_id}/accounting/sod_rulesList segregation of duties rules
The built-in default rules (source default, or customized when the company changed their severity, wording or on/off) followed by the company's custom rules. Needs manage_grants on an unrestricted grant. Requires accounting:read.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- keystringrequired
- namestringrequired
- dutiesstring[]requiredOne 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.
- severitystringrequiredOne of: warn, block.
- enabledbooleanrequired
- riskstringrequired
- sourcestringrequiredOne of: default, customized, custom.
- updated_atstring | null (date-time)required
- updated_by_idinteger | nullrequired
Errors
401Missing or invalid bearer token403Missing manage_grants, a restricted grant, wrong company or a token without the required scope
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/sod_rules" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounting Access
PUT/rest/v1.0/companies/{company_id}/accounting/sod_rules/{rule_key}Create or change a segregation of duties rule
Creates a custom rule (name, 2-4 duties, severity, risk) or changes one: a built-in rule's severity, wording and on/off (its duties are fixed), a custom rule's duties too. Every change needs a reason and is audited with before and after; weakening (block to warn, off, other duties) is flagged as sod_rule_weakened. Existing grants are never changed: current_holders lists who already holds the combination; their next grant change needs a reason. Needs manage_grants on an unrestricted grant and step-up (a token needs accounting:step_up). Requires accounting:write.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- rule_keystringpathrequiredRule key (lowercase letters, digits and underscores)
Request body
- sod_ruleobjectrequired
- sod_rule.namestring
- sod_rule.dutiesstring[]Custom rules only; a built-in rule's duties are fixed 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.
- sod_rule.severitystringrequiredOne of: warn, block.
- sod_rule.enabledbooleanrequired
- sod_rule.riskstring
- sod_rule.reasonstringrequired
Response · 200 · object
- keystringrequired
- namestringrequired
- dutiesstring[]requiredOne 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.
- severitystringrequiredOne of: warn, block.
- enabledbooleanrequired
- riskstringrequired
- sourcestringrequiredOne of: default, customized, custom.
- updated_atstring | null (date-time)required
- updated_by_idinteger | nullrequired
- current_holdersobject[]required
- current_holders[].user_idintegerrequired
- current_holders[].namestringrequired
Errors
401Missing or invalid bearer token403Missing manage_grants, a restricted grant, step-up required or a read-only token404Malformed rule key422Invalid body, changed duties on a built-in rule, or a new rule without duties, name or risk
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/sod_rules/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"sod_rule": {
"severity": "warn",
"enabled": true,
"reason": "string"
}
}'