Approvals
- GET
/rest/v1.0/companies/{company_id}/approval_workflows/approvalsMy approvals: runs waiting on me, decided by me, or submitted by me - POST
/rest/v1.0/companies/{company_id}/approval_workflows/approvalsSubmit a record for approval (agents may submit; only people decide) - GET
/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}Show a run with tasks and audit trail - POST
/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/cancelWithdraw a pending run (submitter or admin) - POST
/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/commentsComment on a run - POST
/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/decisionApprove or reject (reject needs a comment) - POST
/rest/v1.0/companies/{company_id}/approval_workflows/approvals/bulk_decisionApprove several runs (per-item results; not every type allows bulk) - GET
/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersCost code owners of a project - POST
/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersAssign a cost code owner (company admins) - DELETE
/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners/{id}Remove a cost code owner - GET
/rest/v1.0/companies/{company_id}/approval_workflows/delegationsApproval delegations (own; admins see all) - POST
/rest/v1.0/companies/{company_id}/approval_workflows/delegationsDelegate approvals while out of office - DELETE
/rest/v1.0/companies/{company_id}/approval_workflows/delegations/{id}Revoke a delegation - GET
/rest/v1.0/companies/{company_id}/approval_workflows/object_typesRecord types covered and their mandatory domain controls - GET
/rest/v1.0/companies/{company_id}/approval_workflows/policiesList approval policies - POST
/rest/v1.0/companies/{company_id}/approval_workflows/policiesCreate an approval policy (company admins) - GET
/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Show an approval policy - PATCH
/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Update an approval policy (bumps version; runs in flight keep their plan) - DELETE
/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Delete an approval policy - GET
/rest/v1.0/companies/{company_id}/approval_workflows/policy_templatesStarter policies - POST
/rest/v1.0/companies/{company_id}/approval_workflows/policy_templates/{key}/applyCreate a policy from a template (inactive unless activate) - GET
/rest/v1.0/companies/{company_id}/approval_workflows/record_statusA record's runs and whether its domain decision may proceed - POST
/rest/v1.0/companies/{company_id}/approval_workflows/simulateWho would approve this record? (read-only)
/rest/v1.0/companies/{company_id}/approval_workflows/approvalsMy approvals: runs waiting on me, decided by me, or submitted by me
Parameters
- company_idintegerpathrequired
- filterstringqueryOne of: pending, decided, submitted.
- object_typestringqueryOne 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.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- object_typestringrequired
- object_labelstring
- object_idintegerrequired
- project_idinteger | null
- policy_idinteger | null
- policy_versioninteger | null
- statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- titlestring | null
- record_urlstring | null
- amountstring | nullDecimal string with two places
- factsobject
- planobject[]
- submitted_by_idinteger
- started_viastringOne of: user, automation.
- source_refstring | null
- roundinteger
- supersedes_idinteger | null
- rejected_reasonstring | null
- completed_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
- tasksobject[]required
- tasks[].idintegerrequired
- tasks[].seqintegerrequired
- tasks[].stage_indexinteger
- tasks[].stage_keystring
- tasks[].stage_namestringrequired
- tasks[].quorumintegerrequired
- tasks[].approver_user_idintegerrequired
- tasks[].sourcestring
- tasks[].statusstringrequiredOne of: waiting, pending, approved, rejected, void.
- tasks[].activated_atstring (date-time) | null
- tasks[].due_atstring (date-time) | null
- tasks[].reminder_countinteger
- tasks[].escalation_levelinteger
- tasks[].escalated_to_user_idsinteger[]
- tasks[].acted_by_idinteger | null
- tasks[].acted_as_delegate_of_idinteger | null
- tasks[].commentstring | null
- tasks[].acted_atstring (date-time) | null
- eventsobject[]
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idinteger | null
- events[].task_idinteger | null
- events[].commentstring | null
- events[].changesany | null
- events[].created_atstring (date-time)required
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/approvalsSubmit a record for approval (agents may submit; only people decide)
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_typestringrequiredOne 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_idintegerrequired
- policy_idinteger
- commentstring
Response · 200 · object
- statusstringrequiredOne of: pending, not_required.
- approvalobject | null
- approval.idintegerrequired
- approval.object_typestringrequired
- approval.object_labelstring
- approval.object_idintegerrequired
- approval.project_idinteger | null
- approval.policy_idinteger | null
- approval.policy_versioninteger | null
- approval.statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- approval.titlestring | null
- approval.record_urlstring | null
- approval.amountstring | nullDecimal string with two places
- approval.factsobject
- approval.planobject[]
- approval.submitted_by_idinteger
- approval.started_viastringOne of: user, automation.
- approval.source_refstring | null
- approval.roundinteger
- approval.supersedes_idinteger | null
- approval.rejected_reasonstring | null
- approval.completed_atstring (date-time) | null
- approval.created_atstring (date-time)
- approval.updated_atstring (date-time)
- approval.tasksobject[]required
- approval.eventsobject[]
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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
}'/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}Show a run with tasks and audit trail
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- object_typestringrequired
- object_labelstring
- object_idintegerrequired
- project_idinteger | null
- policy_idinteger | null
- policy_versioninteger | null
- statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- titlestring | null
- record_urlstring | null
- amountstring | nullDecimal string with two places
- factsobject
- planobject[]
- submitted_by_idinteger
- started_viastringOne of: user, automation.
- source_refstring | null
- roundinteger
- supersedes_idinteger | null
- rejected_reasonstring | null
- completed_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
- tasksobject[]required
- tasks[].idintegerrequired
- tasks[].seqintegerrequired
- tasks[].stage_indexinteger
- tasks[].stage_keystring
- tasks[].stage_namestringrequired
- tasks[].quorumintegerrequired
- tasks[].approver_user_idintegerrequired
- tasks[].sourcestring
- tasks[].statusstringrequiredOne of: waiting, pending, approved, rejected, void.
- tasks[].activated_atstring (date-time) | null
- tasks[].due_atstring (date-time) | null
- tasks[].reminder_countinteger
- tasks[].escalation_levelinteger
- tasks[].escalated_to_user_idsinteger[]
- tasks[].acted_by_idinteger | null
- tasks[].acted_as_delegate_of_idinteger | null
- tasks[].commentstring | null
- tasks[].acted_atstring (date-time) | null
- eventsobject[]
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idinteger | null
- events[].task_idinteger | null
- events[].commentstring | null
- events[].changesany | null
- events[].created_atstring (date-time)required
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/cancelWithdraw a pending run (submitter or admin)
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- reasonstring
Response · 200 · object
- idintegerrequired
- object_typestringrequired
- object_labelstring
- object_idintegerrequired
- project_idinteger | null
- policy_idinteger | null
- policy_versioninteger | null
- statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- titlestring | null
- record_urlstring | null
- amountstring | nullDecimal string with two places
- factsobject
- planobject[]
- submitted_by_idinteger
- started_viastringOne of: user, automation.
- source_refstring | null
- roundinteger
- supersedes_idinteger | null
- rejected_reasonstring | null
- completed_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
- tasksobject[]required
- tasks[].idintegerrequired
- tasks[].seqintegerrequired
- tasks[].stage_indexinteger
- tasks[].stage_keystring
- tasks[].stage_namestringrequired
- tasks[].quorumintegerrequired
- tasks[].approver_user_idintegerrequired
- tasks[].sourcestring
- tasks[].statusstringrequiredOne of: waiting, pending, approved, rejected, void.
- tasks[].activated_atstring (date-time) | null
- tasks[].due_atstring (date-time) | null
- tasks[].reminder_countinteger
- tasks[].escalation_levelinteger
- tasks[].escalated_to_user_idsinteger[]
- tasks[].acted_by_idinteger | null
- tasks[].acted_as_delegate_of_idinteger | null
- tasks[].commentstring | null
- tasks[].acted_atstring (date-time) | null
- eventsobject[]
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idinteger | null
- events[].task_idinteger | null
- events[].commentstring | null
- events[].changesany | null
- events[].created_atstring (date-time)required
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"
}'/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/commentsComment on a run
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- commentstringrequired
Response · 201 · object
- idintegerrequired
- object_typestringrequired
- object_labelstring
- object_idintegerrequired
- project_idinteger | null
- policy_idinteger | null
- policy_versioninteger | null
- statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- titlestring | null
- record_urlstring | null
- amountstring | nullDecimal string with two places
- factsobject
- planobject[]
- submitted_by_idinteger
- started_viastringOne of: user, automation.
- source_refstring | null
- roundinteger
- supersedes_idinteger | null
- rejected_reasonstring | null
- completed_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
- tasksobject[]required
- tasks[].idintegerrequired
- tasks[].seqintegerrequired
- tasks[].stage_indexinteger
- tasks[].stage_keystring
- tasks[].stage_namestringrequired
- tasks[].quorumintegerrequired
- tasks[].approver_user_idintegerrequired
- tasks[].sourcestring
- tasks[].statusstringrequiredOne of: waiting, pending, approved, rejected, void.
- tasks[].activated_atstring (date-time) | null
- tasks[].due_atstring (date-time) | null
- tasks[].reminder_countinteger
- tasks[].escalation_levelinteger
- tasks[].escalated_to_user_idsinteger[]
- tasks[].acted_by_idinteger | null
- tasks[].acted_as_delegate_of_idinteger | null
- tasks[].commentstring | null
- tasks[].acted_atstring (date-time) | null
- eventsobject[]
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idinteger | null
- events[].task_idinteger | null
- events[].commentstring | null
- events[].changesany | null
- events[].created_atstring (date-time)required
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"
}'/rest/v1.0/companies/{company_id}/approval_workflows/approvals/{id}/decisionApprove or reject (reject needs a comment)
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- decisionstringrequiredOne of: approve, reject.
- commentstring
Response · 200 · object
- outcomestringrequiredOne of: recorded, approved, rejected.
- approvalobjectrequired
- approval.idintegerrequired
- approval.object_typestringrequired
- approval.object_labelstring
- approval.object_idintegerrequired
- approval.project_idinteger | null
- approval.policy_idinteger | null
- approval.policy_versioninteger | null
- approval.statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- approval.titlestring | null
- approval.record_urlstring | null
- approval.amountstring | nullDecimal string with two places
- approval.factsobject
- approval.planobject[]
- approval.submitted_by_idinteger
- approval.started_viastringOne of: user, automation.
- approval.source_refstring | null
- approval.roundinteger
- approval.supersedes_idinteger | null
- approval.rejected_reasonstring | null
- approval.completed_atstring (date-time) | null
- approval.created_atstring (date-time)
- approval.updated_atstring (date-time)
- approval.tasksobject[]required
- approval.eventsobject[]
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"
}'/rest/v1.0/companies/{company_id}/approval_workflows/approvals/bulk_decisionApprove several runs (per-item results; not every type allows bulk)
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_idsinteger[]required
- commentstring
Response · 200 · object
- resultsobject[]
- results[].instance_idinteger
- results[].okboolean
- results[].outcomestring
- results[].errorstring
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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": []
}'/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersCost code owners of a project
Parameters
- company_idintegerpathrequired
- project_idintegerqueryrequired
Response · 200 · object[]
- idinteger
- project_idinteger
- cost_code_idinteger
- user_idinteger
- created_by_idinteger
- created_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_ownersAssign a cost code owner (company admins)
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_idintegerrequired
- cost_code_idintegerrequired
- user_idintegerrequired
Response · 201 · object
- idinteger
- project_idinteger
- cost_code_idinteger
- user_idinteger
- created_by_idinteger
- created_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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
}'/rest/v1.0/companies/{company_id}/approval_workflows/cost_code_owners/{id}Remove a cost code owner
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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 credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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)"/rest/v1.0/companies/{company_id}/approval_workflows/delegationsApproval delegations (own; admins see all)
Parameters
- company_idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- from_user_idintegerrequired
- to_user_idintegerrequired
- object_typesstring[]
- starts_atstring (date-time)
- ends_atstring (date-time)
- reasonstring
- created_by_idinteger
- revoked_atstring (date-time) | null
- created_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/delegationsDelegate approvals while out of office
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_idinteger
- to_user_idintegerrequired
- object_typesstring[]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_atstring (date-time)required
- ends_atstring (date-time)required
- reasonstringrequired
Response · 201 · object
- idintegerrequired
- from_user_idintegerrequired
- to_user_idintegerrequired
- object_typesstring[]
- starts_atstring (date-time)
- ends_atstring (date-time)
- reasonstring
- created_by_idinteger
- revoked_atstring (date-time) | null
- created_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"
}'/rest/v1.0/companies/{company_id}/approval_workflows/delegations/{id}Revoke a delegation
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- idintegerrequired
- from_user_idintegerrequired
- to_user_idintegerrequired
- object_typesstring[]
- starts_atstring (date-time)
- ends_atstring (date-time)
- reasonstring
- created_by_idinteger
- revoked_atstring (date-time) | null
- created_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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)"/rest/v1.0/companies/{company_id}/approval_workflows/object_typesRecord types covered and their mandatory domain controls
Parameters
- company_idintegerpathrequired
Response · 200 · object[]
- object_typestring
- labelstring
- bulk_approveboolean
- guardsstring[]
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/policiesList approval policies
Parameters
- company_idintegerpathrequired
- object_typestringqueryOne 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_idstringqueryA project id, or `company` for company-wide policies only
Response · 200 · object[]
- idintegerrequired
- object_typestringrequired
- project_idinteger | null
- namestringrequired
- descriptionstring | null
- priorityinteger
- is_activebooleanrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
- versionintegerrequired
- template_keystring | null
- created_by_idinteger
- updated_by_idinteger
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/policiesCreate an approval policy (company admins)
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_policyobjectrequired
- approval_policy.object_typestringOne 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_idinteger | null
- approval_policy.namestring
- approval_policy.descriptionstring | null
- approval_policy.priorityinteger
- approval_policy.is_activeboolean
- approval_policy.conditionsobject[]
- approval_policy.conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- approval_policy.conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- approval_policy.conditions[].valuenumber | string | (number | string)[]required
- approval_policy.stagesobject[]
- approval_policy.stages[].keystringrequired
- approval_policy.stages[].namestringrequired
- approval_policy.stages[].approversobject[]required
- approval_policy.stages[].approvers[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- approval_policy.stages[].approvers[].user_idinteger
- approval_policy.stages[].approvers[].rolestring
- approval_policy.stages[].approvers[].template_idinteger
- approval_policy.stages[].approvers[].keystringOne of: project_manager, project_executive, cost_code_owner.
- approval_policy.stages[].quorumobject
- approval_policy.stages[].quorum.typestringrequiredOne of: any, all, n.
- approval_policy.stages[].quorum.ninteger
- approval_policy.stages[].parallel_with_previousboolean
- approval_policy.stages[].conditionsobject[]
- approval_policy.stages[].conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- approval_policy.stages[].conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- approval_policy.stages[].conditions[].valuenumber | string | (number | string)[]required
- approval_policy.stages[].sla_hoursnumber | null
- approval_policy.stages[].reminder_every_hoursnumber | null
- approval_policy.stages[].escalate_after_hoursnumber | null
- approval_policy.stages[].escalate_toobject[]
- approval_policy.stages[].escalate_to[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- approval_policy.stages[].escalate_to[].user_idinteger
- approval_policy.stages[].escalate_to[].rolestring
- approval_policy.stages[].escalate_to[].template_idinteger
- approval_policy.stages[].escalate_to[].keystringOne of: project_manager, project_executive, cost_code_owner.
- approval_policy.reapprovalobject
- approval_policy.reapproval.percentnumber | null
- approval_policy.reapproval.amountnumber | null
- approval_policy.reapproval.on_decreaseboolean
- approval_policy.template_keystring | null
Response · 201 · object
- idintegerrequired
- object_typestringrequired
- project_idinteger | null
- namestringrequired
- descriptionstring | null
- priorityinteger
- is_activebooleanrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
- versionintegerrequired
- template_keystring | null
- created_by_idinteger
- updated_by_idinteger
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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": {}
}'/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Show an approval policy
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- object_typestringrequired
- project_idinteger | null
- namestringrequired
- descriptionstring | null
- priorityinteger
- is_activebooleanrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
- versionintegerrequired
- template_keystring | null
- created_by_idinteger
- updated_by_idinteger
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Update an approval policy (bumps version; runs in flight keep their plan)
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_policyobjectrequired
- approval_policy.object_typestringOne 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_idinteger | null
- approval_policy.namestring
- approval_policy.descriptionstring | null
- approval_policy.priorityinteger
- approval_policy.is_activeboolean
- approval_policy.conditionsobject[]
- approval_policy.conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- approval_policy.conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- approval_policy.conditions[].valuenumber | string | (number | string)[]required
- approval_policy.stagesobject[]
- approval_policy.stages[].keystringrequired
- approval_policy.stages[].namestringrequired
- approval_policy.stages[].approversobject[]required
- approval_policy.stages[].approvers[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- approval_policy.stages[].approvers[].user_idinteger
- approval_policy.stages[].approvers[].rolestring
- approval_policy.stages[].approvers[].template_idinteger
- approval_policy.stages[].approvers[].keystringOne of: project_manager, project_executive, cost_code_owner.
- approval_policy.stages[].quorumobject
- approval_policy.stages[].quorum.typestringrequiredOne of: any, all, n.
- approval_policy.stages[].quorum.ninteger
- approval_policy.stages[].parallel_with_previousboolean
- approval_policy.stages[].conditionsobject[]
- approval_policy.stages[].conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- approval_policy.stages[].conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- approval_policy.stages[].conditions[].valuenumber | string | (number | string)[]required
- approval_policy.stages[].sla_hoursnumber | null
- approval_policy.stages[].reminder_every_hoursnumber | null
- approval_policy.stages[].escalate_after_hoursnumber | null
- approval_policy.stages[].escalate_toobject[]
- approval_policy.stages[].escalate_to[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- approval_policy.stages[].escalate_to[].user_idinteger
- approval_policy.stages[].escalate_to[].rolestring
- approval_policy.stages[].escalate_to[].template_idinteger
- approval_policy.stages[].escalate_to[].keystringOne of: project_manager, project_executive, cost_code_owner.
- approval_policy.reapprovalobject
- approval_policy.reapproval.percentnumber | null
- approval_policy.reapproval.amountnumber | null
- approval_policy.reapproval.on_decreaseboolean
- approval_policy.template_keystring | null
Response · 200 · object
- idintegerrequired
- object_typestringrequired
- project_idinteger | null
- namestringrequired
- descriptionstring | null
- priorityinteger
- is_activebooleanrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
- versionintegerrequired
- template_keystring | null
- created_by_idinteger
- updated_by_idinteger
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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": {}
}'/rest/v1.0/companies/{company_id}/approval_workflows/policies/{id}Delete an approval policy
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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 credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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)"/rest/v1.0/companies/{company_id}/approval_workflows/policy_templatesStarter policies
Parameters
- company_idintegerpathrequired
Response · 200 · object[]
- keystringrequired
- namestringrequired
- descriptionstring
- object_typestringrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/policy_templates/{key}/applyCreate a policy from a template (inactive unless activate)
Parameters
- company_idintegerpathrequired
- keystringpathrequired
- Idempotency-KeystringheaderOptional. 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
- activateboolean
- project_idinteger | null
Response · 201 · object
- idintegerrequired
- object_typestringrequired
- project_idinteger | null
- namestringrequired
- descriptionstring | null
- priorityinteger
- is_activebooleanrequired
- conditionsobject[]
- conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- conditions[].valuenumber | string | (number | string)[]required
- stagesobject[]required
- stages[].keystringrequired
- stages[].namestringrequired
- stages[].approversobject[]required
- stages[].quorumobject
- stages[].parallel_with_previousboolean
- stages[].conditionsobject[]
- stages[].sla_hoursnumber | null
- stages[].reminder_every_hoursnumber | null
- stages[].escalate_after_hoursnumber | null
- stages[].escalate_toobject[]
- reapprovalobject
- reapproval.percentnumber | null
- reapproval.amountnumber | null
- reapproval.on_decreaseboolean
- versionintegerrequired
- template_keystring | null
- created_by_idinteger
- updated_by_idinteger
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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
}'/rest/v1.0/companies/{company_id}/approval_workflows/record_statusA record's runs and whether its domain decision may proceed
Parameters
- company_idintegerpathrequired
- object_typestringqueryrequiredOne 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_idintegerqueryrequired
Response · 200 · object
- object_typestring
- object_idinteger
- clearanceobject
- clearance.clearboolean
- clearance.reasonstringOne of: no_policy, approved, approval_required, approval_pending, reapproval_required.
- clearance.approval_idinteger | null
- clearance.messagestring | null
- approvalsobject[]
- approvals[].idintegerrequired
- approvals[].object_typestringrequired
- approvals[].object_labelstring
- approvals[].object_idintegerrequired
- approvals[].project_idinteger | null
- approvals[].policy_idinteger | null
- approvals[].policy_versioninteger | null
- approvals[].statusstringrequiredOne of: pending, approved, rejected, cancelled, superseded.
- approvals[].titlestring | null
- approvals[].record_urlstring | null
- approvals[].amountstring | nullDecimal string with two places
- approvals[].factsobject
- approvals[].planobject[]
- approvals[].submitted_by_idinteger
- approvals[].started_viastringOne of: user, automation.
- approvals[].source_refstring | null
- approvals[].roundinteger
- approvals[].supersedes_idinteger | null
- approvals[].rejected_reasonstring | null
- approvals[].completed_atstring (date-time) | null
- approvals[].created_atstring (date-time)
- approvals[].updated_atstring (date-time)
- approvals[].tasksobject[]required
- approvals[].eventsobject[]
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"/rest/v1.0/companies/{company_id}/approval_workflows/simulateWho would approve this record? (read-only)
Parameters
- company_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_typestringrequiredOne 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_idinteger
- factsobject
- policyobject
- policy.object_typestringOne 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_idinteger | null
- policy.namestring
- policy.descriptionstring | null
- policy.priorityinteger
- policy.is_activeboolean
- policy.conditionsobject[]
- policy.conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- policy.conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- policy.conditions[].valuenumber | string | (number | string)[]required
- policy.stagesobject[]
- policy.stages[].keystringrequired
- policy.stages[].namestringrequired
- policy.stages[].approversobject[]required
- policy.stages[].approvers[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- policy.stages[].approvers[].user_idinteger
- policy.stages[].approvers[].rolestring
- policy.stages[].approvers[].template_idinteger
- policy.stages[].approvers[].keystringOne of: project_manager, project_executive, cost_code_owner.
- policy.stages[].quorumobject
- policy.stages[].quorum.typestringrequiredOne of: any, all, n.
- policy.stages[].quorum.ninteger
- policy.stages[].parallel_with_previousboolean
- policy.stages[].conditionsobject[]
- policy.stages[].conditions[].fieldstringrequiredOne of: amount, pct_of_contract, cost_type, project_id, vendor_id, vendor_risk, cost_code_id, change_amount.
- policy.stages[].conditions[].opstringrequiredOne of: gt, gte, lt, lte, eq, neq, in, not_in.
- policy.stages[].conditions[].valuenumber | string | (number | string)[]required
- policy.stages[].sla_hoursnumber | null
- policy.stages[].reminder_every_hoursnumber | null
- policy.stages[].escalate_after_hoursnumber | null
- policy.stages[].escalate_toobject[]
- policy.stages[].escalate_to[].typestringrequiredOne of: user, project_role, permission_template, accounting_role, company_admin, dynamic.
- policy.stages[].escalate_to[].user_idinteger
- policy.stages[].escalate_to[].rolestring
- policy.stages[].escalate_to[].template_idinteger
- policy.stages[].escalate_to[].keystringOne of: project_manager, project_executive, cost_code_owner.
- policy.reapprovalobject
- policy.reapproval.percentnumber | null
- policy.reapproval.amountnumber | null
- policy.reapproval.on_decreaseboolean
- policy.template_keystring | null
Response · 200 · object
- object_typestringrequired
- object_idinteger | null
- titlestring
- factsobject
- policyobject | null
- policy.idinteger | null
- policy.namestring
- policy.project_idinteger | null
- approval_requiredbooleanrequired
- guardsstring[]required
- stagesobject[]required
- stages[].keystring
- stages[].namestring
- stages[].seqinteger
- stages[].parallelboolean
- stages[].quoruminteger
- stages[].quorum_ruleobject
- stages[].fallbackboolean
- stages[].sla_hoursnumber | null
- stages[].approversobject[]
- stages[].excludedobject[]
Errors
401Missing or invalid credentials403Not allowed: company admin required, not an approver, ineligible approver (maker-checker, missing grant), or an agent/service-account principal trying to decide404Not found in this company409approval_closed, already_decided, approval_in_progress, approver_unresolved or reapproval_required422Invalid 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"
}'