Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Approvals

23 endpoints23 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/approval_workflows/approvalsMy approvals: runs waiting on me, decided by me, or submitted by me
  2. POST /rest/v1.0/companies/{company_id}/approval_workflows/approvalsSubmit a record for approval (agents may submit; only people decide)
  3. GET /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}Show a run with tasks and audit trail
  4. POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/cancelWithdraw a pending run (submitter or admin)
  5. POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/commentsComment on a run
  6. POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/decisionApprove or reject (reject needs a comment)
  7. POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/bulk_decisionApprove several runs (per-item results; not every type allows bulk)
  8. GET /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersCost code owners of a project
  9. POST /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersAssign a cost code owner (company admins)
  10. DELETE /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners/{id}Remove a cost code owner
  11. GET /rest/v1.0/companies/{company_id}/approval_workflows/delegationsApproval delegations (own; admins see all)
  12. POST /rest/v1.0/companies/{company_id}/approval_workflows/delegationsDelegate approvals while out of office
  13. DELETE /rest/v1.0/companies/{company_id}/approval_workflows/delegations/{id}Revoke a delegation
  14. GET /rest/v1.0/companies/{company_id}/approval_workflows/object_typesRecord types covered and their mandatory domain controls
  15. GET /rest/v1.0/companies/{company_id}/approval_workflows/policiesList approval policies
  16. POST /rest/v1.0/companies/{company_id}/approval_workflows/policiesCreate an approval policy (company admins)
  17. GET /rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Show an approval policy
  18. PATCH /rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Update an approval policy (bumps version; runs in flight keep their plan)
  19. DELETE /rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Delete an approval policy
  20. GET /rest/v1.0/companies/{company_id}/approval_workflows/policy_templatesStarter policies
  21. POST /rest/v1.0/companies/{company_id}/approval_workflows/policy_templates/{key}/applyCreate a policy from a template (inactive unless activate)
  22. GET /rest/v1.0/companies/{company_id}/approval_workflows/record_statusA record's runs and whether its domain decision may proceed
  23. POST /rest/v1.0/companies/{company_id}/approval_workflows/simulateWho would approve this record? (read-only)
GET /rest/v1.0/companies/{company_id}/approval_workflows/approvals

My approvals: runs waiting on me, decided by me, or submitted by me

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • filter
    stringquery
    One of: pending, decided, submitted.
  • object_type
    stringquery
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • object_type
    stringrequired
  • object_label
    string
  • object_id
    integerrequired
  • project_id
    integer | null
  • policy_id
    integer | null
  • policy_version
    integer | null
  • status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • title
    string | null
  • record_url
    string | null
  • amount
    string | null
    Decimal string with two places
  • facts
    object
  • plan
    object[]
  • submitted_by_id
    integer
  • started_via
    string
    One of: user, automation.
  • source_ref
    string | null
  • round
    integer
  • supersedes_id
    integer | null
  • rejected_reason
    string | null
  • completed_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)
  • tasks
    object[]required
  • tasks[].id
    integerrequired
  • tasks[].seq
    integerrequired
  • tasks[].stage_index
    integer
  • tasks[].stage_key
    string
  • tasks[].stage_name
    stringrequired
  • tasks[].quorum
    integerrequired
  • tasks[].approver_user_id
    integerrequired
  • tasks[].source
    string
  • tasks[].status
    stringrequired
    One of: waiting, pending, approved, rejected, void.
  • tasks[].activated_at
    string (date-time) | null
  • tasks[].due_at
    string (date-time) | null
  • tasks[].reminder_count
    integer
  • tasks[].escalation_level
    integer
  • tasks[].escalated_to_user_ids
    integer[]
  • tasks[].acted_by_id
    integer | null
  • tasks[].acted_as_delegate_of_id
    integer | null
  • tasks[].comment
    string | null
  • tasks[].acted_at
    string (date-time) | null
  • events
    object[]
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integer | null
  • events[].task_id
    integer | null
  • events[].comment
    string | null
  • events[].changes
    any | null
  • events[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals

Submit a record for approval (agents may submit; only people decide)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • object_type
    stringrequired
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • object_id
    integerrequired
  • policy_id
    integer
  • comment
    string

Response · 200 · object

  • status
    stringrequired
    One of: pending, not_required.
  • approval
    object | null
  • approval.id
    integerrequired
  • approval.object_type
    stringrequired
  • approval.object_label
    string
  • approval.object_id
    integerrequired
  • approval.project_id
    integer | null
  • approval.policy_id
    integer | null
  • approval.policy_version
    integer | null
  • approval.status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • approval.title
    string | null
  • approval.record_url
    string | null
  • approval.amount
    string | null
    Decimal string with two places
  • approval.facts
    object
  • approval.plan
    object[]
  • approval.submitted_by_id
    integer
  • approval.started_via
    string
    One of: user, automation.
  • approval.source_ref
    string | null
  • approval.round
    integer
  • approval.supersedes_id
    integer | null
  • approval.rejected_reason
    string | null
  • approval.completed_at
    string (date-time) | null
  • approval.created_at
    string (date-time)
  • approval.updated_at
    string (date-time)
  • approval.tasks
    object[]required
  • approval.events
    object[]

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "object_type": "change_order",
  "object_id": 1
}'
GET /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}

