Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · Shared services

Shared accounting services

Attachment downloads, data lifecycle (exports, retention, holds, offboarding) and encryption key rotation used by every Accounting app. 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 Shared accounting services guide for the workflow.

28 operationsCompany moduleAll Accounting apps →
  1. GET /rest/v1.0/companies/{company_id}/accounting/attachments/{id}Download an attachment
  2. GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/exportsLatest 50 full export requests; accounting:read and unrestricted owner plus step-up
  3. POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/exportsQueue full extract; accounting:write and unrestricted owner plus step-up
  4. GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/exports/{id}Export status, checksummed manifest and user-bound 15-minute download link
  5. GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/exports/{id}/downloadStream signed ZIP64 archive; rechecks current owner access, MFA/step-up and authenticated recipient
  6. POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/holdsRecord an outstanding filing or legal hold for employee/vendor
  7. DELETE /rest/v1.0/companies/{company_id}/accounting/lifecycle/holds/{id}Release an explicit retention hold with owner step-up
  8. GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/offboardingSuper-admin retrieves retained offboarding certificate
  9. POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/offboardingSuper-admin irreversibly deletes tenant accounting after durable/fresh export verification
  10. GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/retentionExplicit policy or disabled defaults
  11. PUT /rest/v1.0/companies/{company_id}/accounting/lifecycle/retentionSet the company legal hold flag; request subject retention periods through the register
  12. POST /rest/v1.0/companies/{company_id}/accounting/pii_rotationRotate vendor and bank PII encryption
  13. GET /rest/v1.0/companies/{company_id}/accounting/privacy/holdsList legal holds
  14. POST /rest/v1.0/companies/{company_id}/accounting/privacy/holdsPlace a legal hold
  15. POST /rest/v1.0/companies/{company_id}/accounting/privacy/holds/{id}/releaseRelease a legal hold
  16. GET /rest/v1.0/companies/{company_id}/accounting/privacy/pii_inventoryPII inventory
  17. GET /rest/v1.0/companies/{company_id}/accounting/privacy/requestsList data subject requests
  18. POST /rest/v1.0/companies/{company_id}/accounting/privacy/requestsLog a data subject request
  19. GET /rest/v1.0/companies/{company_id}/accounting/privacy/requests/{id}Data subject request
  20. POST /rest/v1.0/companies/{company_id}/accounting/privacy/requests/{id}/decisionComplete or reject a data subject request
  21. GET /rest/v1.0/companies/{company_id}/accounting/privacy/retention_registerRetention register
  22. POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_register/changesRequest a retention period change (maker)
  23. POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_register/changes/{id}/decisionApprove or reject a retention change (checker)
  24. GET /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runsList retention runs
  25. POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runsPreview retention (dry run)
  26. GET /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runs/{id}Retention run with its evidence report
  27. POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runs/{id}/executeExecute a retention preview
  28. POST /rest/v1.0/companies/{company_id}/accounting/privacy/subject_exportsExport the personal data held about a subject

Accounting / Shared accounting services

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

Download an attachment

Returns the stored bytes as application/octet-stream with Content-Disposition: attachment (never rendered inline). Access is re-checked against the parent record. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace
  • 404Not found in this company

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/exports

Latest 50 full export requests; accounting:read and unrestricted owner plus step-up

List is capped to the latest 50 requests; extract contents have no row cap.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • id
    string (uuid)required
  • job_id
    integerrequired
  • status
    anyrequired
    One of: queued, processing, complete, failed.
  • sha256
    string | nullrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/exports

Queue full extract; accounting:write and unrestricted owner plus step-up

Supports Idempotency-Key; retries with the same key replay the original result.

v1.0Implemented

Parameters

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

Response · 202 · object

  • id
    string (uuid)required
  • job_id
    integerrequired
  • status
    anyrequired
    One of: queued, processing, complete, failed.
  • sha256
    string | nullrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/lifecycle/exports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Accounting / Shared accounting services

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

Export status, checksummed manifest and user-bound 15-minute download link

Requires accounting:read token scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    string (uuid)pathrequired

