Company Admin
- GET
/rest/v1.0/companies/{company_id}/departmentsList departments - POST
/rest/v1.0/companies/{company_id}/departmentsCreate departments - GET
/rest/v1.0/companies/{company_id}/departments/{id}Get departments - PATCH
/rest/v1.0/companies/{company_id}/departments/{id}Update departments - DELETE
/rest/v1.0/companies/{company_id}/departments/{id}Delete departments - GET
/rest/v1.0/companies/{company_id}/insurance_evidence_inboxRead current evidence awaiting review and route policy follow-ups - GET
/rest/v1.0/companies/{company_id}/insurance_followupsCompany-scoped renewal follow-up queue - GET
/rest/v1.0/companies/{company_id}/insurance_policiesList company insurance policies - POST
/rest/v1.0/companies/{company_id}/insurance_policiesCreate company insurance policy - GET
/rest/v1.0/companies/{company_id}/insurance_policies/{id}Read company insurance policy - PATCH
/rest/v1.0/companies/{company_id}/insurance_policies/{id}Edit company insurance policy - DELETE
/rest/v1.0/companies/{company_id}/insurance_policies/{id}Delete company insurance policy - GET
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceRead policy evidence and immutable history - POST
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceReceive an immutable PDF or scan; receipt does not verify coverage - GET
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence/{evidence_id}/contentRead authorized evidence bytes, validating received SHA-256 - GET
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upRead policy follow-up - POST
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upCreate, update, complete or reopen the single policy follow-up - POST
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/renewalsCreate a linked renewal, preserving prior files and reviews - POST
/rest/v1.0/companies/{company_id}/insurance_policies/{id}/reviewsRecord evidence acceptance, rejection or revocation with a reason - GET
/rest/v1.0/companies/{company_id}/invitationsList invitations - POST
/rest/v1.0/companies/{company_id}/invitationsCreate invitation - DELETE
/rest/v1.0/companies/{company_id}/invitations/{id}Delete invitation - GET
/rest/v1.0/companies/{company_id}/migration_jobsList migration jobs - POST
/rest/v1.0/companies/{company_id}/migration_jobsCreate migration job - GET
/rest/v1.0/companies/{company_id}/migration_jobs/{id}Get migration job - POST
/rest/v1.0/companies/{company_id}/migration_jobs/{id}/runExecute the job - GET
/rest/v1.0/companies/{company_id}/officesList offices - POST
/rest/v1.0/companies/{company_id}/officesCreate offices - GET
/rest/v1.0/companies/{company_id}/offices/{id}Get offices - PATCH
/rest/v1.0/companies/{company_id}/offices/{id}Update offices - DELETE
/rest/v1.0/companies/{company_id}/offices/{id}Delete offices - GET
/rest/v1.0/companies/{company_id}/permission_templatesList company permission templates - POST
/rest/v1.0/companies/{company_id}/permission_templatesCreate company permission template - GET
/rest/v1.0/companies/{company_id}/permission_templates/{id}Read company permission template - PATCH
/rest/v1.0/companies/{company_id}/permission_templates/{id}Edit company permission template - DELETE
/rest/v1.0/companies/{company_id}/permission_templates/{id}Delete company permission template - POST
/rest/v1.0/companies/{company_id}/permission_templates/{id}/assignmentsAssign or clear a project permission template - GET
/rest/v1.0/companies/{company_id}/project_regionsList project regions - POST
/rest/v1.0/companies/{company_id}/project_regionsCreate project regions - GET
/rest/v1.0/companies/{company_id}/project_regions/{id}Get project regions - PATCH
/rest/v1.0/companies/{company_id}/project_regions/{id}Update project regions - DELETE
/rest/v1.0/companies/{company_id}/project_regions/{id}Delete project regions - GET
/rest/v1.0/companies/{company_id}/project_stages/{id}Get project stages - PATCH
/rest/v1.0/companies/{company_id}/project_stages/{id}Update project stages - DELETE
/rest/v1.0/companies/{company_id}/project_stages/{id}Delete project stages - GET
/rest/v1.0/companies/{company_id}/project_typesList project types - POST
/rest/v1.0/companies/{company_id}/project_typesCreate project types - GET
/rest/v1.0/companies/{company_id}/project_types/{id}Get project types - PATCH
/rest/v1.0/companies/{company_id}/project_types/{id}Update project types - DELETE
/rest/v1.0/companies/{company_id}/project_types/{id}Delete project types - GET
/rest/v1.0/companies/{company_id}/scim_connectionsList SCIM connections - POST
/rest/v1.0/companies/{company_id}/scim_connectionsCreate SCIM connection - DELETE
/rest/v1.0/companies/{company_id}/scim_connections/{id}Delete SCIM connection - GET
/rest/v1.0/companies/{company_id}/tradesList trades - POST
/rest/v1.0/companies/{company_id}/tradesCreate trades - GET
/rest/v1.0/companies/{company_id}/trades/{id}Get trades - PATCH
/rest/v1.0/companies/{company_id}/trades/{id}Update trades - DELETE
/rest/v1.0/companies/{company_id}/trades/{id}Delete trades
/rest/v1.0/companies/{company_id}/departmentsList departments
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerqueryValues above 1000 are clamped by the REST handler.
- searchstringqueryTrimmed, case-insensitive substring match on name; blank means no filter.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/departments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/departmentsCreate departments
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- departmentobjectrequired
- department.namestringrequiredTrimmed; must contain a non-whitespace character.
- department.descriptionstring | null
- department.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- department.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 201 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/departments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"department": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/departments/{id}Get departments
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/departments/{id}Update departments
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- departmentobjectrequired
- department.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- department.descriptionstring | null
- department.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- department.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"department": {}
}'/rest/v1.0/companies/{company_id}/departments/{id}Delete departments
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/insurance_evidence_inboxRead current evidence awaiting review and route policy follow-ups
Live company-admin authority and admin:read token scope are required. Replaced evidence is excluded from every filter and retained in policy history. Unreviewed, unassigned and mine exclude evidence with a recorded review. Unassigned has no open policy follow-up; mine has an open follow-up assigned to the caller. All returns current evidence regardless of review state. Oldest received first, ID tiebreaker. Only metadata is returned: view/review bytes through the existing policy evidence workflow. Acceptance is not coverage verification or payment release.
Parameters
- company_idintegerpathrequired
- filterstringqueryOne of: unreviewed, unassigned, mine, all.
- kindstringqueryOne of: all, certificate, policy, endorsement.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- evidence_idintegerrequired
- policy_idintegerrequired
- filenamestringrequired
- kindstringrequiredOne of: certificate, policy, endorsement.
- received_atstring (date-time)required
- insurance_typestringrequired
- policy_numberstring | nullrequired
- review_statusstringrequiredOne of: unreviewed, accepted, rejected, revoked.
- follow_upobject | nullrequired
- follow_up.statusstringrequiredOne of: open, completed.
- follow_up.due_datestring (date)required
- follow_up.owner_namestringrequired
- follow_up.owner_availablebooleanrequired
Errors
401Authentication required403Current company-admin authority required404Wrong company422Invalid filter or pagination
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_evidence_inbox" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_followupsCompany-scoped renewal follow-up queue
Overdue means before the current UTC day; due soon includes today through 30 days. Completed items are excluded from overdue/due-soon/mine. Each response page contains at most 25 items. Owners without live authority remain visible for reassignment. No notifications are sent.
Parameters
- company_idintegerpathrequired
- filterstringqueryOne of: open, overdue, due_soon, mine, completed, all.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- policy_idintegerrequired
- owner_user_idintegerrequired
- owner_namestringrequired
- owner_availablebooleanrequired
- due_datestring (date)required
- statusstringrequiredOne of: open, completed.
- notestringrequired
- completed_atstring (date-time) | nullrequired
- completed_by_idinteger | nullrequired
- linked_renewal_idinteger | nullrequired
- policy_versionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Authentication required403Current company admin required404Scoped policy, owner or renewal missing409Stale version, conflicting retry or invalid transition422Invalid input
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_followups" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policiesList company insurance policies
Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Flat array ordered by expiration date then ID. Includes policies associated with historical inactive projects/vendors. No status or search filter. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- pageintegerquery
- per_pageintegerqueryHandler clamps values above 1000.
- filters[project_id]integerqueryOnly the first positive integer value is used. Invalid values are ignored. Filters narrow the company register; they do not imply project membership.
- filters[vendor_id]integerqueryOnly the first positive integer value is used. Invalid values are ignored. Filters narrow the company register; they do not imply project membership.
Response · 200 · object[]
- idintegerrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- notesstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policiesCreate company insurance policy
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Project/vendor references must belong to this company; historical inactive references are permitted. Effective date cannot follow expiration date (400). Date-only inputs must be real calendar dates. Status in the response is pending without expiration, expired before the current instant, expiring within 30 days, otherwise active. JSON metadata only; no certificate upload. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
- insurance_policyobjectrequired
- insurance_policy.insurance_typestringrequiredTrimmed and must not be blank.
- insurance_policy.carrierstring | null
- insurance_policy.policy_numberstring | null
- insurance_policy.coverage_amountnumber | string | null
- insurance_policy.effective_datestring (date) | null
- insurance_policy.expiration_datestring (date) | null
- insurance_policy.statusstringOptional stored status. The response always derives status freshly from expiration_date, so it may differ. One of: active, expiring, expired, pending.
- insurance_policy.project_idinteger | null
- insurance_policy.vendor_idinteger | null
- insurance_policy.notesstring | null
Response · 201 · object
- idintegerrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- notesstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"insurance_policy": {
"insurance_type": "string"
}
}'/rest/v1.0/companies/{company_id}/insurance_policies/{id}Read company insurance policy
Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Response status is computed from expiration at read time, regardless of stored status. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
Response · 200 · object
- idintegerrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- notesstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policies/{id}Edit company insurance policy
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Omitted nullable fields retain their value; explicit null clears them. Remaining project/vendor references must belong to the company. Effective date cannot follow expiration date (400), including when only one date is changed. Response status is freshly derived even if an explicit stored status is supplied. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
- insurance_policyobjectrequired
- insurance_policy.insurance_typestringTrimmed and must not be blank.
- insurance_policy.carrierstring | null
- insurance_policy.policy_numberstring | null
- insurance_policy.coverage_amountnumber | string | null
- insurance_policy.effective_datestring (date) | null
- insurance_policy.expiration_datestring (date) | null
- insurance_policy.statusstringOptional stored status. The response always derives status freshly from expiration_date, so it may differ. One of: active, expiring, expired, pending.
- insurance_policy.project_idinteger | null
- insurance_policy.vendor_idinteger | null
- insurance_policy.notesstring | null
Response · 200 · object
- idintegerrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- notesstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"insurance_policy": {}
}'/rest/v1.0/companies/{company_id}/insurance_policies/{id}Delete company insurance policy
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Permanently deletes the policy metadata record. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceRead policy evidence and immutable history
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- notesstring | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- versionintegerrequired
- renewed_from_idinteger | nullrequired
- renewal_idinteger | nullrequired
- evidenceobject[]required
- evidence[].idintegerrequired
- evidence[].upload_idintegerrequired
- evidence[].storage_project_idintegerrequired
- evidence[].kindstringrequiredOne of: certificate, policy, endorsement.
- evidence[].filenamestringrequired
- evidence[].content_typestringrequired
- evidence[].sizeintegerrequired
- evidence[].sha256stringrequired
- evidence[].policy_snapshotobjectrequired
- evidence[].received_by_idintegerrequired
- evidence[].received_atstring (date-time)required
- evidence[].replaces_evidence_idinteger | nullrequired
- eventsobject[]required
- events[].idintegerrequired
- events[].evidence_idinteger | nullrequired
- events[].actor_user_idintegerrequired
- events[].kindstringrequiredOne of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
- events[].decisionstring | nullrequiredOne of: accepted, rejected, revoked, null.
- events[].notestringrequired
- events[].request_keystring (uuid)required
- events[].policy_versionintegerrequired
- events[].related_policy_idinteger | nullrequired
- events[].recorded_atstring (date-time)required
Errors
401Authentication required403Current company admin authority and source scopes required404Scoped resource not found409Stale version, conflicting retry, retained history or invalid transition422Invalid fields or unsupported evidence bytes
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceReceive an immutable PDF or scan; receipt does not verify coverage
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
- expected_versionintegerrequired
- request_keystring (uuid)required
- storage_project_idintegerrequired
- kindstringrequiredOne of: certificate, policy, endorsement.
- notestringrequired
- replaces_evidence_idinteger
- filestring (binary)required
Response · 201 · object
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- notesstring | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- versionintegerrequired
- renewed_from_idinteger | nullrequired
- renewal_idinteger | nullrequired
- evidenceobject[]required
- evidence[].idintegerrequired
- evidence[].upload_idintegerrequired
- evidence[].storage_project_idintegerrequired
- evidence[].kindstringrequiredOne of: certificate, policy, endorsement.
- evidence[].filenamestringrequired
- evidence[].content_typestringrequired
- evidence[].sizeintegerrequired
- evidence[].sha256stringrequired
- evidence[].policy_snapshotobjectrequired
- evidence[].received_by_idintegerrequired
- evidence[].received_atstring (date-time)required
- evidence[].replaces_evidence_idinteger | nullrequired
- eventsobject[]required
- events[].idintegerrequired
- events[].evidence_idinteger | nullrequired
- events[].actor_user_idintegerrequired
- events[].kindstringrequiredOne of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
- events[].decisionstring | nullrequiredOne of: accepted, rejected, revoked, null.
- events[].notestringrequired
- events[].request_keystring (uuid)required
- events[].policy_versionintegerrequired
- events[].related_policy_idinteger | nullrequired
- events[].recorded_atstring (date-time)required
Errors
401Authentication required403Current company admin authority and source scopes required404Scoped resource not found409Stale version, conflicting retry, retained history or invalid transition422Invalid fields or unsupported evidence bytes
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"request_key": "00000000-0000-4000-8000-000000000000",
"storage_project_id": 1,
"kind": "certificate",
"note": "string",
"file": "string"
}'/rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence/{evidence_id}/contentRead authorized evidence bytes, validating received SHA-256
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- evidence_idintegerpathrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Authentication required403Current company admin authority and source scopes required404Scoped resource not found409Stale version, conflicting retry, retained history or invalid transition422Invalid fields or unsupported evidence bytes
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence/1/content" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upRead policy follow-up
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object | null
- idintegerrequired
- policy_idintegerrequired
- owner_user_idintegerrequired
- owner_namestringrequired
- owner_availablebooleanrequired
- due_datestring (date)required
- statusstringrequiredOne of: open, completed.
- notestringrequired
- completed_atstring (date-time) | nullrequired
- completed_by_idinteger | nullrequired
- linked_renewal_idinteger | nullrequired
- policy_versionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Authentication required403Current company admin required404Scoped policy, owner or renewal missing409Stale version, conflicting retry or invalid transition422Invalid input
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/follow_up" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upCreate, update, complete or reopen the single policy follow-up
Owner must currently have company admin authority. Completion is an administrative outcome only. Optional renewal must be the actual child of this policy. Reopen clears current completion/link and retains prior outcome in policy events. Commands require current policy version and a company-unique UUID; identical retries have no new effect.
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
- expected_versionintegerrequired
- request_keystring (uuid)required
- notestringrequired
- actionstringrequired
- owner_user_idintegerrequired
- due_datestring (date)required
Response · 200 · object | null
- idintegerrequired
- policy_idintegerrequired
- owner_user_idintegerrequired
- owner_namestringrequired
- owner_availablebooleanrequired
- due_datestring (date)required
- statusstringrequiredOne of: open, completed.
- notestringrequired
- completed_atstring (date-time) | nullrequired
- completed_by_idinteger | nullrequired
- linked_renewal_idinteger | nullrequired
- policy_versionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Authentication required403Current company admin required404Scoped policy, owner or renewal missing409Stale version, conflicting retry or invalid transition422Invalid input
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/follow_up" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"request_key": "00000000-0000-4000-8000-000000000000",
"note": "string",
"action": "string",
"owner_user_id": 1,
"due_date": "2026-11-01"
}'/rest/v1.0/companies/{company_id}/insurance_policies/{id}/renewalsCreate a linked renewal, preserving prior files and reviews
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
- expected_versionintegerrequired
- request_keystring (uuid)required
- policyobjectrequired
- policy.insurance_typestringrequired
- policy.carrierstring | null
- policy.policy_numberstring | null
- policy.coverage_amountnumber | null
- policy.effective_datestring (date) | null
- policy.expiration_datestring (date) | null
- policy.project_idinteger | null
- policy.vendor_idinteger | null
- policy.notesstring | null
- policy.statusstringOne of: active, expiring, expired, pending.
- notestringrequired
Response · 201 · object
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- notesstring | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- versionintegerrequired
- renewed_from_idinteger | nullrequired
- renewal_idinteger | nullrequired
- evidenceobject[]required
- evidence[].idintegerrequired
- evidence[].upload_idintegerrequired
- evidence[].storage_project_idintegerrequired
- evidence[].kindstringrequiredOne of: certificate, policy, endorsement.
- evidence[].filenamestringrequired
- evidence[].content_typestringrequired
- evidence[].sizeintegerrequired
- evidence[].sha256stringrequired
- evidence[].policy_snapshotobjectrequired
- evidence[].received_by_idintegerrequired
- evidence[].received_atstring (date-time)required
- evidence[].replaces_evidence_idinteger | nullrequired
- eventsobject[]required
- events[].idintegerrequired
- events[].evidence_idinteger | nullrequired
- events[].actor_user_idintegerrequired
- events[].kindstringrequiredOne of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
- events[].decisionstring | nullrequiredOne of: accepted, rejected, revoked, null.
- events[].notestringrequired
- events[].request_keystring (uuid)required
- events[].policy_versionintegerrequired
- events[].related_policy_idinteger | nullrequired
- events[].recorded_atstring (date-time)required
Errors
401Authentication required403Current company admin authority and source scopes required404Scoped resource not found409Stale version, conflicting retry, retained history or invalid transition422Invalid fields or unsupported evidence bytes
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/renewals" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"request_key": "00000000-0000-4000-8000-000000000000",
"policy": {
"insurance_type": "string"
},
"note": "string"
}'/rest/v1.0/companies/{company_id}/insurance_policies/{id}/reviewsRecord evidence acceptance, rejection or revocation with a reason
Review requires admin:read for the referenced source as well as admin:write. Acceptance records a document review, not verified coverage. Only an accepted review may be revoked. Every command requires current version and a company-unique request key; identical retries have no additional effect.
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
- expected_versionintegerrequired
- request_keystring (uuid)required
- evidence_idintegerrequired
- decisionstringrequiredOne of: accepted, rejected, revoked.
- notestringrequired
Response · 200 · object
- insurance_typestringrequired
- carrierstring | nullrequired
- policy_numberstring | nullrequired
- coverage_amountnumber | nullrequired
- effective_datestring (date) | nullrequired
- expiration_datestring (date) | nullrequired
- project_idinteger | nullrequired
- vendor_idinteger | nullrequired
- notesstring | nullrequired
- statusstringrequiredOne of: active, expiring, expired, pending.
- idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- versionintegerrequired
- renewed_from_idinteger | nullrequired
- renewal_idinteger | nullrequired
- evidenceobject[]required
- evidence[].idintegerrequired
- evidence[].upload_idintegerrequired
- evidence[].storage_project_idintegerrequired
- evidence[].kindstringrequiredOne of: certificate, policy, endorsement.
- evidence[].filenamestringrequired
- evidence[].content_typestringrequired
- evidence[].sizeintegerrequired
- evidence[].sha256stringrequired
- evidence[].policy_snapshotobjectrequired
- evidence[].received_by_idintegerrequired
- evidence[].received_atstring (date-time)required
- evidence[].replaces_evidence_idinteger | nullrequired
- eventsobject[]required
- events[].idintegerrequired
- events[].evidence_idinteger | nullrequired
- events[].actor_user_idintegerrequired
- events[].kindstringrequiredOne of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
- events[].decisionstring | nullrequiredOne of: accepted, rejected, revoked, null.
- events[].notestringrequired
- events[].request_keystring (uuid)required
- events[].policy_versionintegerrequired
- events[].related_policy_idinteger | nullrequired
- events[].recorded_atstring (date-time)required
Errors
401Authentication required403Current company admin authority and source scopes required404Scoped resource not found409Stale version, conflicting retry, retained history or invalid transition422Invalid fields or unsupported evidence bytes
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/reviews" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"expected_version": 1,
"request_key": "00000000-0000-4000-8000-000000000000",
"evidence_id": 1,
"decision": "accepted",
"note": "string"
}'/rest/v1.0/companies/{company_id}/invitationsList invitations
A scoped API token needs identity:read.
Parameters
- company_idintegerpathrequired
Response · 201 · any[]
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.422Validation failed; `errors` maps each field to messages.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/invitations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/invitationsCreate invitation
Parameters
- company_idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/invitations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/invitations/{id}Delete invitation
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/invitations/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/migration_jobsList migration jobs
Requires the company admin permission. A scoped API token needs migration:read.
Parameters
- company_idintegerpathrequired
- pageintegerqueryPage number, starting at 1.
- per_pageintegerqueryRecords per page.
Request body
- migration_jobobjectrequired
- migration_job.target_project_idinteger | null
- migration_job.source_company_idstring | null
- migration_job.source_project_idstring | null
- migration_job.modestringOne of: dry_run, live.
- migration_job.scopesstring[]One of: directory, rfis, submittals, punch_list, observations, daily_log, documents, prime_contracts, commitments.
- migration_job.use_mockboolean
- migration_job.source_base_urlstring | nullOne of: https://api.procore.com, https://sandbox.procore.com.
- migration_job.source_tokenstring | null
Response · 201 · object[]
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.422Validation failed; `errors` maps each field to messages.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/migration_jobs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"migration_job": {}
}'/rest/v1.0/companies/{company_id}/migration_jobsCreate migration job
Parameters
- company_idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/migration_jobs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/migration_jobs/{id}Get migration job
A scoped API token needs migration:read.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/migration_jobs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/migration_jobs/{id}/runExecute the job
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/migration_jobs/1/run" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/officesList offices
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by main office first, then position and name. Includes inactive rows. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerqueryValues above 1000 are clamped by the REST handler.
- searchstringqueryTrimmed, case-insensitive substring match on name; blank means no filter.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- addressstring | nullrequired
- citystring | nullrequired
- state_codestring | nullrequired
- country_codestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- faxstring | nullrequired
- divisionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- main_officebooleanrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/offices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/officesCreate offices
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Setting main_office=true clears that flag on other company offices. Catalog presence does not grant authorization.
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
- officeobjectrequired
- office.namestringrequiredTrimmed; must contain a non-whitespace character.
- office.addressstring | null
- office.citystring | null
- office.state_codestring | null
- office.country_codestring | null
- office.zipstring | null
- office.phonestring | null
- office.faxstring | null
- office.divisionstring | null
- office.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- office.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
- office.main_officeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
Response · 201 · object
- idintegerrequired
- namestringrequired
- addressstring | nullrequired
- citystring | nullrequired
- state_codestring | nullrequired
- country_codestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- faxstring | nullrequired
- divisionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- main_officebooleanrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/offices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"office": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/offices/{id}Get offices
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- addressstring | nullrequired
- citystring | nullrequired
- state_codestring | nullrequired
- country_codestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- faxstring | nullrequired
- divisionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- main_officebooleanrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/offices/{id}Update offices
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Setting main_office=true clears that flag on other company offices. Catalog presence does not grant authorization.
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
- officeobjectrequired
- office.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- office.addressstring | null
- office.citystring | null
- office.state_codestring | null
- office.country_codestring | null
- office.zipstring | null
- office.phonestring | null
- office.faxstring | null
- office.divisionstring | null
- office.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- office.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
- office.main_officeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
Response · 200 · object
- idintegerrequired
- namestringrequired
- addressstring | nullrequired
- citystring | nullrequired
- state_codestring | nullrequired
- country_codestring | nullrequired
- zipstring | nullrequired
- phonestring | nullrequired
- faxstring | nullrequired
- divisionstring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- main_officebooleanrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"office": {}
}'/rest/v1.0/companies/{company_id}/offices/{id}Delete offices
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/permission_templatesList company permission templates
Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Flat array ordered by name; pagination slices the company template list. No search or type filter. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- pageintegerquery
- per_pageintegerqueryHandler clamps values above 1000.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- project_specificbooleanrequired
- typestringrequiredOne of: global, project_specific.
- permissionsobjectrequired
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/permission_templates" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/permission_templatesCreate company permission template
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Creates a project permission map; when analytics is omitted, creation inserts analytics:read_only. Creation does not assign the template or alter company admin flags. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
- permission_templateobjectrequired
- permission_template.namestringrequiredCreate trims and rejects blank names with 400. PATCH whitespace-only name is accepted but retains the existing name.
- permission_template.project_specificanyBoolean coercion uses JavaScript truthiness. Prefer a JSON boolean; a nonempty string, including "false", becomes true. Defaults false on create.
- permission_template.permissionsobjectTool slug to permission level. PATCH replaces the whole map. Unknown tool keys are accepted; this does not grant company administrator status.
Response · 201 · object
- idintegerrequired
- namestringrequired
- project_specificbooleanrequired
- typestringrequiredOne of: global, project_specific.
- permissionsobjectrequired
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/permission_templates" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"permission_template": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/permission_templates/{id}Read company permission template
Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Returns the stored map, not the effective permissions of a user. Company admin overrides and workspace restrictions are evaluated separately. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
Response · 200 · object
- idintegerrequired
- namestringrequired
- project_specificbooleanrequired
- typestringrequiredOne of: global, project_specific.
- permissionsobjectrequired
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/permission_templates/{id}Edit company permission template
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Supplying permissions replaces the whole map, including when empty; omitted keys lose template grants. Unlike creation, update does not add an analytics default. Changes affect all memberships assigned this template. project_specific is metadata, not a project restriction. This does not change company administrator flags. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
- permission_templateobjectrequired
- permission_template.namestringCreate trims and rejects blank names with 400. PATCH whitespace-only name is accepted but retains the existing name.
- permission_template.project_specificanyBoolean coercion uses JavaScript truthiness. Prefer a JSON boolean; a nonempty string, including "false", becomes true. Defaults false on create.
- permission_template.permissionsobjectTool slug to permission level. PATCH replaces the whole map. Unknown tool keys are accepted; this does not grant company administrator status.
Response · 200 · object
- idintegerrequired
- namestringrequired
- project_specificbooleanrequired
- typestringrequiredOne of: global, project_specific.
- permissionsobjectrequired
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"permission_template": {}
}'/rest/v1.0/companies/{company_id}/permission_templates/{id}Delete company permission template
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Clears this template from all valid company project memberships and permanently deletes it. Invalid retained foreign membership references fail with 400. Members may lose project grants; company administrator flags are not changed. No last-company-admin removal occurs through this operation. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/permission_templates/{id}/assignmentsAssign or clear a project permission template
Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Requires an existing project membership and project, user and template in the authenticated company. The path template must exist even when clearing. Only explicit permission_template_id:null clears; omitted or numeric body values select the path template. Clearing removes template-derived project permissions, while company admin overrides remain. Assignment never creates membership or changes company administrator flags. Catalog presence does not grant access.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
- OS-Company-IdintegerheaderOptional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
- 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
- user_idintegerrequired
- permission_template_idinteger | nullOnly explicit null clears. Omission or any accepted numeric value assigns the template identified by the URL, ignoring that numeric body value.
Response · 200 · object
- project_idintegerrequired
- user_idintegerrequired
- permission_template_idinteger | nullrequired
Errors
400Invalid reference, date interval or retained membership references401Authentication required403Token scope or current company authority denied404Company or resource not found within the authenticated company422Body validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1/assignments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_id": 1,
"user_id": 1
}'/rest/v1.0/companies/{company_id}/project_regionsList project regions
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerqueryValues above 1000 are clamped by the REST handler.
- searchstringqueryTrimmed, case-insensitive substring match on name; blank means no filter.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_regions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/project_regionsCreate project regions
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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_regionobjectrequired
- project_region.namestringrequiredTrimmed; must contain a non-whitespace character.
- project_region.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- project_region.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 201 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/project_regions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_region": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/project_regions/{id}Get project regions
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/project_regions/{id}Update project regions
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- project_regionobjectrequired
- project_region.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- project_region.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- project_region.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 200 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_region": {}
}'/rest/v1.0/companies/{company_id}/project_regions/{id}Delete project regions
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Soft-deletes the record; later list/show omit it. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/project_stages/{id}Get project stages
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- formatted_namestringrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/project_stages/{id}Update project stages
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- project_stageobjectrequired
- project_stage.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- project_stage.formatted_namestring | null
Response · 200 · object
- idintegerrequired
- namestringrequired
- formatted_namestringrequired
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_stage": {}
}'/rest/v1.0/companies/{company_id}/project_stages/{id}Delete project stages
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/project_typesList project types
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerqueryValues above 1000 are clamped by the REST handler.
- searchstringqueryTrimmed, case-insensitive substring match on name; blank means no filter.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_types" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/project_typesCreate project types
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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_typeobjectrequired
- project_type.namestringrequiredTrimmed; must contain a non-whitespace character.
- project_type.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- project_type.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 201 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/project_types" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_type": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/project_types/{id}Get project types
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/project_types/{id}Update project types
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- project_typeobjectrequired
- project_type.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- project_type.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- project_type.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 200 · object
- idintegerrequired
- namestringrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"project_type": {}
}'/rest/v1.0/companies/{company_id}/project_types/{id}Delete project types
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Soft-deletes the record; later list/show omit it. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"/rest/v1.0/companies/{company_id}/scim_connectionsList SCIM connections
A scoped API token needs identity:read.
Parameters
- company_idintegerpathrequired
Response · 201 · any[]
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.422Validation failed; `errors` maps each field to messages.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/scim_connections" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/scim_connectionsCreate SCIM connection
Parameters
- company_idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/scim_connections" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/scim_connections/{id}Delete SCIM connection
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
No documented fields.
Errors
401Missing, invalid or expired API token.403The token or user lacks the required scope or permission.404The record does not exist or belongs to another company.
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/scim_connections/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/tradesList trades
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerqueryValues above 1000 are clamped by the REST handler.
- searchstringqueryTrimmed, case-insensitive substring match on name; blank means no filter.
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- codestring | nullrequired
- csi_codestring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/trades" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/tradesCreate trades
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- tradeobjectrequired
- trade.namestringrequiredTrimmed; must contain a non-whitespace character.
- trade.codestring | null
- trade.csi_codestring | null
- trade.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- trade.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 201 · object
- idintegerrequired
- namestringrequired
- codestring | nullrequired
- csi_codestring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/trades" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"trade": {
"name": "string"
}
}'/rest/v1.0/companies/{company_id}/trades/{id}Get trades
Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.
Parameters
- company_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- codestring | nullrequired
- csi_codestring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/trades/{id}Update trades
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.
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
- tradeobjectrequired
- trade.namestringTrimmed when nonblank; a whitespace-only name is ignored.
- trade.codestring | null
- trade.csi_codestring | null
- trade.activeanyPrefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
- trade.positionanyPrefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
Response · 200 · object
- idintegerrequired
- namestringrequired
- codestring | nullrequired
- csi_codestring | nullrequired
- activebooleanrequired
- positionintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"trade": {}
}'/rest/v1.0/companies/{company_id}/trades/{id}Delete trades
Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.
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
400Malformed JSON, invalid service identity, or a blank name after trimming on create401Valid authentication required403Required token scope or company permission denied; workspace may be read only404Company path does not match the authenticated company, or the record does not exist in that company422Request body validation failed429Rate limit exceeded
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"