Show a run with tasks and audit trail

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • object_label
    string
  • object_id
    integerrequired
  • project_id
    integer | null
  • policy_id
    integer | null
  • policy_version
    integer | null
  • status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • title
    string | null
  • record_url
    string | null
  • amount
    string | null
    Decimal string with two places
  • facts
    object
  • plan
    object[]
  • submitted_by_id
    integer
  • started_via
    string
    One of: user, automation.
  • source_ref
    string | null
  • round
    integer
  • supersedes_id
    integer | null
  • rejected_reason
    string | null
  • completed_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)
  • tasks
    object[]required
  • tasks[].id
    integerrequired
  • tasks[].seq
    integerrequired
  • tasks[].stage_index
    integer
  • tasks[].stage_key
    string
  • tasks[].stage_name
    stringrequired
  • tasks[].quorum
    integerrequired
  • tasks[].approver_user_id
    integerrequired
  • tasks[].source
    string
  • tasks[].status
    stringrequired
    One of: waiting, pending, approved, rejected, void.
  • tasks[].activated_at
    string (date-time) | null
  • tasks[].due_at
    string (date-time) | null
  • tasks[].reminder_count
    integer
  • tasks[].escalation_level
    integer
  • tasks[].escalated_to_user_ids
    integer[]
  • tasks[].acted_by_id
    integer | null
  • tasks[].acted_as_delegate_of_id
    integer | null
  • tasks[].comment
    string | null
  • tasks[].acted_at
    string (date-time) | null
  • events
    object[]
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integer | null
  • events[].task_id
    integer | null
  • events[].comment
    string | null
  • events[].changes
    any | null
  • events[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/cancel

Withdraw a pending run (submitter or admin)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • reason
    string

Response · 200 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • object_label
    string
  • object_id
    integerrequired
  • project_id
    integer | null
  • policy_id
    integer | null
  • policy_version
    integer | null
  • status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • title
    string | null
  • record_url
    string | null
  • amount
    string | null
    Decimal string with two places
  • facts
    object
  • plan
    object[]
  • submitted_by_id
    integer
  • started_via
    string
    One of: user, automation.
  • source_ref
    string | null
  • round
    integer
  • supersedes_id
    integer | null
  • rejected_reason
    string | null
  • completed_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)
  • tasks
    object[]required
  • tasks[].id
    integerrequired
  • tasks[].seq
    integerrequired
  • tasks[].stage_index
    integer
  • tasks[].stage_key
    string
  • tasks[].stage_name
    stringrequired
  • tasks[].quorum
    integerrequired
  • tasks[].approver_user_id
    integerrequired
  • tasks[].source
    string
  • tasks[].status
    stringrequired
    One of: waiting, pending, approved, rejected, void.
  • tasks[].activated_at
    string (date-time) | null
  • tasks[].due_at
    string (date-time) | null
  • tasks[].reminder_count
    integer
  • tasks[].escalation_level
    integer
  • tasks[].escalated_to_user_ids
    integer[]
  • tasks[].acted_by_id
    integer | null
  • tasks[].acted_as_delegate_of_id
    integer | null
  • tasks[].comment
    string | null
  • tasks[].acted_at
    string (date-time) | null
  • events
    object[]
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integer | null
  • events[].task_id
    integer | null
  • events[].comment
    string | null
  • events[].changes
    any | null
  • events[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals/1/cancel" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string"
}'
POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/comments