Response · 200 · object

  • id
    string (uuid)required
  • job_id
    integerrequired
  • status
    anyrequired
    One of: queued, processing, complete, failed.
  • sha256
    string | nullrequired
  • created_at
    string (date-time)required
  • completed_at
    string | null (date-time)required
  • manifest
    object | nullrequired
  • manifest.version
    anyrequired
  • manifest.company_id
    integerrequired
  • manifest.export_id
    string (uuid)required
  • manifest.snapshot
    stringrequired
  • manifest.created_at
    string (date-time)required
  • manifest.encoding
    stringrequired
  • manifest.attachments
    stringrequired
  • manifest.tables
    object[]required
  • download_url
    string | nullrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/exports/{id}/download

Stream signed ZIP64 archive; rechecks current owner access, MFA/step-up and authenticated recipient

Requires accounting:read token scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    string (uuid)pathrequired
  • expires
    integerqueryrequired
  • signature
    stringqueryrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Authentication or step-up required
  • 403Expired, altered or wrong-user signature/access revoked
  • 404Artifact missing

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/holds

Record an outstanding filing or legal hold for employee/vendor

Requires accounting:write token scope. Supports Idempotency-Key; retries with the same key replay the original result.

v1.0Implemented

Parameters

  • 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

  • retention_hold
    objectrequired
  • retention_hold.subject_type
    anyrequired
    One of: employee, vendor.
  • retention_hold.subject_id
    integerrequired
  • retention_hold.reason
    stringrequired

Response · 201 · object

  • id
    integerrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/lifecycle/holds" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "retention_hold": {
    "subject_type": "employee",
    "subject_id": 1,
    "reason": "string"
  }
}'

Accounting / Shared accounting services

DELETE /rest/v1.0/companies/{company_id}/accounting/lifecycle/holds/{id}

Release an explicit retention hold with owner step-up

Requires accounting:write token scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/offboarding

Super-admin retrieves retained offboarding certificate

Requires accounting:read token scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

  • certificate
    object | nullrequired
  • certificate.version
    anyrequired
  • certificate.company_id
    integerrequired
  • certificate.export_id
    string (uuid)required
  • certificate.export_sha256
    stringrequired
  • certificate.export_completed_at
    string (date-time)required
  • certificate.actor_id
    integerrequired
  • certificate.destroyed_at
    string (date-time)required
  • certificate.counts
    objectrequired
  • certificate.scope
    stringrequired
  • certificate.guards_restored
    anyrequired
  • certificate.certificate_sha256
    stringrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/lifecycle/offboarding

Super-admin irreversibly deletes tenant accounting after durable/fresh export verification

Requires accounting:write token scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • offboarding
    objectrequired
  • offboarding.export_id
    string (uuid)required
  • offboarding.confirm
    stringrequired
  • offboarding.acknowledge_irreversible
    anyrequired

Response · 200 · object

  • certificate
    objectrequired
  • certificate.version
    anyrequired
  • certificate.company_id
    integerrequired
  • certificate.export_id
    string (uuid)required
  • certificate.export_sha256
    stringrequired
  • certificate.export_completed_at
    string (date-time)required
  • certificate.actor_id
    integerrequired
  • certificate.destroyed_at
    string (date-time)required
  • certificate.counts
    objectrequired
  • certificate.scope
    stringrequired
  • certificate.guards_restored
    anyrequired
  • certificate.certificate_sha256
    stringrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/lifecycle/offboarding" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "offboarding": {
    "export_id": "00000000-0000-4000-8000-000000000000",
    "confirm": "string",
    "acknowledge_irreversible": null
  }
}'

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/lifecycle/retention

Explicit policy or disabled defaults

The approved employee SSN (employee_days) and vendor TIN (vendor_days) retention periods from the retention register (null when none is approved) and the company legal hold flag. Requires accounting:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

  • employee_days
    integer | nullrequired
  • vendor_days
    integer | nullrequired
  • legal_hold
    booleanrequired
  • reason
    string | nullrequired

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

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

Accounting / Shared accounting services

