Payroll
Review pay runs, post labor costs and prepare payment and filing outputs. Every operation below is generated from the published OpenAPI contract. Paths are company-scoped; read the Accounting API guide for scopes, step-up and permissions, and the Payroll guide for the workflow.
- POST
/rest/v1.0/companies/{company_id}/accounting/payroll/accrualPost the month-end payroll accrual - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/burden_true_upPost the standard-rate burden true-up - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/certified_payrollCertified payroll (WH-347) - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/reissueReissue a printed paper check under a new number - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/voidVoid one check of a posted run - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/codesList payroll codes - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/codesCreate a code - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/employeesList employees - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/employeesCreate an employee - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Show an employee - PATCH
/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Update an employee - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductionsAdd a deduction, match or garnishment - DELETE
/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductions/{deduction_id}End a deduction - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/revealReveal an employee SSN and bank numbers - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/employersList payroll employer entities - PUT
/rest/v1.0/companies/{company_id}/accounting/payroll/employers/{entity_id}Set an employer entity's payroll identity - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/filingsMark a payroll return period filed - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/futa_overrideRequest or approve a provisional FUTA credit reduction override - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/manual_checksEnter a manual (handwritten) check - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsList pay groups - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsCreate a pay group - PATCH
/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groups/{id}Update a pay group - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/pii_rotationRotate payroll PII encryption - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/rate_changesList pay-rate changes - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/rate_changes/{id}Approve or reject a pay-rate change - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/remittancesList payroll liability remittances - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/remittancesRemit a payroll liability - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/remittances/{id}/{decision}Release or reject a pending bank remittance - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/reports/{report}Payroll tax and remittance data - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/runsList pay runs - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/runsCreate a pay run - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}Show a pay run - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run outputs - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run workflow step - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/setupShow payroll setup - PATCH
/rest/v1.0/companies/{company_id}/accounting/payroll/setupUpdate payroll setup - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/union_localsList union locals - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/union_localsCreate a union local - PATCH
/rest/v1.0/companies/{company_id}/accounting/payroll/union_locals/{id}Update a union local - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/union_ratesAdd a CBA rate - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsList wage determinations - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsCreate a wage determination - GET
/rest/v1.0/companies/{company_id}/accounting/payroll/wc_classesList workers' comp classes - POST
/rest/v1.0/companies/{company_id}/accounting/payroll/wc_classesCreate a wc class
Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/accrualPost the month-end payroll accrual
{ month: YYYY-MM }: approved timecards dated in the month that no posted run has paid, at each hourly employee's rate: Dr job labor by job (with hours) / Cr accrued wages (2150 → 2315) on the month's last day, auto-reversing on the 1st. 201 with the entry, 200 with journal_entry_id null when nothing is unpaid, 409 when the month is already accrued; an accrual reversed on its own date (a correction) no longer counts, so the month can be re-run as a new revision. Employer-wide: needs payroll_run on all entities. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- monthstringrequired
Response · 200 · object
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace409Conflict with the current state422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/accrual" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"month": "string"
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/burden_true_upPost the standard-rate burden true-up
{ month: YYYY-MM }: clears the month's Burden Applied balance to the jobs it was applied to (pro rata) or to overhead. Each entity's Burden Applied clears in that entity: one entry per entity with a balance (a pay group posts to its own entity). The job split is net of payroll run reversals and single-check voids posted in the month, so a voided run's or check's job gets no share; a check voided this month from an earlier month's run clears its own residue to that check's jobs (or overhead). 422 when the month holds a reversal of an earlier month's payroll run and that earlier month was already trued up (reconcile the job allocation manually), or when a payroll run in the month was reversed after the month's true-up was posted (reverse that true-up and re-run). Reversed true-ups never block. 201 with the entries (journal_entries lists each with its entity_id; the deprecated journal_entry_id / journal_entry_number name only the first), or 200 with journal_entry_id null when the balance is zero. Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- monthstring
Response · 200 · object
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/burden_true_up" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"month": "string"
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/certified_payrollCertified payroll (WH-347)
Without project_id: prevailing-wage projects and the weeks that need reports. With project_id and week_ending: the WH-347 dataset (json; column 1E is the last four SSN digits), csv, pdf, or the CA DIR eCPR XML (ecpr: V1 layout, accepted by DIR until 2027-01-13; ecpr_v2: XML Schema V2.0 with pwcr=<10-digit DIR registration>; ny_xml: NYS DOL certified payroll XML with prc_number=<10-character PRC>; ecpr and ecpr_v2 carry the full SSN and ny_xml the home address: all need the accounting:write scope and view_payroll_pii, audited, per-user export limit). A week with no work returns the statement of no work performed. Covers every entity: an entity-scoped grant gets 403. Requires the accounting:read scope (accounting:write for ecpr).
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- project_idintegerqueryProject with a wage determination
- week_endingstringqueryYYYY-MM-DD
- formatstringqueryOutput One of: json, csv, pdf, ecpr, ecpr_v2, ny_xml.
- pwcrstringqueryformat=ecpr_v2: the contractor's 10-digit DIR public works registration
- prc_numberstringqueryformat=ny_xml: the project's 10-character NYS DOL Prevailing Rate Case number
Response · 200 · object
- projectsobject[]required
- projects[].idintegerrequired
- projects[].namestringrequired
- projects[].wd_numberstringrequired
- weeksstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422No wage determination, or the data fails WH-347 checks (e.g. apprentice over ratio)429Too many reveals or PII files; retry after the Retry-After seconds.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/certified_payroll" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/reissueReissue a printed paper check under a new number
For a lost or damaged paper check of an approved or posted run: the old number is voided in the bank account's shared check register (positive pay sends the void) and the same net pay takes the next number on that account, issued on date (default today). No journal entry, wage or tax effect: the run's cash line for the check stays outstanding until the new check clears. A voided check or a direct deposit is refused (422); a check whose cash line cleared the bank returns 409. Requires the accounting:write scope and release_payments.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reasonstringrequired
- datestring (date)
Response · 200 · object
- checkobjectrequired
- check.idintegerrequired
- check.employee_idintegerrequired
- check.employee_numberstring | null
- check.employee_namestring | null
- check.ssn_maskedstring | null
- check.bank_account_maskedstring | null
- check.payment_methodstring
- check.pay_datestring
- check.hoursstring
- check.regular_hoursstring
- check.ot_hoursstring
- check.dt_hoursstring
- check.grossstringrequiredDecimal string
- check.employee_taxesstringDecimal string
- check.deductionsstringDecimal string
- check.netstringrequiredDecimal string
- check.employer_coststringDecimal string
- check.taxesobject[]required
- check.deduction_linesobject[]required
- check.exceptionsany[]
- check.explainobject[]
- check.check_numberstring | nullPaper check number from the shared check register
- check.suta_statestring | null
- check.employer_entity_idinteger | nullrequiredEmployer of record: the entity with its own EIN, null = the company employer in payroll setup.
- check.voided_atstring | nullrequired
- check.void_reasonstring | nullrequired
- check.void_entry_idinteger | nullrequired
- voided_check_numberstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace404Not found409Conflict with the current state422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/checks/1/reissue" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reason": "string"
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/voidVoid one check of a posted run
Reverses only this check's journal lines and job cost hours (source payroll_check_void), dated date (default today, never before the pay date or in a filed quarter). The voider did not prepare, edit or calculate the run. A direct deposit whose NACHA file exists needs confirm_paid. A paper check whose cash line cleared the bank (bank-matched, or cleared or reconciled in a reconciliation) returns 409. Standard-rate burden is reversed at the rate and per-check share captured at approval, not the current setup. Payroll reports keep the check on its pay date and add a negative row on the void date. reissue creates a correction run (draft) with the check's time and earnings, paid on reissue_pay_date. A run with a voided check can no longer be voided whole. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reasonstringrequired
- datestring (date)
- confirm_paidboolean
- reissueboolean
- reissue_pay_datestring (date)
Response · 200 · object
- checkobjectrequired
- check.idintegerrequired
- check.employee_idintegerrequired
- check.employee_numberstring | null
- check.employee_namestring | null
- check.ssn_maskedstring | null
- check.bank_account_maskedstring | null
- check.payment_methodstring
- check.pay_datestring
- check.hoursstring
- check.regular_hoursstring
- check.ot_hoursstring
- check.dt_hoursstring
- check.grossstringrequiredDecimal string
- check.employee_taxesstringDecimal string
- check.deductionsstringDecimal string
- check.netstringrequiredDecimal string
- check.employer_coststringDecimal string
- check.taxesobject[]required
- check.deduction_linesobject[]required
- check.exceptionsany[]
- check.explainobject[]
- check.check_numberstring | nullPaper check number from the shared check register
- check.suta_statestring | null
- check.employer_entity_idinteger | nullrequiredEmployer of record: the entity with its own EIN, null = the company employer in payroll setup.
- check.voided_atstring | nullrequired
- check.void_reasonstring | nullrequired
- check.void_entry_idinteger | nullrequired
- reissue_runobject | nullrequired
- reissue_run.idintegerrequired
- reissue_run.numberstringrequired
- reissue_run.pay_group_idintegerrequired
- reissue_run.pay_group_codestring | nullrequired
- reissue_run.period_startstringrequired
- reissue_run.period_endstringrequired
- reissue_run.pay_datestringrequired
- reissue_run.statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- reissue_run.revisionintegerrequired
- reissue_run.gross_totalstringrequiredDecimal string
- reissue_run.employee_taxesstringrequiredDecimal string
- reissue_run.deductions_totalstringrequiredDecimal string
- reissue_run.net_totalstringrequiredDecimal string
- reissue_run.employer_coststringrequiredDecimal string
- reissue_run.check_countinteger | nullrequired
- reissue_run.exceptionsobject[]required
- reissue_run.prepared_by_idintegerrequired
- reissue_run.approved_by_idinteger | nullrequired
- reissue_run.approved_atstring | nullrequired
- reissue_run.posted_atstring | nullrequired
- reissue_run.journal_entry_idinteger | nullrequired
- reissue_run.void_reasonstring | nullrequired
- reissue_run.run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- reissue_run.last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace404Not found409Conflict with the current state422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/checks/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reason": "string"
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/codesList payroll codes
Earning, deduction, benefit and employer-tax codes. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- kindstringrequiredOne of: earning, deduction, benefit, employer_tax.
- codestringrequired
- namestringrequired
- tax_treatmentstring | nullrequiredEarnings: regular | supplemental (flat-rate FIT) | nontaxable (paid, not wages). Deductions: the deduction type.
- calc_methodstringrequired
- ratestring | nullrequired
- is_activebooleanrequired
- include_in_regular_ratebooleanrequiredEarnings: a nondiscretionary bonus counted in the FLSA regular rate (raises the overtime of the weeks the run covers, 29 CFR 778.208-.210).
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/codes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/codesCreate a code
Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- codeobjectrequired
Response · 201 · object
- idintegerrequired
- kindstringrequiredOne of: earning, deduction, benefit, employer_tax.
- codestringrequired
- namestringrequired
- tax_treatmentstring | nullrequiredEarnings: regular | supplemental (flat-rate FIT) | nontaxable (paid, not wages). Deductions: the deduction type.
- calc_methodstringrequired
- ratestring | nullrequired
- is_activebooleanrequired
- include_in_regular_ratebooleanrequiredEarnings: a nondiscretionary bonus counted in the FLSA regular rate (raises the overtime of the weeks the run covers, 29 CFR 778.208-.210).
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/codes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"code": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/employeesList employees
PII masked (***-**-1234, ****6789). Filters: filters[status], filters[pay_group_id], search. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerqueryPage (1-based)
- per_pageintegerqueryPage size (max 1000)
- searchstringqueryName or number
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- first_namestringrequired
- last_namestringrequired
- middle_initialstring | null
- user_idinteger | null
- workforce_person_idinteger | null
- statusstring
- hire_datestring | null
- term_datestring | null
- pay_group_idintegerrequired
- pay_group_codestring | null
- pay_typestringrequiredOne of: hourly, salary.
- hourly_ratestring | null
- salary_per_periodstring | nullDecimal string
- salary_allocationarray | null
- union_local_idinteger | null
- home_local_codestring | null
- classificationstring | null
- worker_typestringOne of: J, RA.
- apprentice_levelstring | null
- plan_credit_per_hourstring | null
- wc_class_codestring | null
- resident_statestring
- work_statestring
- w4object | null
- state_w4object | null
- birth_yearinteger | null
- addressstring | null
- citystring | null
- statestring | null
- zipstring | null
- payment_methodstring
- ssn_maskedstring | nullrequiredMasked; full SSN only via ?reveal=true
- bank_account_maskedstring | nullrequired
- bank_account_typestring | null
- has_bank_routingboolean
- deductionsobject[]
- deductions[].idintegerrequired
- deductions[].kindstringrequiredOne of: deduction, garnishment, match.
- deductions[].codestringrequired
- deductions[].typestringrequired
- deductions[].amountstring | nullrequiredDecimal string
- deductions[].pct_of_grossstring | nullrequired
- deductions[].paramsobject | nullrequired
- deductions[].is_activebooleanrequired
- revealedobjectOnly with ?reveal=true and view_payroll_pii; audited
- revealed.ssnstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- resident_localitystring | null
- reciprocity_statesstring[]
- pending_rate_change_idinteger | nullPATCH only: pay-rate fields become this pending rate change
- pending_bank_change_idinteger | nullPATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
- flsa_exemptbooleanrequiredSalaried only: false = non-exempt, overtime on hours over 40 at 1.5 × weekly salary ÷ 40. A pay-rate field: changes wait for a second person.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/employeesCreate an employee
ssn, bank_routing_number and bank_account_number are write-only: encrypted at rest (AES-256-GCM), never returned. Audit rows carry field names only. Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- employeeobjectrequired
Response · 201 · object
- idintegerrequired
- numberstringrequired
- first_namestringrequired
- last_namestringrequired
- middle_initialstring | null
- user_idinteger | null
- workforce_person_idinteger | null
- statusstring
- hire_datestring | null
- term_datestring | null
- pay_group_idintegerrequired
- pay_group_codestring | null
- pay_typestringrequiredOne of: hourly, salary.
- hourly_ratestring | null
- salary_per_periodstring | nullDecimal string
- salary_allocationarray | null
- union_local_idinteger | null
- home_local_codestring | null
- classificationstring | null
- worker_typestringOne of: J, RA.
- apprentice_levelstring | null
- plan_credit_per_hourstring | null
- wc_class_codestring | null
- resident_statestring
- work_statestring
- w4object | null
- state_w4object | null
- birth_yearinteger | null
- addressstring | null
- citystring | null
- statestring | null
- zipstring | null
- payment_methodstring
- ssn_maskedstring | nullrequiredMasked; full SSN only via ?reveal=true
- bank_account_maskedstring | nullrequired
- bank_account_typestring | null
- has_bank_routingboolean
- deductionsobject[]
- deductions[].idintegerrequired
- deductions[].kindstringrequiredOne of: deduction, garnishment, match.
- deductions[].codestringrequired
- deductions[].typestringrequired
- deductions[].amountstring | nullrequiredDecimal string
- deductions[].pct_of_grossstring | nullrequired
- deductions[].paramsobject | nullrequired
- deductions[].is_activebooleanrequired
- revealedobjectOnly with ?reveal=true and view_payroll_pii; audited
- revealed.ssnstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- resident_localitystring | null
- reciprocity_statesstring[]
- pending_rate_change_idinteger | nullPATCH only: pay-rate fields become this pending rate change
- pending_bank_change_idinteger | nullPATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
- flsa_exemptbooleanrequiredSalaried only: false = non-exempt, overtime on hours over 40 at 1.5 × weekly salary ÷ 40. A pay-rate field: changes wait for a second person.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"employee": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Show an employee
With deductions. Deprecated ?reveal=true (use POST employees/{id}/reveal, which takes a reason and keeps the request out of URLs and access logs) adds the decrypted SSN and bank numbers: needs the accounting:write scope and view_payroll_pii, writes an audit entry (the app's reveal is a POST server action with a required reason, stored in the audit event; it is never a URL parameter), and counts toward the per-user export limit (429). Employees outside the grant's entities (by pay group posting entity) are 404. Requires the accounting:read scope (accounting:write with reveal=true).
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- revealbooleanqueryDecrypt PII (view_payroll_pii; audited)
Response · 200 · object
- idintegerrequired
- numberstringrequired
- first_namestringrequired
- last_namestringrequired
- middle_initialstring | null
- user_idinteger | null
- workforce_person_idinteger | null
- statusstring
- hire_datestring | null
- term_datestring | null
- pay_group_idintegerrequired
- pay_group_codestring | null
- pay_typestringrequiredOne of: hourly, salary.
- hourly_ratestring | null
- salary_per_periodstring | nullDecimal string
- salary_allocationarray | null
- union_local_idinteger | null
- home_local_codestring | null
- classificationstring | null
- worker_typestringOne of: J, RA.
- apprentice_levelstring | null
- plan_credit_per_hourstring | null
- wc_class_codestring | null
- resident_statestring
- work_statestring
- w4object | null
- state_w4object | null
- birth_yearinteger | null
- addressstring | null
- citystring | null
- statestring | null
- zipstring | null
- payment_methodstring
- ssn_maskedstring | nullrequiredMasked; full SSN only via ?reveal=true
- bank_account_maskedstring | nullrequired
- bank_account_typestring | null
- has_bank_routingboolean
- deductionsobject[]
- deductions[].idintegerrequired
- deductions[].kindstringrequiredOne of: deduction, garnishment, match.
- deductions[].codestringrequired
- deductions[].typestringrequired
- deductions[].amountstring | nullrequiredDecimal string
- deductions[].pct_of_grossstring | nullrequired
- deductions[].paramsobject | nullrequired
- deductions[].is_activebooleanrequired
- revealedobjectOnly with ?reveal=true and view_payroll_pii; audited
- revealed.ssnstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- resident_localitystring | null
- reciprocity_statesstring[]
- pending_rate_change_idinteger | nullPATCH only: pay-rate fields become this pending rate change
- pending_bank_change_idinteger | nullPATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
- flsa_exemptbooleanrequiredSalaried only: false = non-exempt, overtime on hours over 40 at 1.5 × weekly salary ÷ 40. A pay-rate field: changes wait for a second person.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found429Too many reveals or PII files; retry after the Retry-After seconds.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
PATCH/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Update an employee
Partial update; rate changes are audited as rate_changed. Needs payroll_run. Requires the accounting:write scope. Pay-rate fields (pay_type, hourly_rate, salary_per_period, classification, union_local_id, plan_credit_per_hour) are not applied: they become a pending rate change (pending_rate_change_id) that a different user approves. Bank fields (bank_routing_number, bank_account_number, bank_account_type) likewise become a pending bank change (pending_bank_change_id).
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- employeeobjectrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- first_namestringrequired
- last_namestringrequired
- middle_initialstring | null
- user_idinteger | null
- workforce_person_idinteger | null
- statusstring
- hire_datestring | null
- term_datestring | null
- pay_group_idintegerrequired
- pay_group_codestring | null
- pay_typestringrequiredOne of: hourly, salary.
- hourly_ratestring | null
- salary_per_periodstring | nullDecimal string
- salary_allocationarray | null
- union_local_idinteger | null
- home_local_codestring | null
- classificationstring | null
- worker_typestringOne of: J, RA.
- apprentice_levelstring | null
- plan_credit_per_hourstring | null
- wc_class_codestring | null
- resident_statestring
- work_statestring
- w4object | null
- state_w4object | null
- birth_yearinteger | null
- addressstring | null
- citystring | null
- statestring | null
- zipstring | null
- payment_methodstring
- ssn_maskedstring | nullrequiredMasked; full SSN only via ?reveal=true
- bank_account_maskedstring | nullrequired
- bank_account_typestring | null
- has_bank_routingboolean
- deductionsobject[]
- deductions[].idintegerrequired
- deductions[].kindstringrequiredOne of: deduction, garnishment, match.
- deductions[].codestringrequired
- deductions[].typestringrequired
- deductions[].amountstring | nullrequiredDecimal string
- deductions[].pct_of_grossstring | nullrequired
- deductions[].paramsobject | nullrequired
- deductions[].is_activebooleanrequired
- revealedobjectOnly with ?reveal=true and view_payroll_pii; audited
- revealed.ssnstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- resident_localitystring | null
- reciprocity_statesstring[]
- pending_rate_change_idinteger | nullPATCH only: pay-rate fields become this pending rate change
- pending_bank_change_idinteger | nullPATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
- flsa_exemptbooleanrequiredSalaried only: false = non-exempt, overtime on hours over 40 at 1.5 × weekly salary ÷ 40. A pay-rate field: changes wait for a second person.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"employee": {}
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductionsAdd a deduction, match or garnishment
kind deduction (pretax_401k, roth_401k, section125, hsa, post_tax, union_dues), garnishment (child_support, federal_tax_levy, state_tax_levy, bankruptcy, student_loan, creditor) or match (params.tiers). Needs payroll_run. One active row per code across every kind (a match cannot share a deduction's code, so use e.g. 401K and 401K_MATCH): a second active row with the same code is 409 (end the first). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- deductionobjectrequired
Response · 201 · object
- idintegerrequired
- kindstringrequiredOne of: deduction, garnishment, match.
- codestringrequired
- typestringrequired
- amountstring | nullrequiredDecimal string
- pct_of_grossstring | nullrequired
- paramsobject | nullrequired
- is_activebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found409The employee already has an active deduction with this code (end it first), or the Idempotency-Key is in use.422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees/1/deductions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"deduction": {}
}'Accounting / Payroll
DELETE/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductions/{deduction_id}End a deduction
Marks it inactive (kept for history). Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- deduction_idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees/1/deductions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/revealReveal an employee SSN and bank numbers
{ reason }: the employee with the decrypted SSN and bank numbers (revealed). Needs the accounting:write scope and view_payroll_pii; writes a pii_revealed audit entry with the reason; counts toward the per-user export limit (429). Cache-Control: no-store. Employees outside the grant entities are 404. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- first_namestringrequired
- last_namestringrequired
- middle_initialstring | null
- user_idinteger | null
- workforce_person_idinteger | null
- statusstring
- hire_datestring | null
- term_datestring | null
- pay_group_idintegerrequired
- pay_group_codestring | null
- pay_typestringrequiredOne of: hourly, salary.
- hourly_ratestring | null
- salary_per_periodstring | nullDecimal string
- salary_allocationarray | null
- union_local_idinteger | null
- home_local_codestring | null
- classificationstring | null
- worker_typestringOne of: J, RA.
- apprentice_levelstring | null
- plan_credit_per_hourstring | null
- wc_class_codestring | null
- resident_statestring
- work_statestring
- w4object | null
- state_w4object | null
- birth_yearinteger | null
- addressstring | null
- citystring | null
- statestring | null
- zipstring | null
- payment_methodstring
- ssn_maskedstring | nullrequiredMasked; full SSN only via ?reveal=true
- bank_account_maskedstring | nullrequired
- bank_account_typestring | null
- has_bank_routingboolean
- deductionsobject[]
- deductions[].idintegerrequired
- deductions[].kindstringrequiredOne of: deduction, garnishment, match.
- deductions[].codestringrequired
- deductions[].typestringrequired
- deductions[].amountstring | nullrequiredDecimal string
- deductions[].pct_of_grossstring | nullrequired
- deductions[].paramsobject | nullrequired
- deductions[].is_activebooleanrequired
- revealedobjectOnly with ?reveal=true and view_payroll_pii; audited
- revealed.ssnstring | nullrequired
- revealed.bank_routing_numberstring | nullrequired
- revealed.bank_account_numberstring | nullrequired
- resident_localitystring | null
- reciprocity_statesstring[]
- pending_rate_change_idinteger | nullPATCH only: pay-rate fields become this pending rate change
- pending_bank_change_idinteger | nullPATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
- flsa_exemptbooleanrequiredSalaried only: false = non-exempt, overtime on hours over 40 at 1.5 × weekly salary ÷ 40. A pay-rate field: changes wait for a second person.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation error (reason: 3 to 500 characters)429Too many reveals or PII files; retry after the Retry-After seconds.
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employees/1/reveal" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reason": "string"
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/employersList payroll employer entities
Entities with their own EIN that employ: state withholding / UI account numbers and the ACH origin (account masked). Checks of a pay group whose posting entity has an EIN other than payroll setup's carry that entity as employer_entity_id. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- entity_idintegerrequired
- state_account_idsobjectrequired
- ach_odfi_routingstring | nullrequired
- ach_bank_namestring | nullrequired
- ach_account_maskedstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employers" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
PUT/rest/v1.0/companies/{company_id}/accounting/payroll/employers/{entity_id}Set an employer entity's payroll identity
Upsert state_account_ids, ach_odfi_routing, ach_bank_name and ach_account_number (write-only, encrypted) for an entity with an EIN. Employer-wide: needs payroll_run on all entities. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- entity_idintegerpathrequired
Request body
- employerobjectrequired
- employer.state_account_idsobject | null
- employer.ach_odfi_routingstring | null
- employer.ach_bank_namestring | null
- employer.ach_account_numberstring | null
Response · 200 · object
- entity_idintegerrequired
- state_account_idsobjectrequired
- ach_odfi_routingstring | nullrequired
- ach_bank_namestring | nullrequired
- ach_account_maskedstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X PUT "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/employers/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"employer": {}
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/filingsMark a payroll return period filed
{ period: "2026-Q1" (941) | "2026-Q1-UI" (state UI report) | "2026" (W-2 / 940), filed?: true }. A void of posted payroll may not be dated into a filed period (409); voiding payroll paid in a filed quarter or year records an amended_return_required audit event (Form 941-X / W-2c) and form_941 lists corrections_required. filed=false reopens the period and also needs close_period (a payroll runner alone cannot reopen a filed return). Needs payroll_run for every entity. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- periodstringrequired
- filedboolean
Response · 200 · object
- filed_periodsstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace422Validation error or payroll setup missing
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/filings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"period": "string"
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/futa_overrideRequest or approve a provisional FUTA credit reduction override
While the year's FUTA credit reduction is DOL's provisional list (final after November 10), Form 940 returns 422 "credit reduction provisional". { action: "request", year, reason } by one payroll runner, then { action: "approve", year } by a different one (403 for the requester). A new request replaces the old one; a change to the provisional rates voids the approval. 422 when the year is not provisional. Audited. Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- actionstringrequiredOne of: request, approve.
- yearintegerrequired
- reasonstringRequired for request (3-500 chars)
Response · 200 · object
- yearinteger
- ratesobject
- reasonstring
- requested_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null
- statusstringOne of: pending, approved.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/futa_override" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"action": "request",
"year": 1
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/manual_checksEnter a manual (handwritten) check
Gross, taxes and deductions as written become a one-check run of run_type manual, status calculated. Net = gross − employee taxes − deductions (a given net must match). A second person approves it and it posts like any run; it is never recalculated (calculate returns 422). Its accounts are the payroll account map's job labor (5000), overhead labor (6000) and net pay (1010) keys, as for any run. check_number requires bank_account_id: the check is entered in that account's shared check register (positive pay sends it), the account must be the checking account on the net pay GL account, and a number already used on the account returns 409. Idempotent on request_key or the Idempotency-Key header (one run and one check per key). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- manual_checkobjectrequired
- manual_check.pay_group_idintegerrequired
- manual_check.employee_idintegerrequired
- manual_check.pay_datestring (date)required
- manual_check.period_startstring (date)
- manual_check.period_endstring (date)
- manual_check.check_numberstring
- manual_check.project_idinteger | null
- manual_check.cost_code_idinteger | null
- manual_check.memostring | null
- manual_check.grossstringrequired
- manual_check.netstring
- manual_check.taxesobject[]
- manual_check.taxes[].codestringrequiredFIT, SS, MED, ADDL_MED, FUTA, SUTA, SIT, LOCAL, SDI …
- manual_check.taxes[].payerstringrequiredOne of: employee, employer.
- manual_check.taxes[].jurisdictionstring
- manual_check.taxes[].amountstringrequired
- manual_check.taxes[].wagesstring
- manual_check.deductionsobject[]
- manual_check.deductions[].codestringrequired
- manual_check.deductions[].typestringrequiredOne of: pretax_401k, roth_401k, section125, hsa, post_tax, union_dues.
- manual_check.deductions[].amountstringrequired
- manual_check.request_keystringRetry key: a repeat with the same key returns the first run (201, same body); the same key with any other field changed (employee, pay group, dates, gross, taxes, deductions, net, check number, job, memo) is 409. An Idempotency-Key header fills a missing request_key.
- manual_check.bank_account_idintegerRequired with check_number: the checking account the check was written on.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- pay_group_idintegerrequired
- pay_group_codestring | nullrequired
- period_startstringrequired
- period_endstringrequired
- pay_datestringrequired
- statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- revisionintegerrequired
- gross_totalstringrequiredDecimal string
- employee_taxesstringrequiredDecimal string
- deductions_totalstringrequiredDecimal string
- net_totalstringrequiredDecimal string
- employer_coststringrequiredDecimal string
- check_countinteger | nullrequired
- exceptionsobject[]required
- exceptions[].keystringrequired
- exceptions[].codestringrequired
- exceptions[].severitystringrequiredOne of: error, warning, info.
- exceptions[].messagestringrequired
- exceptions[].employee_idinteger | nullrequired
- exceptions[].acknowledgedbooleanrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring | nullrequired
- posted_atstring | nullrequired
- journal_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace404Not found409The check number is already used on the bank account, or the request_key (or Idempotency-Key) was already used for a different manual check, or that request is still running.422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/manual_checks" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"manual_check": {
"pay_group_id": 1,
"employee_id": 1,
"pay_date": "2026-11-01",
"gross": "string"
}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsList pay groups
Pay groups with frequency and overtime rule set (FLSA, CA, AK, NV, CO). Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- frequencystringrequiredOne of: weekly, biweekly, semimonthly, monthly.
- ot_rule_setstringrequired
- is_activebooleanrequired
- employee_countinteger | nullrequired
- ot_methodstringrequiredrate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
- workweek_anchorstring | null (date)requiredAny first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
- entity_idinteger | nullrequiredPosting entity for the group's runs (default entity when null)
- dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/pay_groups" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsCreate a pay group
Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- pay_groupobjectrequired
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- frequencystringrequiredOne of: weekly, biweekly, semimonthly, monthly.
- ot_rule_setstringrequired
- is_activebooleanrequired
- employee_countinteger | nullrequired
- ot_methodstringrequiredrate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
- workweek_anchorstring | null (date)requiredAny first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
- entity_idinteger | nullrequiredPosting entity for the group's runs (default entity when null)
- dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/pay_groups" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"pay_group": {}
}'Accounting / Payroll
PATCH/rest/v1.0/companies/{company_id}/accounting/payroll/pay_groups/{id}Update a pay group
Name, frequency, OT rule set, OT method (weighted_average | rate_in_effect) or is_active. Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- pay_groupobject
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- frequencystringrequiredOne of: weekly, biweekly, semimonthly, monthly.
- ot_rule_setstringrequired
- is_activebooleanrequired
- employee_countinteger | nullrequired
- ot_methodstringrequiredrate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
- workweek_anchorstring | null (date)requiredAny first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
- entity_idinteger | nullrequiredPosting entity for the group's runs (default entity when null)
- dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/pay_groups/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"pay_group": {}
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/pii_rotationRotate payroll PII encryption
Re-encrypts SSNs, employee and pending bank numbers and the ACH account still under an older key version (or the legacy format) with the current key, bound to its row (company, employee, field). Refused (409) while any run is approved. Returns counts only. Needs payroll_run + view_payroll_pii; audited. Requires the accounting:write scope. Also rewrites decided bank-change rows, employer-entity ACH accounts (AcctPayrollEmployer), employee ACH prenote records and employee NOC corrections. remaining counts the company's rows, vendor and banking included, still holding a value under an older key id or the legacy format: drop an old key id only once it is 0.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- rotatedintegerrequired
- remainingintegerrequiredRows still under an older key id or the legacy format, company-wide.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace409An approved run holds a hash of the current ciphertext
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/pii_rotation" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/rate_changesList pay-rate changes
Newest first. Paginated (page/per_page; Total and Link headers). Requested by one person, approved or rejected by another (SoD). Filters: employee_id, status. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- employee_idintegerquery
- statusstringqueryOne of: pending, approved, rejected.
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- employee_idintegerrequired
- kindstringrequiredbank: a bank-account change; changes holds masked values only (****1234). Approval sets the employee's bank_changed_at, and the next calculation raises a bank_changed warning to acknowledge. One of: rate, bank.
- changesobjectrequired
- statusstringrequiredOne of: pending, approved, rejected.
- requested_by_idintegerrequired
- approved_by_idinteger | nullrequired
- decided_atstring | nullrequired
- reasonstring | nullrequired
- created_atstringrequired
- effective_datestring | nullRate in effect from this date (time on earlier dates pays the previous rate)
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/rate_changes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/rate_changes/{id}Approve or reject a pay-rate change
{ approve, reason }. Approving applies the rates. 403 when the approver requested the change or prepared an open run for the employee's pay group. Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- approveboolean
- reasonstring | null
Response · 200 · object
- idintegerrequired
- employee_idintegerrequired
- kindstringrequiredbank: a bank-account change; changes holds masked values only (****1234). Approval sets the employee's bank_changed_at, and the next calculation raises a bank_changed warning to acknowledge. One of: rate, bank.
- changesobjectrequired
- statusstringrequiredOne of: pending, approved, rejected.
- requested_by_idintegerrequired
- approved_by_idinteger | nullrequired
- decided_atstring | nullrequired
- reasonstring | nullrequired
- created_atstringrequired
- effective_datestring | nullRate in effect from this date (time on earlier dates pays the previous rate)
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/rate_changes/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"approve": true,
"reason": "string"
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/remittancesList payroll liability remittances
Newest first. Paginated (page/per_page; Total and Link headers). Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- request_keystringrequired
- account_keystringrequiredEngine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
- account_idintegerrequired
- entity_idintegerrequired
- methodstringrequiredOne of: bank, ap_bill.
- bank_account_idinteger | null
- ap_bill_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- amountstringrequiredDecimal string
- through_datestringrequired
- paid_datestringrequired
- memostring | null
- created_atstring
- statusstringrequiredpending_approval: a bank payment at or above the journal approval threshold waiting for a second releaser (no journal yet) One of: posted, pending_approval, rejected.
- created_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/remittances" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/remittancesRemit a payroll liability
{ remittance: { request_key, account_key, amount, through_date, paid_date, method: bank | ap_bill, bank_account_id (bank) | vendor_id (ap_bill), entity_id?, memo } }. entity_id defaults to the bank account's entity, else the company default; the liability is cleared, and the open balance checked, in that entity (the actor needs access to it; a bank account of another entity is 422). bank moves cash: it needs release_payments (403 without it) and posts Dr liability / Cr the bank's GL account (shown in the bank register), or, at or above the journal approval threshold (settings require_approval_above), is saved as status pending_approval with no journal until a different user releases it (POST remittances/{id}/approve); ap_bill drafts an AP bill coded to the liability. The amount may not exceed the open balance through through_date less unposted remittance bills and pending bank remittances (422). Idempotent on request_key (a replay returns the first remittance; a different body with the same key is 409). Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- remittanceobjectrequired
Response · 201 · object
- idintegerrequired
- request_keystringrequired
- account_keystringrequiredEngine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
- account_idintegerrequired
- entity_idintegerrequired
- methodstringrequiredOne of: bank, ap_bill.
- bank_account_idinteger | null
- ap_bill_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- amountstringrequiredDecimal string
- through_datestringrequired
- paid_datestringrequired
- memostring | null
- created_atstring
- statusstringrequiredpending_approval: a bank payment at or above the journal approval threshold waiting for a second releaser (no journal yet) One of: posted, pending_approval, rejected.
- created_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace404Not found409Request key reused for a different remittance422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/remittances" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"remittance": {}
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/remittances/{id}/{decision}Release or reject a pending bank remittance
approve posts the bank remittance journal (Dr liability / Cr bank GL), dated its paid date; reject leaves it rejected with no journal. Needs payroll_run and release_payments; the creator cannot approve their own remittance (403). Only pending_approval remittances (409 otherwise). Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- decisionstringpathrequiredOne of: approve, reject.
Response · 200 · object
- idintegerrequired
- request_keystringrequired
- account_keystringrequiredEngine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
- account_idintegerrequired
- entity_idintegerrequired
- methodstringrequiredOne of: bank, ap_bill.
- bank_account_idinteger | null
- ap_bill_idinteger | nullrequired
- journal_entry_idinteger | nullrequired
- amountstringrequiredDecimal string
- through_datestringrequired
- paid_datestringrequired
- memostring | null
- created_atstring
- statusstringrequiredpending_approval: a bank payment at or above the journal approval threshold waiting for a second releaser (no journal yet) One of: posted, pending_approval, rejected.
- created_by_idinteger
- approved_by_idinteger | null
- approved_atstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace404Not found409Not waiting for release, or decided concurrently422Validation or workflow error (closed period)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/remittances/1/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/reports/{report}Payroll tax and remittance data
From posted runs. form_941 (year, quarter), form_940 (year; credit_reduction {provisional, rates, override} with Schedule A from the year's FUTA credit reduction list; 422 "credit reduction provisional" while DOL's list is provisional and wages fall in a listed state, until an approved futa_override; 422 when no list is loaded for the year and wages fall in a state on any loaded list), w2 (year; format=efw2 supports domestic tax years 2024-2026 and needs the accounting:write scope and view_payroll_pii, audited; BSO/contact inputs required; provisional requests rejected; incomplete or unsupported populated payroll source fields return 422), union_remittance (month YYYY-MM: per fund, remit-to local, employees with hours and amounts; hours and gross are the CBA rate group's), union_local_remittance (month YYYY-MM, optional local; format=json|csv: one report per remit-to local with each employee's hours, gross, employer fringe by fund, dues actually withheld and the amount to remit, plus a reconciliation of the month's fringe (engine key 2120) and dues (2124) to the payroll journal and the GL accounts they map to: report vs engine and engine vs GL payroll postings must both be 0.00 for an account to tie; opening, other activity (remittances) and closing balances), state_ui (year, quarter; rows carry employee_tax: NJ/PA/AK employee unemployment withheld; the csv adds an employee_sui column). Requires the accounting:read scope. deposit_calendar (year, quarter): each liability date's 941 deposit due date under the monthly or semiweekly schedule (next-day for $100k). w2 format=pdf: employee W-2 copies (view_payroll_pii, audited). w3 (year): W-3 transmittal totals. w2 and w3 boxes include W (box 12 code W: HSA contributions through the cafeteria plan). state_ui accepts state=XX; format=csv returns the state SUI wage file (accounting:write scope and view_payroll_pii, audited). Tax filings cover every entity of the employer: an entity-scoped grant gets 403. EFW2 and the SUI file count toward the per-user export limit (429). form_941 also returns filed (the quarter is marked filed) and corrections_required ([{ run, voided_on, form: 941-X }]: posted payroll of the filed quarter voided after it ended). Reports use effective dates: a run voided after posting stays in its pay-date period, and its void adds negative rows on the void (reversal) date. deposit_calendar counts only posted (paid) remittances toward remitted; a deposit period whose net liability is negative (a void) has amount 0.00 and the rest as credit. w2 rows carry correction_required: "W-2c" when a void of prior-year pay leaves a box negative (left out of EFW2, W-3 and the PDF); state_ui rows carry correction_required: "amended_report" likewise (left out of the SUI file). form_940 caps FUTA wages on cumulative wages, so a void gives back only the wages it had made taxable.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- reportstringpathrequiredOne of: form_941, form_940, w2, union_remittance, union_local_remittance, state_ui, deposit_calendar, w3.
- yearintegerqueryTax year
- quarterintegerquery1-4
- monthstringqueryYYYY-MM
- formatstringqueryw2: json | efw2 | pdf; state_ui: json | csv; union_local_remittance: json | csv
- localstringqueryunion_local_remittance: one remit-to local code
- bso_user_idstringqueryRequired for efw2: attesting BSO user ID
- contact_namestringqueryRequired for efw2
- contact_phonestringqueryRequired for efw2: ten-digit domestic telephone (formatting allowed)
- contact_emailstring (email)queryRequired for efw2: printable ASCII email
- statestringquerystate_ui: two-letter state
- employer_entity_idintegerqueryform_941, form_940, deposit_calendar, w3, state_ui: the employer (EIN) to file for. 0 = the company employer in payroll setup, an entity id = that entity. Omitted: the only employer that paid in the period (422 when several did). W-2 rows carry employer_entity_id: an employee paid by two EINs gets two W-2s.
Response · 200 · object | object[]
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Unsupported year/provisional option, invalid identity/contact, missing qualified-overtime detail, unsupported populated W-2 data, HSA contributions or unclassified retirement-plan source429Too many reveals or PII files; retry after the Retry-After seconds.
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/reports/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/runsList pay runs
Newest pay date first. Filters: filters[status], filters[pay_group_id]. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerqueryPage (1-based)
- per_pageintegerqueryPage size (max 1000)
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- pay_group_idintegerrequired
- pay_group_codestring | nullrequired
- period_startstringrequired
- period_endstringrequired
- pay_datestringrequired
- statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- revisionintegerrequired
- gross_totalstringrequiredDecimal string
- employee_taxesstringrequiredDecimal string
- deductions_totalstringrequiredDecimal string
- net_totalstringrequiredDecimal string
- employer_coststringrequiredDecimal string
- check_countinteger | nullrequired
- exceptionsobject[]required
- exceptions[].keystringrequired
- exceptions[].codestringrequired
- exceptions[].severitystringrequiredOne of: error, warning, info.
- exceptions[].messagestringrequired
- exceptions[].employee_idinteger | nullrequired
- exceptions[].acknowledgedbooleanrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring | nullrequired
- posted_atstring | nullrequired
- journal_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/runsCreate a pay run
pay_group_id, period_start, period_end, pay_date. Refuses a period that overlaps another open run of the group. Imports approved timecards unless import_time is false. Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- pay_runobjectrequired
Response · 201 · object
- idintegerrequired
- numberstringrequired
- pay_group_idintegerrequired
- pay_group_codestring | nullrequired
- period_startstringrequired
- period_endstringrequired
- pay_datestringrequired
- statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- revisionintegerrequired
- gross_totalstringrequiredDecimal string
- employee_taxesstringrequiredDecimal string
- deductions_totalstringrequiredDecimal string
- net_totalstringrequiredDecimal string
- employer_coststringrequiredDecimal string
- check_countinteger | nullrequired
- exceptionsobject[]required
- exceptions[].keystringrequired
- exceptions[].codestringrequired
- exceptions[].severitystringrequiredOne of: error, warning, info.
- exceptions[].messagestringrequired
- exceptions[].employee_idinteger | nullrequired
- exceptions[].acknowledgedbooleanrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring | nullrequired
- posted_atstring | nullrequired
- journal_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"pay_run": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}Show a pay run
Checks (PII masked) with taxes and deductions, and time lines. ?explain=true adds each check's calculation trace. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- explainbooleanqueryInclude calculation traces
Response · 200 · object
- idintegerrequired
- numberstringrequired
- pay_group_idintegerrequired
- pay_group_codestring | nullrequired
- period_startstringrequired
- period_endstringrequired
- pay_datestringrequired
- statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- revisionintegerrequired
- gross_totalstringrequiredDecimal string
- employee_taxesstringrequiredDecimal string
- deductions_totalstringrequiredDecimal string
- net_totalstringrequiredDecimal string
- employer_coststringrequiredDecimal string
- check_countinteger | nullrequired
- exceptionsobject[]required
- exceptions[].keystringrequired
- exceptions[].codestringrequired
- exceptions[].severitystringrequiredOne of: error, warning, info.
- exceptions[].messagestringrequired
- exceptions[].employee_idinteger | nullrequired
- exceptions[].acknowledgedbooleanrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring | nullrequired
- posted_atstring | nullrequired
- journal_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- checksobject[]required
- checks[].idintegerrequired
- checks[].employee_idintegerrequired
- checks[].employee_numberstring | null
- checks[].employee_namestring | null
- checks[].ssn_maskedstring | null
- checks[].bank_account_maskedstring | null
- checks[].payment_methodstring
- checks[].pay_datestring
- checks[].hoursstring
- checks[].regular_hoursstring
- checks[].ot_hoursstring
- checks[].dt_hoursstring
- checks[].grossstringrequiredDecimal string
- checks[].employee_taxesstringDecimal string
- checks[].deductionsstringDecimal string
- checks[].netstringrequiredDecimal string
- checks[].employer_coststringDecimal string
- checks[].taxesobject[]required
- checks[].deduction_linesobject[]required
- checks[].exceptionsany[]
- checks[].explainobject[]
- checks[].check_numberstring | nullPaper check number from the shared check register
- checks[].suta_statestring | null
- checks[].employer_entity_idinteger | nullrequiredEmployer of record: the entity with its own EIN, null = the company employer in payroll setup.
- checks[].voided_atstring | nullrequired
- checks[].void_reasonstring | nullrequired
- checks[].void_entry_idinteger | nullrequired
- timeobject[]required
- time[].idintegerrequired
- time[].employee_idintegerrequired
- time[].datestringrequired
- time[].hoursstringrequired
- time[].project_idinteger | nullrequired
- time[].cost_code_idinteger | nullrequired
- time[].classificationstring | nullrequired
- time[].work_statestring | nullrequired
- time[].ratestring | nullrequired
- time[].timecard_entry_idinteger | nullrequired
- time[].localitystring | nullrequired
- time[].per_diemstring | nullrequired
- time[].per_diem_high_costbooleanrequired
- time[].per_diem_awaybooleanrequired
- time[].wc_class_codestring | nullWorkers' comp class override for this line
- last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run outputs
preview: the payroll journal entry and the labor/burden job cost lines it will post. register: per-check register (JSON, or CSV with format=csv). nacha: the PPD direct deposit file (payroll_run + view_payroll_pii; audited; approved or posted runs). The file is never stored; each generation is recorded (file id modifier, sha256, entries, total, generated by). It is generated once (file id modifier A): a second GET is 409; re-send with POST nacha_resend. Response headers: X-Ach-File-Id-Modifier, and X-Ach-Warning when the effective entry date (pay date) is fewer than 2 banking days away. preview and register require the accounting:read scope; nacha (the direct deposit file) requires the accounting:write scope. Payroll resends require previous_file_id_modifier from the run detail last_ach_file_id_modifier. Missing acknowledgement is 422; stale or replayed acknowledgement is 409 with no new file. Confirm bank non-processing before refreshing and requesting another distinct resend.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- actionstringpathrequiredGET: preview | register | nacha. POST: nacha | import_time | time | earnings | calculate | acknowledge | override | approve | post | void | print_checks | nacha_resend. One of: preview, register, nacha, import_time, time, calculate, acknowledge, override, approve, post, void, earnings, print_checks, nacha_resend.
- formatstringqueryregister: csv
Response · 200 · object | object[]
- posting_datestringrequired
- journalstringrequired
- memostring | nullrequired
- source_typestringrequired
- source_idinteger | nullrequired
- source_revisionintegerrequired
- linesobject[]required
- lines[].account_idintegerrequired
- lines[].account_numberstring | nullrequired
- lines[].account_namestring | nullrequired
- lines[].job_cost_typestring | nullrequired
- lines[].debitstringrequiredDecimal string
- lines[].creditstringrequiredDecimal string
- lines[].memostring | nullrequired
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].hoursstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found409The direct deposit file was already generated (re-send with nacha_resend)422Not calculated / not approved / setup incomplete
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/runs/1/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run workflow step
import_time: approved TimecardEntry rows of the group's linked users in the period (each imported once; they become completed when the run posts). time: { time: [...] } hand-entered lines. calculate: gross-to-net for every employee with time or a salary (replaces prior checks, bumps the revision). acknowledge: { key, reason } for a warning. approve: a different person than the preparer; errors block, warnings must be acknowledged; 422 when a check already in a bank's register (a manual check) is on a bank whose GL is not the net pay account (map key 1010). post: one PR journal entry (sourceType payroll_run) with labor and burden job cost; timecards → completed. void: { reason, date?, confirm_paid? } reverses a posted entry (dated today by default, never before the pay date) and reopens the timecards; a posted run is voided by someone other than its preparers, and an approved or posted run whose direct deposit file was generated needs confirm_paid: true (409 otherwise), and a bank-reconciled entry is refused (409). Needs payroll_run. Requires the accounting:write scope. override: { key, reason } clears an apprentice_over_ratio error (only when the over-ratio hours are already paid at least the journeyworker rate), a missing_suta_rate error or a local_tax_stub error; the person overriding must not be the run's preparer. approve refuses with 409 'Recalculate: YTD changed' when another run paying any of the same employees in the same tax year was approved after this run was calculated (its YTD wage bases are stale); recalculate and approve again. Checks localized to NJ, PA or AK withhold employee unemployment (tax code SUI, accrued to payroll key 2116); with no employee rate loaded for the pay date the check fails with calc_failed. Earnings coded to a project are taxed in the job site state and rated for workers comp there. Calculation raises sdi_rate_unconfirmed (error), one per payer side, when a work state's SDI/PFML program has no rate loaded or that side's rate depends on employer size and payroll setup has no confirmed rate for that side. earnings: { earnings: [{ employee_id, code_id, amount | hours (+ rate), project_id, cost_code_id, memo }] } replaces the run's extra earnings (bonus, PTO, holiday); each code's tax_treatment decides supplemental withholding. print_checks: { bank_account_id } numbers the run's paper checks from that checking account's shared check register (approved or posted runs; re-printing keeps the numbers; the bank account's GL must be the account the run credited for net pay, map key 1010, else 422 naming both) and returns { checks: [{ check_id, employee_id, employee_number, check_number, net, print }] }; needs release_payments. nacha: generates the direct deposit file the first time (422 when the payroll ACH origin routing/account differs from the numbered bank account on the run's net-pay GL; a warning when that GL has no numbered bank account) (same as GET nacha, which is kept for older clients; prefer POST so a retry or prefetch does not spend the one generation). nacha_resend: { resend: { reason, previous_file_id_modifier } } re-sends the direct deposit file with the next file id modifier (B, then C; at most 2 re-sends, then 409); needs payroll_run, view_payroll_pii and release_payments; returns the ACH file (text/plain) with the same headers as GET nacha; audited (nacha_resent, with the reason). Payroll resends require previous_file_id_modifier from the run detail last_ach_file_id_modifier. Missing acknowledgement is 422; stale or replayed acknowledgement is 409 with no new file. Confirm bank non-processing before refreshing and requesting another distinct resend.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- actionstringpathrequiredGET: preview | register | nacha. POST: nacha | import_time | time | earnings | calculate | acknowledge | override | approve | post | void | print_checks | nacha_resend. One of: preview, register, nacha, import_time, time, calculate, acknowledge, override, approve, post, void, earnings, print_checks, nacha_resend.
Request body
- resendobjectrequired
- resend.reasonstringrequired
- resend.previous_file_id_modifierstringrequiredLast file reviewed by the caller, from last_ach_file_id_modifier on run detail.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- pay_group_idintegerrequired
- pay_group_codestring | nullrequired
- period_startstringrequired
- period_endstringrequired
- pay_datestringrequired
- statusstringrequiredOne of: draft, calculated, approved, posted, voided.
- revisionintegerrequired
- gross_totalstringrequiredDecimal string
- employee_taxesstringrequiredDecimal string
- deductions_totalstringrequiredDecimal string
- net_totalstringrequiredDecimal string
- employer_coststringrequiredDecimal string
- check_countinteger | nullrequired
- exceptionsobject[]required
- exceptions[].keystringrequired
- exceptions[].codestringrequired
- exceptions[].severitystringrequiredOne of: error, warning, info.
- exceptions[].messagestringrequired
- exceptions[].employee_idinteger | nullrequired
- exceptions[].acknowledgedbooleanrequired
- prepared_by_idintegerrequired
- approved_by_idinteger | nullrequired
- approved_atstring | nullrequired
- posted_atstring | nullrequired
- journal_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- run_typestringrequiredOnly regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
- last_ach_file_id_modifierstring | nullLatest generated payroll ACH modifier, or null before generation. Returned on run detail; supply as previous_file_id_modifier when preparing a resend. Read this field again after an uncertain response.
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found409Approve: YTD changed since calculation (recalculate), approval inputs busy, or a conflicting state422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/runs/1/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"resend": {
"reason": "string",
"previous_file_id_modifier": "string"
}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/setupShow payroll setup
Tax engine (builtin or a registered provider adapter), burden method, SUTA, employer identity (EIN masked), ACH origin (account masked) and the payroll account map. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- tax_providerstringrequired
- tax_providersstring[]required
- burden_methodstringrequired
- default_ot_rule_setstringrequired
- suta_statestring | nullrequired
- suta_ratestring | nullrequired
- suta_wage_basestring | nullrequiredDecimal string
- state_flat_ratesobjectrequired
- state_account_idsobjectrequiredState employer account numbers for EFW2 RS records, keyed by state
- account_mapobject[]required
- account_map[].keystringrequired
- account_map[].labelstringrequired
- account_map[].account_numberstringrequired
- employer_ein_maskedstring | nullrequired
- employer_namestring | nullrequired
- employer_addressstring | nullrequired
- employer_citystring | nullrequired
- employer_statestring | nullrequired
- employer_zipstring | nullrequired
- ach_odfi_routingstring | nullrequired
- ach_bank_namestring | nullrequired
- ach_account_maskedstring | nullrequired
- local_flat_ratesobjectrequiredStub rates for localities without built-in data, keyed ST:City
- sdi_ratesobjectrequiredCompany-confirmed SDI/PFML rates keyed ST:Program:employee or ST:Program:employer (e.g. WA:PFML:employee), used where the built-in dataset has no rate or the rate depends on employer size
- standard_burden_ratestring | nullrequired
- burden_true_up_tostringrequiredOne of: jobs, overhead.
- per_diem_accountablebooleanrequired
- per_diem_federal_ratestring | nullrequired
- suta_ratesobjectSUTA rate and wage base per state; a check uses its localization state
- filed_periodsstring[]Filed payroll return periods: 2026-Q1 (941 / state UI) and 2026 (W-2 / 940)
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/setup" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
PATCH/rest/v1.0/companies/{company_id}/accounting/payroll/setupUpdate payroll setup
Partial update; an unknown tax_provider is refused. The ACH account number is encrypted. Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- payroll_setupobjectrequired
Response · 200 · object
- tax_providerstringrequired
- tax_providersstring[]required
- burden_methodstringrequired
- default_ot_rule_setstringrequired
- suta_statestring | nullrequired
- suta_ratestring | nullrequired
- suta_wage_basestring | nullrequiredDecimal string
- state_flat_ratesobjectrequired
- state_account_idsobjectrequiredState employer account numbers for EFW2 RS records, keyed by state
- account_mapobject[]required
- account_map[].keystringrequired
- account_map[].labelstringrequired
- account_map[].account_numberstringrequired
- employer_ein_maskedstring | nullrequired
- employer_namestring | nullrequired
- employer_addressstring | nullrequired
- employer_citystring | nullrequired
- employer_statestring | nullrequired
- employer_zipstring | nullrequired
- ach_odfi_routingstring | nullrequired
- ach_bank_namestring | nullrequired
- ach_account_maskedstring | nullrequired
- local_flat_ratesobjectrequiredStub rates for localities without built-in data, keyed ST:City
- sdi_ratesobjectrequiredCompany-confirmed SDI/PFML rates keyed ST:Program:employee or ST:Program:employer (e.g. WA:PFML:employee), used where the built-in dataset has no rate or the rate depends on employer size
- standard_burden_ratestring | nullrequired
- burden_true_up_tostringrequiredOne of: jobs, overhead.
- per_diem_accountablebooleanrequired
- per_diem_federal_ratestring | nullrequired
- suta_ratesobjectSUTA rate and wage base per state; a check uses its localization state
- filed_periodsstring[]Filed payroll return periods: 2026-Q1 (941 / state UI) and 2026 (W-2 / 940)
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/setup" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"payroll_setup": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/union_localsList union locals
Locals with their effective-dated CBA rates and benefit rules. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- codestringrequired
- namestringrequired
- remit_tostring | nullrequired
- cba_rulesobject | nullrequiredCBA day rules: weekday 0 = Sunday ... 6 = Saturday
- cba_rules.day_multipliersobject
- cba_rules.holidaysstring (date)[]
- cba_rules.holiday_multiplierstringOne of: 1.5, 2.
- ratesobject[]required
- rates[].idintegerrequired
- rates[].local_idintegerrequired
- rates[].classificationstringrequired
- rates[].zonestring | nullrequired
- rates[].effective_fromstringrequired
- rates[].effective_tostring | nullrequired
- rates[].wagestringrequired
- rates[].benefitsobject[]required
- rates[].apprentice_ratiostring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/union_locals" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/union_localsCreate a union local
Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- union_localobjectrequired
Response · 201 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- remit_tostring | nullrequired
- cba_rulesobject | nullrequiredCBA day rules: weekday 0 = Sunday ... 6 = Saturday
- cba_rules.day_multipliersobject
- cba_rules.holidaysstring (date)[]
- cba_rules.holiday_multiplierstringOne of: 1.5, 2.
- ratesobject[]required
- rates[].idintegerrequired
- rates[].local_idintegerrequired
- rates[].classificationstringrequired
- rates[].zonestring | nullrequired
- rates[].effective_fromstringrequired
- rates[].effective_tostring | nullrequired
- rates[].wagestringrequired
- rates[].benefitsobject[]required
- rates[].apprentice_ratiostring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/union_locals" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"union_local": {}
}'Accounting / Payroll
PATCH/rest/v1.0/companies/{company_id}/accounting/payroll/union_locals/{id}Update a union local
Name, remit_to, or cba_rules ({ day_multipliers: { "0".."6": multiplier }, holidays: [date], holiday_multiplier }; null clears). Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- union_localobjectrequired
Response · 200 · object
- idintegerrequired
- codestringrequired
- namestringrequired
- remit_tostring | nullrequired
- cba_rulesobject | nullrequiredCBA day rules: weekday 0 = Sunday ... 6 = Saturday
- cba_rules.day_multipliersobject
- cba_rules.holidaysstring (date)[]
- cba_rules.holiday_multiplierstringOne of: 1.5, 2.
- ratesobject[]required
- rates[].idintegerrequired
- rates[].local_idintegerrequired
- rates[].classificationstringrequired
- rates[].zonestring | nullrequired
- rates[].effective_fromstringrequired
- rates[].effective_tostring | nullrequired
- rates[].wagestringrequired
- rates[].benefitsobject[]required
- rates[].apprentice_ratiostring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace404Not found422Validation or workflow error
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/union_locals/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"union_local": {}
}'Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/union_ratesAdd a CBA rate
Effective-dated wage and benefit rules (per hour, % of gross, per day; employer fringe or employee deduction such as dues; reciprocity). Needs payroll_run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- union_rateobjectrequired
Response · 201 · object
- idintegerrequired
- local_idintegerrequired
- classificationstringrequired
- zonestring | nullrequired
- effective_fromstringrequired
- effective_tostring | nullrequired
- wagestringrequired
- benefitsobject[]required
- benefits[].codestring
- benefits[].fundstring
- benefits[].localstring
- benefits[].basisstringOne of: per_hour, pct_gross, per_day.
- benefits[].amountstring | number
- benefits[].kindstringOne of: employer_fringe, employee_deduction.
- benefits[].reciprocalboolean
- benefits[].planstringOne of: retirement, health, other.
- apprentice_ratiostring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/union_rates" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"union_rate": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsList wage determinations
Prevailing wage BHR + fringe per project and classification, with the apprentice ratio. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequired
- wd_numberstringrequired
- countystring | nullrequired
- classificationstringrequired
- bhrstringrequired
- fringestringrequired
- effective_fromstringrequired
- effective_tostring | nullrequired
- apprentice_ratiostring | nullrequired
- dir_project_idstring | nullrequired
- awarding_bodystring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/wage_determinations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsCreate a wage determination
Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- wage_determinationobjectrequired
Response · 201 · object
- idintegerrequired
- project_idintegerrequired
- wd_numberstringrequired
- countystring | nullrequired
- classificationstringrequired
- bhrstringrequired
- fringestringrequired
- effective_fromstringrequired
- effective_tostring | nullrequired
- apprentice_ratiostring | nullrequired
- dir_project_idstring | nullrequired
- awarding_bodystring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/wage_determinations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"wage_determination": {}
}'Accounting / Payroll
GET/rest/v1.0/companies/{company_id}/accounting/payroll/wc_classesList workers' comp classes
Effective-dated class rates per $100 (or per hour); OT premium excluded by default. Needs payroll_view. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object[]
- idintegerrequired
- statestringrequired
- codestringrequired
- namestringrequired
- rate_per_100string | nullrequired
- rate_per_hourstring | nullrequired
- exclude_ot_premiumbooleanrequired
- effective_fromstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/wc_classes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Payroll
POST/rest/v1.0/companies/{company_id}/accounting/payroll/wc_classesCreate a wc class
Needs payroll_run; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- wc_classobjectrequired
Response · 201 · object
- idintegerrequired
- statestringrequired
- codestringrequired
- namestringrequired
- rate_per_100string | nullrequired
- rate_per_hourstring | nullrequired
- exclude_ot_premiumbooleanrequired
- effective_fromstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), a project-scoped (project_manager_view) grant (it never holds payroll permissions), wrong company, or read-only workspace422Validation or workflow error
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/payroll/wc_classes" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"wc_class": {}
}'