Comment on a run

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • comment
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • object_label
    string
  • object_id
    integerrequired
  • project_id
    integer | null
  • policy_id
    integer | null
  • policy_version
    integer | null
  • status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • title
    string | null
  • record_url
    string | null
  • amount
    string | null
    Decimal string with two places
  • facts
    object
  • plan
    object[]
  • submitted_by_id
    integer
  • started_via
    string
    One of: user, automation.
  • source_ref
    string | null
  • round
    integer
  • supersedes_id
    integer | null
  • rejected_reason
    string | null
  • completed_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)
  • tasks
    object[]required
  • tasks[].id
    integerrequired
  • tasks[].seq
    integerrequired
  • tasks[].stage_index
    integer
  • tasks[].stage_key
    string
  • tasks[].stage_name
    stringrequired
  • tasks[].quorum
    integerrequired
  • tasks[].approver_user_id
    integerrequired
  • tasks[].source
    string
  • tasks[].status
    stringrequired
    One of: waiting, pending, approved, rejected, void.
  • tasks[].activated_at
    string (date-time) | null
  • tasks[].due_at
    string (date-time) | null
  • tasks[].reminder_count
    integer
  • tasks[].escalation_level
    integer
  • tasks[].escalated_to_user_ids
    integer[]
  • tasks[].acted_by_id
    integer | null
  • tasks[].acted_as_delegate_of_id
    integer | null
  • tasks[].comment
    string | null
  • tasks[].acted_at
    string (date-time) | null
  • events
    object[]
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integer | null
  • events[].task_id
    integer | null
  • events[].comment
    string | null
  • events[].changes
    any | null
  • events[].created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals/1/comments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "comment": "string"
}'
POST /rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/decision

Approve or reject (reject needs a comment)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • decision
    stringrequired
    One of: approve, reject.
  • comment
    string

Response · 200 · object

  • outcome
    stringrequired
    One of: recorded, approved, rejected.
  • approval
    objectrequired
  • approval.id
    integerrequired
  • approval.object_type
    stringrequired
  • approval.object_label
    string
  • approval.object_id
    integerrequired
  • approval.project_id
    integer | null
  • approval.policy_id
    integer | null
  • approval.policy_version
    integer | null
  • approval.status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • approval.title
    string | null
  • approval.record_url
    string | null
  • approval.amount
    string | null
    Decimal string with two places
  • approval.facts
    object
  • approval.plan
    object[]
  • approval.submitted_by_id
    integer
  • approval.started_via
    string
    One of: user, automation.
  • approval.source_ref
    string | null
  • approval.round
    integer
  • approval.supersedes_id
    integer | null
  • approval.rejected_reason
    string | null
  • approval.completed_at
    string (date-time) | null
  • approval.created_at
    string (date-time)
  • approval.updated_at
    string (date-time)
  • approval.tasks
    object[]required
  • approval.events
    object[]

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

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

Approve several runs (per-item results; not every type allows bulk)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • instance_ids
    integer[]required
  • comment
    string

Response · 200 · object

  • results
    object[]
  • results[].instance_id
    integer
  • results[].ok
    boolean
  • results[].outcome
    string
  • results[].error
    string

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/approvals/bulk_decision" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "instance_ids": []
}'
GET /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners

Cost code owners of a project

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • project_id
    integerqueryrequired

Response · 200 · object[]

  • id
    integer
  • project_id
    integer
  • cost_code_id
    integer
  • user_id
    integer
  • created_by_id
    integer
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/cost_code_owners" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners

Assign a cost code owner (company admins)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_id
    integerrequired
  • cost_code_id
    integerrequired
  • user_id
    integerrequired

Response · 201 · object

  • id
    integer
  • project_id
    integer
  • cost_code_id
    integer
  • user_id
    integer
  • created_by_id
    integer
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/cost_code_owners" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 1,
  "cost_code_id": 1,
  "user_id": 1
}'
DELETE /rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners/{id}

Remove a cost code owner

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/cost_code_owners/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/approval_workflows/delegations

Approval delegations (own; admins see all)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • from_user_id
    integerrequired
  • to_user_id
    integerrequired
  • object_types
    string[]
  • starts_at
    string (date-time)
  • ends_at
    string (date-time)
  • reason
    string
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/delegations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/delegations

Delegate approvals while out of office

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • from_user_id
    integer
  • to_user_id
    integerrequired
  • object_types
    string[]
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • starts_at
    string (date-time)required
  • ends_at
    string (date-time)required
  • reason
    stringrequired