PUT /rest/v1.0/companies/{company_id}/accounting/lifecycle/retention

Set the company legal hold flag; request subject retention periods through the register

legal_hold applies at once (a company-wide hold blocks every retention purge). A non-null employee_days or vendor_days different from the approved period files maker-checker change requests in the retention register (employee_ssn and employee_bank, or vendor_tin and vendor_bank) that another unrestricted owner must approve; a period below a class's hard floor (1461 days for SSN/TIN, 730 for bank details) is 422. Unrestricted owner, view_payroll_pii and step-up. Requires accounting:write.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Request body

  • retention_policy
    objectrequired
  • retention_policy.employee_days
    integer | nullrequired
  • retention_policy.vendor_days
    integer | nullrequired
  • retention_policy.legal_hold
    booleanrequired
  • retention_policy.reason
    stringrequired

Response · 200 · object

  • employee_days
    integer | nullrequired
  • vendor_days
    integer | nullrequired
  • legal_hold
    booleanrequired
  • reason
    stringrequired
  • pending_change_ids
    integer[]required

Errors

  • 401Authentication/MFA/step-up required
  • 403Wrong tenant, insufficient token scope or unrestricted owner/super-admin access required
  • 404Not found
  • 409Proof stale/incomplete, retention hold, offboarded company, or unsupported schema
  • 422Invalid request or explicit confirmation

Example request

Generated from the contractcurl
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/lifecycle/retention" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "retention_policy": {
    "employee_days": 1,
    "vendor_days": 1,
    "legal_hold": true,
    "reason": "string"
  }
}'

Accounting / Shared accounting services

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

Rotate vendor and bank PII encryption

Data migration and key rotation: re-encrypts vendor/customer TIN and bank numbers (live and pending) and company bank account and routing numbers still in the legacy format, under an older key, or written before row binding (empty AAD), with the current key and bound to their row (company, row, field), so a value copied to another row no longer decrypts. A rewritten pending change gets a new change_hash. Returns counts only. Needs manage_vendor_banking; audited. Requires the accounting:write scope. Also rewrites AP payment release snapshots and vendor ACH prenote records (profile binding), vendor and unmatched NOC corrections, ERP connection OAuth tokens and webhook signing secrets. remaining counts the company's rows, payroll included, still holding a value under an older key id or the legacy format: drop an old key id only once it is 0.

v1.0Implemented

Parameters

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

Response · 200 · object

  • rotated
    integerrequired
  • remaining
    integerrequired
    Rows still under an older key id or the legacy format, company-wide.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing manage_vendor_banking, wrong company, or read-only workspace

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/privacy/holds

List legal holds

Every hold, newest first (500), active and released. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: company, entity, project, vendor, employee.
  • subject_id
    integerrequired
  • matter
    string | nullrequired
  • reason
    stringrequired
  • placed_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • active
    booleanrequired
  • released_at
    string | null (date-time)required
  • released_by_id
    integer | nullrequired
  • release_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/holds

Place a legal hold

Places a hold on the company, an entity, a project, a vendor or an employee. Effective at once: retention skips every record it covers (an employee: their pay group's or a check's employer entity, projects they logged time on; a vendor: entities of its bills, payments and 1099 filings, projects on its bill lines). Any active hold also suspends outbox and job-error redaction. Audited. Honors Idempotency-Key. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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
  • 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

  • hold
    objectrequired
  • hold.subject_type
    anyrequired
    One of: company, entity, project, vendor, employee.
  • hold.subject_id
    integer
    Required except for a company hold
  • hold.matter
    string
    Matter or case reference (no personal data)
  • hold.reason
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: company, entity, project, vendor, employee.
  • subject_id
    integerrequired
  • matter
    string | nullrequired
  • reason
    stringrequired
  • placed_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • active
    booleanrequired
  • released_at
    string | null (date-time)required
  • released_by_id
    integer | nullrequired
  • release_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404Subject not found in this company
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/holds/{id}/release

Release a legal hold

Releases an active hold with a reason; audited. 409 when already released. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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

