Esc

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

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.

26 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/access_reviewsList access review campaigns
  2. POST /rest/v1.0/companies/{company_id}/accounting/access_reviewsOpen an access review campaign
  3. GET /rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}Get an access review campaign with its snapshot
  4. POST /rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/cancelCancel an access review campaign
  5. POST /rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/completeComplete an access review campaign
  6. POST /rest/v1.0/companies/{company_id}/accounting/access_reviews/{id}/items/{item_id}/decisionDecide one access review item
  7. GET /rest/v1.0/companies/{company_id}/accounting/compliance/policy_areasPolicy areas and their qualified sign-off status
  8. GET /rest/v1.0/companies/{company_id}/accounting/compliance/reviewersList registered qualified reviewers
  9. POST /rest/v1.0/companies/{company_id}/accounting/compliance/reviewersRegister a qualified reviewer
  10. POST /rest/v1.0/companies/{company_id}/accounting/compliance/reviewers/{id}/revokeRevoke a qualified reviewer registration
  11. GET /rest/v1.0/companies/{company_id}/accounting/compliance/signoffsList qualified sign-offs
  12. POST /rest/v1.0/companies/{company_id}/accounting/compliance/signoffsRecord a qualified sign-off
  13. GET /rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}Show a qualified sign-off
  14. GET /rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsList evidence on a qualified sign-off
  15. POST /rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/attachmentsAttach evidence to a qualified sign-off
  16. POST /rest/v1.0/companies/{company_id}/accounting/compliance/signoffs/{id}/revokeRevoke a qualified sign-off
  17. GET /rest/v1.0/companies/{company_id}/accounting/control_objectivesSOC 1 control register
  18. GET /rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Get a control objective with its evidence
  19. PUT /rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}Assign a control objective's owner and frequency
  20. POST /rest/v1.0/companies/{company_id}/accounting/control_objectives/{objective_key}/evidenceRecord control evidence
  21. GET /rest/v1.0/companies/{company_id}/accounting/grantsList accounting access
  22. PATCH /rest/v1.0/companies/{company_id}/accounting/grants/{id}Set a member's accounting access
  23. POST /rest/v1.0/companies/{company_id}/accounting/grants/access_reviewCertify an access review
  24. GET /rest/v1.0/companies/{company_id}/accounting/sod_conflictsSegregation of duties conflict report
  25. GET /rest/v1.0/companies/{company_id}/accounting/sod_rulesList segregation of duties rules
  26. 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_reviews

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • status
    stringquery
    One of: open, completed, cancelled.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • kind
    stringrequired
    One of: quarterly, ad_hoc.
  • title
    stringrequired
  • period
    string | nullrequired
  • entity_id
    integer | nullrequired
  • status
    stringrequired
    One of: open, completed, cancelled.
  • due_on
    string (date)required
  • dormant_days
    integerrequired
  • reviewers
    object[]required
  • reviewers[].id
    integerrequired
  • reviewers[].name
    string | nullrequired
  • snapshot_at
    string (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • counts
    objectrequired
  • counts.items
    integerrequired
  • counts.decided
    integerrequired
  • counts.dormant
    integerrequired
  • counts.sod
    integerrequired
  • counts.keep
    integerrequired
  • counts.modify
    integerrequired
  • counts.revoke
    integerrequired
  • summary
    object | nullrequired
    Decision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, a project-scoped grant, wrong company or a token without the required scope

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • access_review
    objectrequired
  • access_review.kind
    stringrequired
    One of: quarterly, ad_hoc.
  • access_review.title
    string
  • access_review.period
    string
    Required for quarterly campaigns, e.g. 2026-Q4
  • access_review.entity_id
    integer | null
    Omit or null for the whole company
  • access_review.due_on
    string (date)required
  • access_review.dormant_days
    integer
  • access_review.reviewer_ids
    integer[]required

Response · 201 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: quarterly, ad_hoc.
  • title
    stringrequired
  • period
    string | nullrequired
  • entity_id
    integer | nullrequired
  • status
    stringrequired
    One of: open, completed, cancelled.
  • due_on
    string (date)required
  • dormant_days
    integerrequired
  • reviewers
    object[]required
  • reviewers[].id
    integerrequired
  • reviewers[].name
    string | nullrequired
  • snapshot_at
    string (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • counts
    objectrequired
  • counts.items
    integerrequired
  • counts.decided
    integerrequired
  • counts.dormant
    integerrequired
  • counts.sod
    integerrequired
  • counts.keep
    integerrequired
  • counts.modify
    integerrequired
  • counts.revoke
    integerrequired
  • summary
    object | nullrequired
    Decision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, an entity outside the caller's grant, wrong company or a read-only token
  • 404Unknown entity or reviewer
  • 409A quarterly campaign already exists for this scope and period, or an Idempotency-Key conflict
  • 422Invalid 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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: quarterly, ad_hoc.
  • title
    stringrequired
  • period
    string | nullrequired
  • entity_id
    integer | nullrequired
  • status
    stringrequired
    One of: open, completed, cancelled.
  • due_on
    string (date)required
  • dormant_days
    integerrequired
  • reviewers
    object[]required
  • reviewers[].id
    integerrequired
  • reviewers[].name
    string | nullrequired
  • snapshot_at
    string (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • counts
    objectrequired
  • counts.items
    integerrequired
  • counts.decided
    integerrequired
  • counts.dormant
    integerrequired
  • counts.sod
    integerrequired
  • counts.keep
    integerrequired
  • counts.modify
    integerrequired
  • counts.revoke
    integerrequired
  • summary
    object | nullrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].review_id
    integerrequired
  • items[].user
    objectrequired
  • items[].kind
    stringrequired
    One of: grant, implicit_owner.
  • items[].grant_id
    integer | nullrequired
  • items[].role
    stringrequired
  • items[].flags
    string[]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.
  • items[].delegated_flags
    string[]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.
  • items[].entity_ids
    integer[]required
  • items[].project_scoped
    booleanrequired
  • items[].expires_at
    string | null (date-time)required
  • items[].certified_at
    string | null (date-time)required
  • items[].mfa
    booleanrequired
  • items[].delegations
    object[]required
    id, direction (received or given), other_user_id, other_name, doc_types, flags, max_amount, entity_ids, starts_at, ends_at
  • items[].api_tokens
    object[]required
    id, scopes (accounting scopes; ["*"] for a legacy full-access token), created_at, expires_at. Never the token.
  • items[].last_activity_at
    string | null (date-time)required
  • items[].dormant
    booleanrequired
  • items[].sod_conflicts
    object[]required
    rule, name, severity, flags, via_delegation, delegation_ids
  • items[].decision
    string | nullrequired
    One of: keep, modify, revoke, null.
  • items[].reason
    string | nullrequired
  • items[].change
    object | nullrequired
    The grant a modify decision applied
  • items[].decided_by
    null | objectrequired
  • items[].decided_at
    string | null (date-time)required
  • items[].drift_at_decision
    boolean | nullrequired
  • items[].applied_audit_id
    integer | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, wrong company or a token without the required scope
  • 404No such campaign in the caller's scope

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • cancel
    objectrequired
  • cancel.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: quarterly, ad_hoc.
  • title
    stringrequired
  • period
    string | nullrequired
  • entity_id
    integer | nullrequired
  • status
    stringrequired
    One of: open, completed, cancelled.
  • due_on
    string (date)required
  • dormant_days
    integerrequired
  • reviewers
    object[]required
  • reviewers[].id
    integerrequired
  • reviewers[].name
    string | nullrequired
  • snapshot_at
    string (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • counts
    objectrequired
  • counts.items
    integerrequired
  • counts.decided
    integerrequired
  • counts.dormant
    integerrequired
  • counts.sod
    integerrequired
  • counts.keep
    integerrequired
  • counts.modify
    integerrequired
  • counts.revoke
    integerrequired
  • summary
    object | nullrequired
    Decision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, or neither creator nor reviewer
  • 404No such campaign
  • 409Already completed or cancelled
  • 422Invalid body

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • complete
    objectrequired
  • complete.note
    string

Response · 200 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: quarterly, ad_hoc.
  • title
    stringrequired
  • period
    string | nullrequired
  • entity_id
    integer | nullrequired
  • status
    stringrequired
    One of: open, completed, cancelled.
  • due_on
    string (date)required
  • dormant_days
    integerrequired
  • reviewers
    object[]required
  • reviewers[].id
    integerrequired
  • reviewers[].name
    string | nullrequired
  • snapshot_at
    string (date-time)required
  • created_by_id
    integerrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • cancel_reason
    string | nullrequired
  • counts
    objectrequired
  • counts.items
    integerrequired
  • counts.decided
    integerrequired
  • counts.dormant
    integerrequired
  • counts.sod
    integerrequired
  • counts.keep
    integerrequired
  • counts.modify
    integerrequired
  • counts.revoke
    integerrequired
  • summary
    object | nullrequired
    Decision counts stored at completion: items, keep, modify, revoke, dormant, sod_conflicts, drift, note

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants or not a designated reviewer
  • 404No such campaign
  • 409Already completed or cancelled
  • 422Undecided items remain

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • decision
    objectrequired
  • decision.decision
    stringrequired
    One of: keep, modify, revoke.
  • decision.reason
    stringrequired
  • decision.grant
    object
    modify only: the grant to apply, as PATCH grants/{id} (role, entity_ids, expires_at and any permission flag as a boolean)
  • decision.grant.role
    stringrequired
  • decision.grant.entity_ids
    integer[]
  • decision.grant.expires_at
    string | null (date)

Response · 200 · object

  • id
    integerrequired
  • review_id
    integerrequired
  • user
    objectrequired
  • user.id
    integerrequired
  • user.name
    stringrequired
  • user.login
    stringrequired
  • user.is_active
    booleanrequired
  • kind
    stringrequired
    One of: grant, implicit_owner.
  • grant_id
    integer | nullrequired
  • role
    stringrequired
  • flags
    string[]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.
  • delegated_flags
    string[]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.
  • entity_ids
    integer[]required
  • project_scoped
    booleanrequired
  • expires_at
    string | null (date-time)required
  • certified_at
    string | null (date-time)required
  • mfa
    booleanrequired
  • delegations
    object[]required
    id, direction (received or given), other_user_id, other_name, doc_types, flags, max_amount, entity_ids, starts_at, ends_at
  • api_tokens
    object[]required
    id, scopes (accounting scopes; ["*"] for a legacy full-access token), created_at, expires_at. Never the token.
  • last_activity_at
    string | null (date-time)required
  • dormant
    booleanrequired
  • sod_conflicts
    object[]required
    rule, name, severity, flags, via_delegation, delegation_ids
  • decision
    string | nullrequired
    One of: keep, modify, revoke, null.
  • reason
    string | nullrequired
  • change
    object | nullrequired
    The grant a modify decision applied
  • decided_by
    null | objectrequired
  • decided_by.id
    integerrequired
  • decided_by.name
    string | nullrequired
  • decided_at
    string | null (date-time)required
  • drift_at_decision
    boolean | nullrequired
  • applied_audit_id
    integer | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, step-up required, not a designated reviewer, or the caller's own item
  • 404No such campaign or item
  • 409Already decided, campaign not open, or a modify on a grant that no longer exists
  • 422Invalid body, a non-keep decision on an administrator, or a grant change the grant path refuses (sod_blocked, sod_reason_required)

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • as_of
    string (date)required
  • areas
    object[]required
  • areas[].area
    stringrequired
  • areas[].title
    stringrequired
  • areas[].covers
    stringrequired
  • areas[].policy_version
    stringrequired
  • areas[].credential_types
    string[]required
    One of: cpa, payroll_specialist, tax_advisor.
  • areas[].max_validity_months
    integerrequired
  • areas[].counts
    objectrequired
  • areas[].jurisdictions
    object[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

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

List registered qualified reviewers

Every registration, revoked ones included, oldest first. Needs view_ledger. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • user
    objectrequired
  • user.id
    integerrequired
  • user.name
    string | nullrequired
  • credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • credential_number
    stringrequired
  • credential_issuer
    stringrequired
  • credential_jurisdiction
    stringrequired
  • areas
    string[]required
  • valid_from
    string (date)required
  • valid_until
    string (date)required
  • registered_by
    objectrequired
  • registered_by.id
    integerrequired
  • registered_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • reviewer
    objectrequired
  • reviewer.user_id
    integerrequired
    An active member of this company (not the caller)
  • reviewer.credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • reviewer.credential_number
    stringrequired
  • reviewer.credential_issuer
    stringrequired
  • reviewer.credential_jurisdiction
    stringrequired
    Country or region code, e.g. US or US-TX
  • reviewer.areas
    string[]required
    Policy area keys (GET compliance/policy_areas)
  • reviewer.valid_from
    string (date)required
  • reviewer.valid_until
    string (date)required

Response · 201 · object

  • id
    integerrequired
  • user
    objectrequired
  • user.id
    integerrequired
  • user.name
    string | nullrequired
  • credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • credential_number
    stringrequired
  • credential_issuer
    stringrequired
  • credential_jurisdiction
    stringrequired
  • areas
    string[]required
  • valid_from
    string (date)required
  • valid_until
    string (date)required
  • registered_by
    objectrequired
  • registered_by.id
    integerrequired
  • registered_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired

Errors

  • 400Invalid body
  • 401Missing or invalid bearer token
  • 403Missing manage_grants, entity-restricted grant, step-up required, self-registration or a read-only token
  • 404The member is not in this company
  • 409Idempotency-Key reused with a different body or caller, or still running
  • 422Inactive member, a credential an area does not accept, or an ended window

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • revoke
    objectrequired
  • revoke.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • user
    objectrequired
  • user.id
    integerrequired
  • user.name
    string | nullrequired
  • credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • credential_number
    stringrequired
  • credential_issuer
    stringrequired
  • credential_jurisdiction
    stringrequired
  • areas
    string[]required
  • valid_from
    string (date)required
  • valid_until
    string (date)required
  • registered_by
    objectrequired
  • registered_by.id
    integerrequired
  • registered_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired

Errors

  • 400Invalid body
  • 401Missing or invalid bearer token
  • 403Missing manage_grants, entity-restricted grant, step-up required or a read-only token
  • 404Not found in this company
  • 409Already revoked

Example request

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

List qualified sign-offs

Newest first, each with its computed status and evidence count. Paginated (Total, Per-Page, Link). Needs view_ledger. Requires accounting:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • area
    stringquery
    Only this policy area key
  • jurisdiction
    stringquery
    Only this jurisdiction
  • page
    integerquery
    Page
  • per_page
    integerquery
    Page size

Response · 200 · object[]

  • id
    integerrequired
  • area
    stringrequired
  • jurisdiction
    stringrequired
  • policy_version
    stringrequired
  • status
    stringrequired
    One of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
  • reviewer
    objectrequired
  • reviewer.registration_id
    integerrequired
  • reviewer.user_id
    integerrequired
  • reviewer.name
    stringrequired
  • reviewer.credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • reviewer.credential_number
    stringrequired
  • reviewer.credential_issuer
    stringrequired
  • scope
    stringrequired
  • conclusion
    stringrequired
    One of: approved, approved_with_exceptions.
  • exceptions
    string | nullrequired
  • signed_on
    string (date)required
  • expires_on
    string (date)required
    First day the sign-off no longer counts
  • evidence_count
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired
  • attachments_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • signoff
    objectrequired
  • signoff.area
    stringrequired
    Policy area key
  • signoff.jurisdiction
    stringrequired
    One of the area's jurisdictions, e.g. US, US-CA or US-GAAP
  • signoff.policy_version
    stringrequired
    Must equal the area's version in force
  • signoff.scope
    stringrequired
    What was reviewed: sources, scenarios and implementation
  • signoff.conclusion
    stringrequired
    One of: approved, approved_with_exceptions.
  • signoff.exceptions
    string | null
    Required with approved_with_exceptions
  • signoff.signed_on
    string (date)required
  • signoff.expires_on
    string (date)required

Response · 201 · object

  • id
    integerrequired
  • area
    stringrequired
  • jurisdiction
    stringrequired
  • policy_version
    stringrequired
  • status
    stringrequired
    One of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
  • reviewer
    objectrequired
  • reviewer.registration_id
    integerrequired
  • reviewer.user_id
    integerrequired
  • reviewer.name
    stringrequired
  • reviewer.credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • reviewer.credential_number
    stringrequired
  • reviewer.credential_issuer
    stringrequired
  • scope
    stringrequired
  • conclusion
    stringrequired
    One of: approved, approved_with_exceptions.
  • exceptions
    string | nullrequired
  • signed_on
    string (date)required
  • expires_on
    string (date)required
    First day the sign-off no longer counts
  • evidence_count
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired
  • attachments_url
    stringrequired

Errors

  • 400Invalid body
  • 401Missing or invalid bearer token
  • 403No accounting access, not a registered reviewer for the area on that date, or a read-only token
  • 409Not the policy version in force, or an Idempotency-Key conflict
  • 422Unsupported jurisdiction, future or too-old signing date, expiry out of range, or exceptions not described

Example request

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • area
    stringrequired
  • jurisdiction
    stringrequired
  • policy_version
    stringrequired
  • status
    stringrequired
    One of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
  • reviewer
    objectrequired
  • reviewer.registration_id
    integerrequired
  • reviewer.user_id
    integerrequired
  • reviewer.name
    stringrequired
  • reviewer.credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • reviewer.credential_number
    stringrequired
  • reviewer.credential_issuer
    stringrequired
  • scope
    stringrequired
  • conclusion
    stringrequired
    One of: approved, approved_with_exceptions.
  • exceptions
    string | nullrequired
  • signed_on
    string (date)required
  • expires_on
    string (date)required
    First day the sign-off no longer counts
  • evidence_count
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired
  • attachments_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Not found in this company

Example request

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

List evidence on a qualified sign-off

Oldest first. Needs view_ledger. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • doc_type
    stringrequired
    One of: 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, wrong company, or a token without the required scope
  • 404Not found in this company

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • file
    string (binary)required

Response · 201 · object

  • id
    integerrequired
  • doc_type
    stringrequired
    One 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_id
    integerrequired
  • name
    stringrequired
  • content_type
    stringrequired
  • size_bytes
    integerrequired
  • sha256
    stringrequired
  • uploaded_by
    objectrequired
  • uploaded_by.id
    integerrequired
  • uploaded_by.name
    string | nullrequired
  • created_at
    string (date-time)required
  • download_url
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, not the signing reviewer, or a read-only token
  • 404Not found in this company
  • 409The sign-off is revoked
  • 422No file, an empty file, a disallowed type or too large

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • revoke
    objectrequired
  • revoke.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • area
    stringrequired
  • jurisdiction
    stringrequired
  • policy_version
    stringrequired
  • status
    stringrequired
    One of: current, awaiting_evidence, expired, outdated, revoked, not_reviewed.
  • reviewer
    objectrequired
  • reviewer.registration_id
    integerrequired
  • reviewer.user_id
    integerrequired
  • reviewer.name
    stringrequired
  • reviewer.credential_type
    stringrequired
    One of: cpa, payroll_specialist, tax_advisor.
  • reviewer.credential_number
    stringrequired
  • reviewer.credential_issuer
    stringrequired
  • scope
    stringrequired
  • conclusion
    stringrequired
    One of: approved, approved_with_exceptions.
  • exceptions
    string | nullrequired
  • signed_on
    string (date)required
  • expires_on
    string (date)required
    First day the sign-off no longer counts
  • evidence_count
    integerrequired
  • created_at
    string (date-time)required
  • revoked_at
    string | null (date-time)required
  • revoked_by_id
    integer | nullrequired
  • revoke_reason
    string | nullrequired
  • attachments_url
    stringrequired

Errors

  • 400Invalid body
  • 401Missing or invalid bearer token
  • 403Missing manage_grants, entity-restricted grant, step-up required or a read-only token
  • 404Not found in this company
  • 409Already revoked

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • as_of
    string (date)required
  • objectives
    object[]required
  • objectives[].key
    stringrequired
  • objectives[].title
    stringrequired
  • objectives[].objective
    stringrequired
  • objectives[].expected_evidence
    stringrequired
  • objectives[].default_frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • objectives[].frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • objectives[].system_sources
    string[]required
  • objectives[].owner
    null | objectrequired
  • objectives[].procedure
    string | nullrequired
  • objectives[].state
    stringrequired
    One of: current, overdue, no_evidence, unassigned.
  • objectives[].due_on
    string | null (date)required
  • objectives[].days_overdue
    integerrequired
  • objectives[].evidence_count
    integerrequired
  • objectives[].last_evidence
    null | objectrequired
  • objectives[].updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a restricted grant, wrong company or a token without the required scope

Example request

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • objective_key
    stringpathrequired
    Control objective key, e.g. CO-1

Response · 200 · object

  • key
    stringrequired
  • title
    stringrequired
  • objective
    stringrequired
  • expected_evidence
    stringrequired
  • default_frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • system_sources
    string[]required
  • owner
    null | objectrequired
  • owner.id
    integerrequired
  • owner.name
    string | nullrequired
  • procedure
    string | nullrequired
  • state
    stringrequired
    One of: current, overdue, no_evidence, unassigned.
  • due_on
    string | null (date)required
  • days_overdue
    integerrequired
  • evidence_count
    integerrequired
  • last_evidence
    null | objectrequired
  • last_evidence.source
    stringrequired
    One of: system, recorded.
  • last_evidence.kind
    stringrequired
  • last_evidence.title
    stringrequired
  • last_evidence.date
    string (date)required
  • last_evidence.ref_id
    integer | nullrequired
  • last_evidence.href
    string | nullrequired
  • last_evidence.url
    string | nullrequired
  • last_evidence.note
    string | nullrequired
  • last_evidence.id
    integer | nullrequired
  • last_evidence.recorded_by
    null | objectrequired
  • updated_at
    string | null (date-time)required
  • evidence
    object[]required
  • evidence[].source
    stringrequired
    One of: system, recorded.
  • evidence[].kind
    stringrequired
  • evidence[].title
    stringrequired
  • evidence[].date
    string (date)required
  • evidence[].ref_id
    integer | nullrequired
  • evidence[].href
    string | nullrequired
  • evidence[].url
    string | nullrequired
  • evidence[].note
    string | nullrequired
  • evidence[].id
    integer | nullrequired
  • evidence[].recorded_by
    null | objectrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, a restricted grant, wrong company or a token without the required scope
  • 404Unknown objective

Example request

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • objective_key
    stringpathrequired
    Control objective key, e.g. CO-1

Request body

  • control_objective
    objectrequired
  • control_objective.owner_user_id
    integer | nullrequired
  • control_objective.frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • control_objective.procedure
    string | null

Response · 200 · object

  • key
    stringrequired
  • title
    stringrequired
  • objective
    stringrequired
  • expected_evidence
    stringrequired
  • default_frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • frequency
    stringrequired
    One of: monthly, quarterly, semiannual, annual.
  • system_sources
    string[]required
  • owner
    null | objectrequired
  • owner.id
    integerrequired
  • owner.name
    string | nullrequired
  • procedure
    string | nullrequired
  • state
    stringrequired
    One of: current, overdue, no_evidence, unassigned.
  • due_on
    string | null (date)required
  • days_overdue
    integerrequired
  • evidence_count
    integerrequired
  • last_evidence
    null | objectrequired
  • last_evidence.source
    stringrequired
    One of: system, recorded.
  • last_evidence.kind
    stringrequired
  • last_evidence.title
    stringrequired
  • last_evidence.date
    string (date)required
  • last_evidence.ref_id
    integer | nullrequired
  • last_evidence.href
    string | nullrequired
  • last_evidence.url
    string | nullrequired
  • last_evidence.note
    string | nullrequired
  • last_evidence.id
    integer | nullrequired
  • last_evidence.recorded_by
    null | objectrequired
  • updated_at
    string | null (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, a restricted grant or a read-only token
  • 404Unknown objective or owner
  • 422Invalid body or an owner without accounting access

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • evidence
    objectrequired
  • evidence.kind
    stringrequired
    One of: dr_rehearsal, access_review, close_signoff, qualified_signoff, integrity_run, document, other.
  • evidence.title
    stringrequired
  • evidence.url
    string | null (uri)
  • evidence.ref_id
    integer | null
  • evidence.performed_on
    string (date)required
  • evidence.note
    string | null

Response · 201 · object

  • id
    integerrequired
  • objective
    stringrequired
  • kind
    stringrequired
  • title
    stringrequired
  • url
    string | nullrequired
  • ref_id
    integer | nullrequired
  • performed_on
    string (date)required
  • note
    string | nullrequired
  • recorded_by_id
    integerrequired
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid bearer token
  • 403Neither the owner nor a grant manager, a restricted grant or a read-only token
  • 404Unknown objective
  • 409Idempotency-Key reused with a different body or caller, or still running
  • 422Invalid body, a future date, or a ref_id that is not a completed access review or a sign-off of this company

Example request

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

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • search
    stringquery
    Name or email
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • user_id
    integerrequired
  • name
    stringrequired
  • email
    stringrequired
  • is_active
    booleanrequired
  • is_admin
    booleanrequired
  • role
    anyrequired
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
  • effective_role
    anyrequired
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
  • flags
    objectrequired
  • flags.view_ledger
    booleanrequired
  • flags.post_journal
    booleanrequired
  • flags.approve_journal
    booleanrequired
  • flags.manage_coa
    booleanrequired
  • flags.close_period
    booleanrequired
  • flags.ap_enter
    booleanrequired
  • flags.ap_approve
    booleanrequired
  • flags.release_payments
    booleanrequired
  • flags.manage_vendor_banking
    booleanrequired
  • flags.ar_enter
    booleanrequired
  • flags.ar_approve
    booleanrequired
  • flags.payroll_view
    booleanrequired
  • flags.payroll_run
    booleanrequired
  • flags.view_payroll_pii
    booleanrequired
  • flags.bank_reconcile
    booleanrequired
  • flags.manage_integrations
    booleanrequired
  • flags.manage_grants
    booleanrequired
  • flags.job_forecast_edit
    booleanrequired
  • entity_ids
    integer[]required
  • updated_at
    string | null (date-time)required
  • expires_at
    string | null (date-time)required
    End of access; at or after it the grant resolves to no access.
  • certified_at
    string | null (date-time)required
    Last access-review certification.
  • certified_by_id
    integer | nullrequired
  • sod_conflicts
    any[]required
    Segregation 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 token
  • 403No accounting access, missing permission, wrong company, or read-only workspace

Example request

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

v1.0Implemented

Parameters

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

Request body

  • grant
    objectrequired
  • grant.role
    anyrequired
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
  • grant.entity_ids
    integer[]
  • grant.view_ledger
    boolean
  • grant.post_journal
    boolean
  • grant.approve_journal
    boolean
  • grant.manage_coa
    boolean
  • grant.close_period
    boolean
  • grant.ap_enter
    boolean
  • grant.ap_approve
    boolean
  • grant.release_payments
    boolean
  • grant.manage_vendor_banking
    boolean
  • grant.ar_enter
    boolean
  • grant.ar_approve
    boolean
  • grant.payroll_view
    boolean
  • grant.payroll_run
    boolean
  • grant.view_payroll_pii
    boolean
  • grant.bank_reconcile
    boolean
  • grant.manage_integrations
    boolean
  • grant.manage_grants
    boolean
  • grant.job_forecast_edit
    boolean
  • grant.reason
    string
    Why a grant that gains a segregation of duties conflict is needed; audited with the change.
  • grant.expires_at
    string | null (date)
    Last company-local day of access; null clears it. Must be today or later.

Response · 200 · object

  • user_id
    integerrequired
  • name
    stringrequired
  • email
    stringrequired
  • is_active
    booleanrequired
  • is_admin
    booleanrequired
  • role
    anyrequired
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
  • effective_role
    anyrequired
    One of: owner, controller, accountant, ap_clerk, ar_clerk, payroll_admin, project_manager_view, auditor_readonly, none.
  • flags
    objectrequired
  • flags.view_ledger
    booleanrequired
  • flags.post_journal
    booleanrequired
  • flags.approve_journal
    booleanrequired
  • flags.manage_coa
    booleanrequired
  • flags.close_period
    booleanrequired
  • flags.ap_enter
    booleanrequired
  • flags.ap_approve
    booleanrequired
  • flags.release_payments
    booleanrequired
  • flags.manage_vendor_banking
    booleanrequired
  • flags.ar_enter
    booleanrequired
  • flags.ar_approve
    booleanrequired
  • flags.payroll_view
    booleanrequired
  • flags.payroll_run
    booleanrequired
  • flags.view_payroll_pii
    booleanrequired
  • flags.bank_reconcile
    booleanrequired
  • flags.manage_integrations
    booleanrequired
  • flags.manage_grants
    booleanrequired
  • flags.job_forecast_edit
    booleanrequired
  • entity_ids
    integer[]required
  • updated_at
    string | null (date-time)required
  • expires_at
    string | null (date-time)required
    End of access; at or after it the grant resolves to no access.
  • certified_at
    string | null (date-time)required
    Last access-review certification.
  • certified_by_id
    integer | nullrequired
  • sod_conflicts
    any[]required
    Segregation of duties rules this grant's flags combine. One of: ap_full_cycle, payroll_full_cycle, gl_full_cycle, grants_with_payments.
  • warnings
    object[]required
  • warnings[].rule
    stringrequired
  • warnings[].severity
    anyrequired
    One of: warn, block.
  • warnings[].flags
    string[]required
  • warnings[].risk
    stringrequired

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Request body

  • access_review
    objectrequired
  • access_review.decisions
    object[]required
  • access_review.decisions[].user_id
    integerrequired
  • access_review.decisions[].decision
    anyrequired
    One of: keep, revoke.
  • access_review.note
    string

Response · 200 · object

  • kept
    integerrequired
  • revoked
    integerrequired
  • certified_at
    string (date-time)required

Errors

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

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • rules
    object[]required
  • rules[].key
    stringrequired
  • rules[].name
    stringrequired
  • rules[].duties
    string[]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.
  • rules[].severity
    stringrequired
    One of: warn, block.
  • rules[].enabled
    booleanrequired
  • rules[].risk
    stringrequired
  • rules[].source
    stringrequired
    One of: default, customized, custom.
  • rules[].updated_at
    string | null (date-time)required
  • rules[].updated_by_id
    integer | nullrequired
  • totals
    objectrequired
  • totals.members
    integerrequired
  • totals.with_conflicts
    integerrequired
  • totals.block
    integerrequired
  • totals.via_delegation
    integerrequired
  • members
    object[]required
  • members[].user
    objectrequired
  • members[].kind
    stringrequired
    One of: grant, implicit_owner.
  • members[].role
    stringrequired
  • members[].entity_ids
    integer[]required
  • members[].project_scoped
    booleanrequired
  • members[].duties
    object[]required
  • members[].conflicts
    object[]required
  • members[].evidence
    objectrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, a restricted grant, wrong company or a token without the required scope

Example request

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

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • key
    stringrequired
  • name
    stringrequired
  • duties
    string[]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.
  • severity
    stringrequired
    One of: warn, block.
  • enabled
    booleanrequired
  • risk
    stringrequired
  • source
    stringrequired
    One of: default, customized, custom.
  • updated_at
    string | null (date-time)required
  • updated_by_id
    integer | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, a restricted grant, wrong company or a token without the required scope

Example request

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • rule_key
    stringpathrequired
    Rule key (lowercase letters, digits and underscores)

Request body

  • sod_rule
    objectrequired
  • sod_rule.name
    string
  • sod_rule.duties
    string[]
    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.severity
    stringrequired
    One of: warn, block.
  • sod_rule.enabled
    booleanrequired
  • sod_rule.risk
    string
  • sod_rule.reason
    stringrequired

Response · 200 · object

  • key
    stringrequired
  • name
    stringrequired
  • duties
    string[]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.
  • severity
    stringrequired
    One of: warn, block.
  • enabled
    booleanrequired
  • risk
    stringrequired
  • source
    stringrequired
    One of: default, customized, custom.
  • updated_at
    string | null (date-time)required
  • updated_by_id
    integer | nullrequired
  • current_holders
    object[]required
  • current_holders[].user_id
    integerrequired
  • current_holders[].name
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403Missing manage_grants, a restricted grant, step-up required or a read-only token
  • 404Malformed rule key
  • 422Invalid body, changed duties on a built-in rule, or a new rule without duties, name or risk

Example request

Generated from the contractcurl
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"
  }
}'

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file