Response · 201 · object

  • id
    integerrequired
  • from_user_id
    integerrequired
  • to_user_id
    integerrequired
  • object_types
    string[]
  • starts_at
    string (date-time)
  • ends_at
    string (date-time)
  • reason
    string
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/delegations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "to_user_id": 1,
  "starts_at": "2026-11-01T12:00:00Z",
  "ends_at": "2026-11-01T12:00:00Z",
  "reason": "string"
}'
DELETE /rest/v1.0/companies/{company_id}/approval_workflows/delegations/{id}

Revoke a delegation

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 200 · object

  • id
    integerrequired
  • from_user_id
    integerrequired
  • to_user_id
    integerrequired
  • object_types
    string[]
  • starts_at
    string (date-time)
  • ends_at
    string (date-time)
  • reason
    string
  • created_by_id
    integer
  • revoked_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/delegations/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/approval_workflows/object_types

Record types covered and their mandatory domain controls

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • object_type
    string
  • label
    string
  • bulk_approve
    boolean
  • guards
    string[]

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/object_types" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/approval_workflows/policies

List approval policies

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • object_type
    stringquery
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • project_id
    stringquery
    A project id, or `company` for company-wide policies only

Response · 200 · object[]

  • id
    integerrequired
  • object_type
    stringrequired
  • project_id
    integer | null
  • name
    stringrequired
  • description
    string | null
  • priority
    integer
  • is_active
    booleanrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean
  • version
    integerrequired
  • template_key
    string | null
  • created_by_id
    integer
  • updated_by_id
    integer
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policies" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/policies