Request body

  • release
    objectrequired
  • release.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: company, entity, project, vendor, employee.
  • subject_id
    integerrequired
  • matter
    string | nullrequired
  • reason
    stringrequired
  • placed_by_id
    integer | nullrequired
  • created_at
    string (date-time)required
  • active
    booleanrequired
  • released_at
    string | null (date-time)required
  • released_by_id
    integer | nullrequired
  • release_reason
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such hold
  • 409Already released
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/privacy/pii_inventory

PII inventory

Every accounting column holding personal or sensitive identifying data: category, subject, protection (sealed, masked, plain, hashed) and governing retention class, plus pattern-matching columns classified as not personal data with the reason. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • columns
    object[]required
  • columns[].table
    stringrequired
  • columns[].column
    stringrequired
  • columns[].category
    stringrequired
  • columns[].subject
    stringrequired
  • columns[].protection
    anyrequired
    One of: sealed, masked, plain, hashed.
  • columns[].record_class
    string | nullrequired
  • columns[].note
    stringrequired
  • not_pii
    object[]required
  • not_pii[].column
    stringrequired
  • not_pii[].reason
    stringrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/privacy/requests

List data subject requests

Newest first (500). Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: employee, vendor.
  • subject_id
    integerrequired
  • kind
    anyrequired
    One of: access, rectification, erasure.
  • status
    anyrequired
    One of: open, completed, rejected.
  • received_on
    string (date)required
  • due_on
    string (date)required
  • description
    stringrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired
  • outcome
    anyrequired
    Decision record: for an erasure, what was erased and what was retained and why
  • assessment
    array | null
    Detail only, while open
  • assessment[].data
    stringrequired
  • assessment[].disposition
    anyrequired
    One of: erasable, retained, already_minimized, erased.
  • assessment[].reason
    stringrequired
  • assessment[].record_class
    string | nullrequired
  • assessment[].retain_until
    string | null

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/requests

Log a data subject request

Access, rectification or erasure about an employee or vendor contact; due 45 days after receipt (a proposal for counsel). Audited. Honors Idempotency-Key. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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
  • 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

  • privacy_request
    objectrequired
  • privacy_request.subject_type
    anyrequired
    One of: employee, vendor.
  • privacy_request.subject_id
    integerrequired
  • privacy_request.kind
    anyrequired
    One of: access, rectification, erasure.
  • privacy_request.received_on
    string (date)required
  • privacy_request.description
    stringrequired
    What was asked, without identifiers

Response · 201 · object

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: employee, vendor.
  • subject_id
    integerrequired
  • kind
    anyrequired
    One of: access, rectification, erasure.
  • status
    anyrequired
    One of: open, completed, rejected.
  • received_on
    string (date)required
  • due_on
    string (date)required
  • description
    stringrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired
  • outcome
    anyrequired
    Decision record: for an erasure, what was erased and what was retained and why
  • assessment
    array | null
    Detail only, while open
  • assessment[].data
    stringrequired
  • assessment[].disposition
    anyrequired
    One of: erasable, retained, already_minimized, erased.
  • assessment[].reason
    stringrequired
  • assessment[].record_class
    string | nullrequired
  • assessment[].retain_until
    string | null

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such subject
  • 422Invalid body or a period below the class's hard floor

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/privacy/requests" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "privacy_request": {
    "subject_type": "employee",
    "subject_id": 1,
    "kind": "access",
    "received_on": "2026-11-01",
    "description": "string"
  }
}'

Accounting / Shared accounting services

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

Data subject request

With, while open, the live assessment of each data item: erasable, retained (with the reason: retention period, ledger integrity, legal hold, open item) or already minimized. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: employee, vendor.
  • subject_id
    integerrequired
  • kind
    anyrequired
    One of: access, rectification, erasure.
  • status
    anyrequired
    One of: open, completed, rejected.
  • received_on
    string (date)required
  • due_on
    string (date)required
  • description
    stringrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired
  • outcome
    anyrequired
    Decision record: for an erasure, what was erased and what was retained and why
  • assessment
    array | null
    Detail only, while open
  • assessment[].data
    stringrequired
  • assessment[].disposition
    anyrequired
    One of: erasable, retained, already_minimized, erased.
  • assessment[].reason
    stringrequired
  • assessment[].record_class
    string | nullrequired
  • assessment[].retain_until
    string | null

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such request

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/requests/{id}/decision

Complete or reject a data subject request

A different owner than the one who logged it. Access completes only after a subject export since the request was logged (409). Erasure clears exactly what the assessment marks erasable (sealed values past their approved period, optional vendor contact fields) and records what was retained and why; financial records, payroll records and the audit trail are never erased. Audited. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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

Request body

  • decision
    objectrequired
  • decision.decision
    anyrequired
    One of: complete, reject.
  • decision.note
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • subject_type
    anyrequired
    One of: employee, vendor.
  • subject_id
    integerrequired
  • kind
    anyrequired
    One of: access, rectification, erasure.
  • status
    anyrequired
    One of: open, completed, rejected.
  • received_on
    string (date)required
  • due_on
    string (date)required
  • description
    stringrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired
  • outcome
    anyrequired
    Decision record: for an erasure, what was erased and what was retained and why
  • assessment
    array | null
    Detail only, while open
  • assessment[].data
    stringrequired
  • assessment[].disposition
    anyrequired
    One of: erasable, retained, already_minimized, erased.
  • assessment[].reason
    stringrequired
  • assessment[].record_class
    string | nullrequired
  • assessment[].retain_until
    string | null

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such request
  • 409Already decided or export missing
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/privacy/retention_register

Retention register

Every record class with its hard floor, proposed period and basis (proposals, not in force), the approved rule in force and any pending change, plus the latest 200 change requests. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • disclaimer
    stringrequired
  • classes
    object[]required
  • classes[].record_class
    stringrequired
    One of: ledger, ap_ar_documents, payroll_records, employee_ssn, employee_bank, vendor_tin, vendor_bank, attachments, audit_logs, outbox_payloads, job_errors, portal_sessions.
  • classes[].label
    stringrequired
  • classes[].action
    anyrequired
    One of: retain, minimize, redact, delete.
  • classes[].automated
    booleanrequired
  • classes[].floor_days
    integerrequired
  • classes[].proposed_days
    integerrequired
  • classes[].from
    stringrequired
  • classes[].proposed_jurisdiction
    stringrequired
  • classes[].proposed_basis
    stringrequired
  • classes[].covers
    string[]required
  • classes[].in_force
    null | objectrequired
  • classes[].pending_change
    null | objectrequired
  • changes
    object[]required
  • changes[].id
    integerrequired
  • changes[].record_class
    stringrequired
    One of: ledger, ap_ar_documents, payroll_records, employee_ssn, employee_bank, vendor_tin, vendor_bank, attachments, audit_logs, outbox_payloads, job_errors, portal_sessions.
  • changes[].retention_days
    integerrequired
  • changes[].jurisdiction
    stringrequired
  • changes[].basis
    stringrequired
  • changes[].reason
    stringrequired
  • changes[].status
    anyrequired
    One of: pending, approved, rejected.
  • changes[].previous_days
    integer | nullrequired
  • changes[].requested_by_id
    integerrequired
  • changes[].requested_at
    string (date-time)required
  • changes[].decided_by_id
    integer | nullrequired
  • changes[].decided_at
    string | null (date-time)required
  • changes[].decision_note
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_register/changes

Request a retention period change (maker)