Create an approval policy (company admins)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • approval_policy
    objectrequired
  • approval_policy.object_type
    string
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • approval_policy.project_id
    integer | null
  • approval_policy.name
    string
  • approval_policy.description
    string | null
  • approval_policy.priority
    integer
  • approval_policy.is_active
    boolean
  • approval_policy.conditions
    object[]
  • approval_policy.conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • approval_policy.conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • approval_policy.conditions[].value
    number | string | (number | string)[]required
  • approval_policy.stages
    object[]
  • approval_policy.stages[].key
    stringrequired
  • approval_policy.stages[].name
    stringrequired
  • approval_policy.stages[].approvers
    object[]required
  • approval_policy.stages[].approvers[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • approval_policy.stages[].approvers[].user_id
    integer
  • approval_policy.stages[].approvers[].role
    string
  • approval_policy.stages[].approvers[].template_id
    integer
  • approval_policy.stages[].approvers[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • approval_policy.stages[].quorum
    object
  • approval_policy.stages[].quorum.type
    stringrequired
    One of: any, all, n.
  • approval_policy.stages[].quorum.n
    integer
  • approval_policy.stages[].parallel_with_previous
    boolean
  • approval_policy.stages[].conditions
    object[]
  • approval_policy.stages[].conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • approval_policy.stages[].conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • approval_policy.stages[].conditions[].value
    number | string | (number | string)[]required
  • approval_policy.stages[].sla_hours
    number | null
  • approval_policy.stages[].reminder_every_hours
    number | null
  • approval_policy.stages[].escalate_after_hours
    number | null
  • approval_policy.stages[].escalate_to
    object[]
  • approval_policy.stages[].escalate_to[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • approval_policy.stages[].escalate_to[].user_id
    integer
  • approval_policy.stages[].escalate_to[].role
    string
  • approval_policy.stages[].escalate_to[].template_id
    integer
  • approval_policy.stages[].escalate_to[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • approval_policy.reapproval
    object
  • approval_policy.reapproval.percent
    number | null
  • approval_policy.reapproval.amount
    number | null
  • approval_policy.reapproval.on_decrease
    boolean
  • approval_policy.template_key
    string | null

Response · 201 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • project_id
    integer | null
  • name
    stringrequired
  • description
    string | null
  • priority
    integer
  • is_active
    booleanrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean
  • version
    integerrequired
  • template_key
    string | null
  • created_by_id
    integer
  • updated_by_id
    integer
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

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

Show an approval policy

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • project_id
    integer | null
  • name
    stringrequired
  • description
    string | null
  • priority
    integer
  • is_active
    booleanrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean
  • version
    integerrequired
  • template_key
    string | null
  • created_by_id
    integer
  • updated_by_id
    integer
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}

Update an approval policy (bumps version; runs in flight keep their plan)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • approval_policy
    objectrequired
  • approval_policy.object_type
    string
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • approval_policy.project_id
    integer | null
  • approval_policy.name
    string
  • approval_policy.description
    string | null
  • approval_policy.priority
    integer
  • approval_policy.is_active
    boolean
  • approval_policy.conditions
    object[]
  • approval_policy.conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • approval_policy.conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • approval_policy.conditions[].value
    number | string | (number | string)[]required
  • approval_policy.stages
    object[]
  • approval_policy.stages[].key
    stringrequired
  • approval_policy.stages[].name
    stringrequired
  • approval_policy.stages[].approvers
    object[]required
  • approval_policy.stages[].approvers[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • approval_policy.stages[].approvers[].user_id
    integer
  • approval_policy.stages[].approvers[].role
    string
  • approval_policy.stages[].approvers[].template_id
    integer
  • approval_policy.stages[].approvers[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • approval_policy.stages[].quorum
    object
  • approval_policy.stages[].quorum.type
    stringrequired
    One of: any, all, n.
  • approval_policy.stages[].quorum.n
    integer
  • approval_policy.stages[].parallel_with_previous
    boolean
  • approval_policy.stages[].conditions
    object[]
  • approval_policy.stages[].conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • approval_policy.stages[].conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • approval_policy.stages[].conditions[].value
    number | string | (number | string)[]required
  • approval_policy.stages[].sla_hours
    number | null
  • approval_policy.stages[].reminder_every_hours
    number | null
  • approval_policy.stages[].escalate_after_hours
    number | null
  • approval_policy.stages[].escalate_to
    object[]
  • approval_policy.stages[].escalate_to[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • approval_policy.stages[].escalate_to[].user_id
    integer
  • approval_policy.stages[].escalate_to[].role
    string
  • approval_policy.stages[].escalate_to[].template_id
    integer
  • approval_policy.stages[].escalate_to[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • approval_policy.reapproval
    object
  • approval_policy.reapproval.percent
    number | null
  • approval_policy.reapproval.amount
    number | null
  • approval_policy.reapproval.on_decrease
    boolean
  • approval_policy.template_key
    string | null

Response · 200 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • project_id
    integer | null
  • name
    stringrequired
  • description
    string | null
  • priority
    integer
  • is_active
    booleanrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean
  • version
    integerrequired
  • template_key
    string | null
  • created_by_id
    integer
  • updated_by_id
    integer
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "approval_policy": {}
}'
DELETE /rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}

Delete an approval policy

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/approval_workflows/policy_templates

Starter policies

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • key
    stringrequired
  • name
    stringrequired
  • description
    string
  • object_type
    stringrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policy_templates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/policy_templates/{key}/apply

Create a policy from a template (inactive unless activate)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • key
    stringpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • activate
    boolean
  • project_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • object_type
    stringrequired
  • project_id
    integer | null
  • name
    stringrequired
  • description
    string | null
  • priority
    integer
  • is_active
    booleanrequired
  • conditions
    object[]
  • conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • conditions[].value
    number | string | (number | string)[]required
  • stages
    object[]required
  • stages[].key
    stringrequired
  • stages[].name
    stringrequired
  • stages[].approvers
    object[]required
  • stages[].quorum
    object
  • stages[].parallel_with_previous
    boolean
  • stages[].conditions
    object[]
  • stages[].sla_hours
    number | null
  • stages[].reminder_every_hours
    number | null
  • stages[].escalate_after_hours
    number | null
  • stages[].escalate_to
    object[]
  • reapproval
    object
  • reapproval.percent
    number | null
  • reapproval.amount
    number | null
  • reapproval.on_decrease
    boolean
  • version
    integerrequired
  • template_key
    string | null
  • created_by_id
    integer
  • updated_by_id
    integer
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/policy_templates/1/apply" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "activate": true,
  "project_id": 1
}'
GET /rest/v1.0/companies/{company_id}/approval_workflows/record_status

A record's runs and whether its domain decision may proceed

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • object_type
    stringqueryrequired
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • object_id
    integerqueryrequired

Response · 200 · object

  • object_type
    string
  • object_id
    integer
  • clearance
    object
  • clearance.clear
    boolean
  • clearance.reason
    string
    One of: no_policy, approved, approval_required, approval_pending, reapproval_required.
  • clearance.approval_id
    integer | null
  • clearance.message
    string | null
  • approvals
    object[]
  • approvals[].id
    integerrequired
  • approvals[].object_type
    stringrequired
  • approvals[].object_label
    string
  • approvals[].object_id
    integerrequired
  • approvals[].project_id
    integer | null
  • approvals[].policy_id
    integer | null
  • approvals[].policy_version
    integer | null
  • approvals[].status
    stringrequired
    One of: pending, approved, rejected, cancelled, superseded.
  • approvals[].title
    string | null
  • approvals[].record_url
    string | null
  • approvals[].amount
    string | null
    Decimal string with two places
  • approvals[].facts
    object
  • approvals[].plan
    object[]
  • approvals[].submitted_by_id
    integer
  • approvals[].started_via
    string
    One of: user, automation.
  • approvals[].source_ref
    string | null
  • approvals[].round
    integer
  • approvals[].supersedes_id
    integer | null
  • approvals[].rejected_reason
    string | null
  • approvals[].completed_at
    string (date-time) | null
  • approvals[].created_at
    string (date-time)
  • approvals[].updated_at
    string (date-time)
  • approvals[].tasks
    object[]required
  • approvals[].events
    object[]

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/approval_workflows/record_status" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/approval_workflows/simulate

Who would approve this record? (read-only)

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • object_type
    stringrequired
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • object_id
    integer
  • facts
    object
  • policy
    object
  • policy.object_type
    string
    One of: change_order, commitment_change_order, payment_application, purchase_request, subcontract, purchase_order, ap_bill, payment_batch, ar_invoice, submittal, expense_report, budget_change, contingency_draw.
  • policy.project_id
    integer | null
  • policy.name
    string
  • policy.description
    string | null
  • policy.priority
    integer
  • policy.is_active
    boolean
  • policy.conditions
    object[]
  • policy.conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • policy.conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • policy.conditions[].value
    number | string | (number | string)[]required
  • policy.stages
    object[]
  • policy.stages[].key
    stringrequired
  • policy.stages[].name
    stringrequired
  • policy.stages[].approvers
    object[]required
  • policy.stages[].approvers[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • policy.stages[].approvers[].user_id
    integer
  • policy.stages[].approvers[].role
    string
  • policy.stages[].approvers[].template_id
    integer
  • policy.stages[].approvers[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • policy.stages[].quorum
    object
  • policy.stages[].quorum.type
    stringrequired
    One of: any, all, n.
  • policy.stages[].quorum.n
    integer
  • policy.stages[].parallel_with_previous
    boolean
  • policy.stages[].conditions
    object[]
  • policy.stages[].conditions[].field
    stringrequired
    One of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
  • policy.stages[].conditions[].op
    stringrequired
    One of: gt, gte, lt, lte, eq, neq, in, not_in.
  • policy.stages[].conditions[].value
    number | string | (number | string)[]required
  • policy.stages[].sla_hours
    number | null
  • policy.stages[].reminder_every_hours
    number | null
  • policy.stages[].escalate_after_hours
    number | null
  • policy.stages[].escalate_to
    object[]
  • policy.stages[].escalate_to[].type
    stringrequired
    One of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
  • policy.stages[].escalate_to[].user_id
    integer
  • policy.stages[].escalate_to[].role
    string
  • policy.stages[].escalate_to[].template_id
    integer
  • policy.stages[].escalate_to[].key
    string
    One of: project_manager, project_executive, cost_code_owner.
  • policy.reapproval
    object
  • policy.reapproval.percent
    number | null
  • policy.reapproval.amount
    number | null
  • policy.reapproval.on_decrease
    boolean
  • policy.template_key
    string | null

Response · 200 · object

  • object_type
    stringrequired
  • object_id
    integer | null
  • title
    string
  • facts
    object
  • policy
    object | null
  • policy.id
    integer | null
  • policy.name
    string
  • policy.project_id
    integer | null
  • approval_required
    booleanrequired
  • guards
    string[]required
  • stages
    object[]required
  • stages[].key
    string
  • stages[].name
    string
  • stages[].seq
    integer
  • stages[].parallel
    boolean
  • stages[].quorum
    integer
  • stages[].quorum_rule
    object
  • stages[].fallback
    boolean
  • stages[].sla_hours
    number | null
  • stages[].approvers
    object[]
  • stages[].excluded
    object[]

Errors

  • 401Missing or invalid credentials
  • 403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide
  • 404Not found in this company
  • 409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required
  • 422Invalid body

Example request

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

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