Requests a period for a record class. Refused below the class's hard floor (422; the database also refuses it) and while another change for the class is pending (409). Not in force until a different owner approves it. Audited. Honors Idempotency-Key. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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
  • 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

  • change
    objectrequired
  • change.record_class
    stringrequired
    One of: ledger, ap_ar_documents, payroll_records, employee_ssn, employee_bank, vendor_tin, vendor_bank, attachments, audit_logs, outbox_payloads, job_errors, portal_sessions.
  • change.retention_days
    integerrequired
    At least the class's floor_days (422 otherwise)
  • change.jurisdiction
    stringrequired
  • change.basis
    stringrequired
  • change.reason
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • record_class
    stringrequired
    One of: ledger, ap_ar_documents, payroll_records, employee_ssn, employee_bank, vendor_tin, vendor_bank, attachments, audit_logs, outbox_payloads, job_errors, portal_sessions.
  • retention_days
    integerrequired
  • jurisdiction
    stringrequired
  • basis
    stringrequired
  • reason
    stringrequired
  • status
    anyrequired
    One of: pending, approved, rejected.
  • previous_days
    integer | nullrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 409A change for this class is pending
  • 422Invalid body or a period below the class's hard floor

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/privacy/retention_register/changes" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "change": {
    "record_class": "ledger",
    "retention_days": 1,
    "jurisdiction": "string",
    "basis": "string",
    "reason": "string"
  }
}'

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_register/changes/{id}/decision

Approve or reject a retention change (checker)

A different unrestricted owner than the requester approves (the rule takes effect, version + 1) or rejects a pending change; 403 for your own request, 409 once decided. Audited with before and after. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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

Request body

  • decision
    objectrequired
  • decision.decision
    anyrequired
    One of: approve, reject.
  • decision.note
    string

Response · 200 · object

  • id
    integerrequired
  • record_class
    stringrequired
    One of: ledger, ap_ar_documents, payroll_records, employee_ssn, employee_bank, vendor_tin, vendor_bank, attachments, audit_logs, outbox_payloads, job_errors, portal_sessions.
  • retention_days
    integerrequired
  • jurisdiction
    stringrequired
  • basis
    stringrequired
  • reason
    stringrequired
  • status
    anyrequired
    One of: pending, approved, rejected.
  • previous_days
    integer | nullrequired
  • requested_by_id
    integerrequired
  • requested_at
    string (date-time)required
  • decided_by_id
    integer | nullrequired
  • decided_at
    string | null (date-time)required
  • decision_note
    string | nullrequired

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such change
  • 409Already decided
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

GET /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runs

List retention runs

Latest 50 previews and executions with per-class summaries. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • mode
    anyrequired
    One of: preview, execute.
  • trigger
    anyrequired
    One of: manual, scheduled.
  • as_of
    string (date-time)required
  • preview_id
    integer | nullrequired
  • plan_hash
    stringrequired
  • summary
    objectrequired
    Per record class: status (not_in_force, retained, planned), past_period, held, to_apply and, for an execution, applied
  • evidence_sha256
    stringrequired
  • requested_by_id
    integerrequired
  • created_at
    string (date-time)required
  • executed
    boolean | null
    List only: whether a preview was executed
  • evidence
    object
    Detail only. Preview: register, active holds and the per-class plan. Execution: the plan, applied ids per class and whether they match the preview, ledger fingerprint, integrity checks and audit-event count before and after.

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runs

Preview retention (dry run)

Computes and records what retention would change now (or at the end of as_of, not in the future): per class, records past the approved period, those kept by holds and those that would change, with a plan hash. Nothing is changed. Honors Idempotency-Key. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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
  • 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

  • preview
    objectrequired
  • preview.as_of
    string (date)

Response · 201 · object

  • id
    integerrequired
  • mode
    anyrequired
    One of: preview, execute.
  • trigger
    anyrequired
    One of: manual, scheduled.
  • as_of
    string (date-time)required
  • preview_id
    integer | nullrequired
  • plan_hash
    stringrequired
  • summary
    objectrequired
    Per record class: status (not_in_force, retained, planned), past_period, held, to_apply and, for an execution, applied
  • evidence_sha256
    stringrequired
  • requested_by_id
    integerrequired
  • created_at
    string (date-time)required
  • executed
    boolean | null
    List only: whether a preview was executed
  • evidence
    object
    Detail only. Preview: register, active holds and the per-class plan. Execution: the plan, applied ids per class and whether they match the preview, ledger fingerprint, integrity checks and audit-event count before and after.

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

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

Retention run with its evidence report

Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and manage_grants) and step-up: a token needs accounting:step_up. Requires accounting:read.

v1.0Implemented

Parameters

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

Response · 200 · object

  • id
    integerrequired
  • mode
    anyrequired
    One of: preview, execute.
  • trigger
    anyrequired
    One of: manual, scheduled.
  • as_of
    string (date-time)required
  • preview_id
    integer | nullrequired
  • plan_hash
    stringrequired
  • summary
    objectrequired
    Per record class: status (not_in_force, retained, planned), past_period, held, to_apply and, for an execution, applied
  • evidence_sha256
    stringrequired
  • requested_by_id
    integerrequired
  • created_at
    string (date-time)required
  • executed
    boolean | null
    List only: whether a preview was executed
  • evidence
    object
    Detail only. Preview: register, active holds and the per-class plan. Execution: the plan, applied ids per class and whether they match the preview, ledger fingerprint, integrity checks and audit-event count before and after.

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such run

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/retention_runs/{id}/execute

Execute a retention preview

Recomputes the plan at the preview's date; it must hash to the preview (409 otherwise: preview again). Then applies it in batches that re-check eligibility and holds under row locks, and records the execution evidence (applied ids against the plan, ledger fingerprint, integrity checks and audit count before and after). A preview executes once and within 24 hours (409). Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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

Response · 201 · object

  • id
    integerrequired
  • mode
    anyrequired
    One of: preview, execute.
  • trigger
    anyrequired
    One of: manual, scheduled.
  • as_of
    string (date-time)required
  • preview_id
    integer | nullrequired
  • plan_hash
    stringrequired
  • summary
    objectrequired
    Per record class: status (not_in_force, retained, planned), past_period, held, to_apply and, for an execution, applied
  • evidence_sha256
    stringrequired
  • requested_by_id
    integerrequired
  • created_at
    string (date-time)required
  • executed
    boolean | null
    List only: whether a preview was executed
  • evidence
    object
    Detail only. Preview: register, active holds and the per-class plan. Execution: the plan, applied ids per class and whether they match the preview, ledger fingerprint, integrity checks and audit-event count before and after.

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such preview
  • 409Plan changed, preview stale or already executed
  • 422Invalid body or a period below the class's hard floor

Example request

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

Accounting / Shared accounting services

POST /rest/v1.0/companies/{company_id}/accounting/privacy/subject_exports

Export the personal data held about a subject

Employee or vendor contact: identity, contact, bank (masked), payroll or AP history, portal users, the audit trail about them (actions only), active holds covering them and the retention disposition of each data item. reveal=true decrypts sealed SSN/TIN/bank values for this response only (rate limited). Every export is audited with the sections and the reveal flag, never the values. Creates no record. Needs an unrestricted company owner (company-wide access, every flag including view_payroll_pii and 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

Request body

  • subject_export
    objectrequired
  • subject_export.subject_type
    anyrequired
    One of: employee, vendor.
  • subject_export.subject_id
    integerrequired
  • subject_export.reveal
    boolean
  • subject_export.request_id
    integer

Response · 200 · object

  • subject
    objectrequired
  • generated_at
    string (date-time)required
  • revealed
    booleanrequired
  • identity
    object
  • bank
    object
  • deductions
    any[]
  • rate_changes
    any[]
  • pay_checks
    any[]
  • year_to_date_imports
    any[]
  • ach_accounts
    any[]
  • vendor
    object
  • profile
    object | null
  • form_1099_filings
    any[]
  • bills
    any[]
  • payments
    any[]
  • portal_users
    any[]
  • audit_trail
    any[]required
  • legal_holds
    integer[]required
  • retention
    object[]required
  • retention[].data
    stringrequired
  • retention[].disposition
    anyrequired
    One of: erasable, retained, already_minimized, erased.
  • retention[].reason
    stringrequired
  • retention[].record_class
    string | nullrequired
  • retention[].retain_until
    string | null

Errors

  • 401Missing or invalid bearer token, or step-up required for a session
  • 403No owner access, wrong company, token without the required scope, step-up or MFA missing, or maker-checker refused
  • 404No such subject or request
  • 422Invalid body or a period below the class's hard floor
  • 429Export rate limit

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/privacy/subject_exports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject_export": {
    "subject_type": "employee",
    "subject_id": 1
  }
}'

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