Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Accounting · People, jobs and assets

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.

44 operationsCompany moduleAll Accounting apps →
  1. POST /rest/v1.0/companies/{company_id}/accounting/payroll/accrualPost the month-end payroll accrual
  2. POST /rest/v1.0/companies/{company_id}/accounting/payroll/burden_true_upPost the standard-rate burden true-up
  3. GET /rest/v1.0/companies/{company_id}/accounting/payroll/certified_payrollCertified payroll (WH-347)
  4. POST /rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/reissueReissue a printed paper check under a new number
  5. POST /rest/v1.0/companies/{company_id}/accounting/payroll/checks/{id}/voidVoid one check of a posted run
  6. GET /rest/v1.0/companies/{company_id}/accounting/payroll/codesList payroll codes
  7. POST /rest/v1.0/companies/{company_id}/accounting/payroll/codesCreate a code
  8. GET /rest/v1.0/companies/{company_id}/accounting/payroll/employeesList employees
  9. POST /rest/v1.0/companies/{company_id}/accounting/payroll/employeesCreate an employee
  10. GET /rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Show an employee
  11. PATCH /rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}Update an employee
  12. POST /rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductionsAdd a deduction, match or garnishment
  13. DELETE /rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/deductions/{deduction_id}End a deduction
  14. POST /rest/v1.0/companies/{company_id}/accounting/payroll/employees/{id}/revealReveal an employee SSN and bank numbers
  15. GET /rest/v1.0/companies/{company_id}/accounting/payroll/employersList payroll employer entities
  16. PUT /rest/v1.0/companies/{company_id}/accounting/payroll/employers/{entity_id}Set an employer entity's payroll identity
  17. POST /rest/v1.0/companies/{company_id}/accounting/payroll/filingsMark a payroll return period filed
  18. POST /rest/v1.0/companies/{company_id}/accounting/payroll/futa_overrideRequest or approve a provisional FUTA credit reduction override
  19. POST /rest/v1.0/companies/{company_id}/accounting/payroll/manual_checksEnter a manual (handwritten) check
  20. GET /rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsList pay groups
  21. POST /rest/v1.0/companies/{company_id}/accounting/payroll/pay_groupsCreate a pay group
  22. PATCH /rest/v1.0/companies/{company_id}/accounting/payroll/pay_groups/{id}Update a pay group
  23. POST /rest/v1.0/companies/{company_id}/accounting/payroll/pii_rotationRotate payroll PII encryption
  24. GET /rest/v1.0/companies/{company_id}/accounting/payroll/rate_changesList pay-rate changes
  25. POST /rest/v1.0/companies/{company_id}/accounting/payroll/rate_changes/{id}Approve or reject a pay-rate change
  26. GET /rest/v1.0/companies/{company_id}/accounting/payroll/remittancesList payroll liability remittances
  27. POST /rest/v1.0/companies/{company_id}/accounting/payroll/remittancesRemit a payroll liability
  28. POST /rest/v1.0/companies/{company_id}/accounting/payroll/remittances/{id}/{decision}Release or reject a pending bank remittance
  29. GET /rest/v1.0/companies/{company_id}/accounting/payroll/reports/{report}Payroll tax and remittance data
  30. GET /rest/v1.0/companies/{company_id}/accounting/payroll/runsList pay runs
  31. POST /rest/v1.0/companies/{company_id}/accounting/payroll/runsCreate a pay run
  32. GET /rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}Show a pay run
  33. GET /rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run outputs
  34. POST /rest/v1.0/companies/{company_id}/accounting/payroll/runs/{id}/{action}Pay run workflow step
  35. GET /rest/v1.0/companies/{company_id}/accounting/payroll/setupShow payroll setup
  36. PATCH /rest/v1.0/companies/{company_id}/accounting/payroll/setupUpdate payroll setup
  37. GET /rest/v1.0/companies/{company_id}/accounting/payroll/union_localsList union locals
  38. POST /rest/v1.0/companies/{company_id}/accounting/payroll/union_localsCreate a union local
  39. PATCH /rest/v1.0/companies/{company_id}/accounting/payroll/union_locals/{id}Update a union local
  40. POST /rest/v1.0/companies/{company_id}/accounting/payroll/union_ratesAdd a CBA rate
  41. GET /rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsList wage determinations
  42. POST /rest/v1.0/companies/{company_id}/accounting/payroll/wage_determinationsCreate a wage determination
  43. GET /rest/v1.0/companies/{company_id}/accounting/payroll/wc_classesList workers' comp classes
  44. 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/accrual

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

v1.0Implemented

Parameters

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

Request body

  • month
    stringrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
  • 409Conflict with the current state
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_up

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

v1.0Implemented

Parameters

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

Request body

  • month
    string

Response · 200 · object

No documented fields.

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_payroll

Certified 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).

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • project_id
    integerquery
    Project with a wage determination
  • week_ending
    stringquery
    YYYY-MM-DD
  • format
    stringquery
    Output One of: json, csv, pdf, ecpr, ecpr_v2, ny_xml.
  • pwcr
    stringquery
    format=ecpr_v2: the contractor's 10-digit DIR public works registration
  • prc_number
    stringquery
    format=ny_xml: the project's 10-character NYS DOL Prevailing Rate Case number

Response · 200 · object

  • projects
    object[]required
  • projects[].id
    integerrequired
  • projects[].name
    stringrequired
  • projects[].wd_number
    stringrequired
  • weeks
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422No 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

Generated from the contractcurl
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}/reissue

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

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired
  • date
    string (date)

Response · 200 · object

  • check
    objectrequired
  • check.id
    integerrequired
  • check.employee_id
    integerrequired
  • check.employee_number
    string | null
  • check.employee_name
    string | null
  • check.ssn_masked
    string | null
  • check.bank_account_masked
    string | null
  • check.payment_method
    string
  • check.pay_date
    string
  • check.hours
    string
  • check.regular_hours
    string
  • check.ot_hours
    string
  • check.dt_hours
    string
  • check.gross
    stringrequired
    Decimal string
  • check.employee_taxes
    string
    Decimal string
  • check.deductions
    string
    Decimal string
  • check.net
    stringrequired
    Decimal string
  • check.employer_cost
    string
    Decimal string
  • check.taxes
    object[]required
  • check.deduction_lines
    object[]required
  • check.exceptions
    any[]
  • check.explain
    object[]
  • check.check_number
    string | null
    Paper check number from the shared check register
  • check.suta_state
    string | null
  • check.employer_entity_id
    integer | nullrequired
    Employer of record: the entity with its own EIN, null = the company employer in payroll setup.
  • check.voided_at
    string | nullrequired
  • check.void_reason
    string | nullrequired
  • check.void_entry_id
    integer | nullrequired
  • voided_check_number
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
  • 404Not found
  • 409Conflict with the current state
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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}/void

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

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired
  • date
    string (date)
  • confirm_paid
    boolean
  • reissue
    boolean
  • reissue_pay_date
    string (date)

Response · 200 · object

  • check
    objectrequired
  • check.id
    integerrequired
  • check.employee_id
    integerrequired
  • check.employee_number
    string | null
  • check.employee_name
    string | null
  • check.ssn_masked
    string | null
  • check.bank_account_masked
    string | null
  • check.payment_method
    string
  • check.pay_date
    string
  • check.hours
    string
  • check.regular_hours
    string
  • check.ot_hours
    string
  • check.dt_hours
    string
  • check.gross
    stringrequired
    Decimal string
  • check.employee_taxes
    string
    Decimal string
  • check.deductions
    string
    Decimal string
  • check.net
    stringrequired
    Decimal string
  • check.employer_cost
    string
    Decimal string
  • check.taxes
    object[]required
  • check.deduction_lines
    object[]required
  • check.exceptions
    any[]
  • check.explain
    object[]
  • check.check_number
    string | null
    Paper check number from the shared check register
  • check.suta_state
    string | null
  • check.employer_entity_id
    integer | nullrequired
    Employer of record: the entity with its own EIN, null = the company employer in payroll setup.
  • check.voided_at
    string | nullrequired
  • check.void_reason
    string | nullrequired
  • check.void_entry_id
    integer | nullrequired
  • reissue_run
    object | nullrequired
  • reissue_run.id
    integerrequired
  • reissue_run.number
    stringrequired
  • reissue_run.pay_group_id
    integerrequired
  • reissue_run.pay_group_code
    string | nullrequired
  • reissue_run.period_start
    stringrequired
  • reissue_run.period_end
    stringrequired
  • reissue_run.pay_date
    stringrequired
  • reissue_run.status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • reissue_run.revision
    integerrequired
  • reissue_run.gross_total
    stringrequired
    Decimal string
  • reissue_run.employee_taxes
    stringrequired
    Decimal string
  • reissue_run.deductions_total
    stringrequired
    Decimal string
  • reissue_run.net_total
    stringrequired
    Decimal string
  • reissue_run.employer_cost
    stringrequired
    Decimal string
  • reissue_run.check_count
    integer | nullrequired
  • reissue_run.exceptions
    object[]required
  • reissue_run.prepared_by_id
    integerrequired
  • reissue_run.approved_by_id
    integer | nullrequired
  • reissue_run.approved_at
    string | nullrequired
  • reissue_run.posted_at
    string | nullrequired
  • reissue_run.journal_entry_id
    integer | nullrequired
  • reissue_run.void_reason
    string | nullrequired
  • reissue_run.run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • reissue_run.last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
  • 404Not found
  • 409Conflict with the current state
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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/codes

List payroll codes

Earning, deduction, benefit and employer-tax codes. Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • kind
    stringrequired
    One of: earning, deduction, benefit, employer_tax.
  • code
    stringrequired
  • name
    stringrequired
  • tax_treatment
    string | nullrequired
    Earnings: regular | supplemental (flat-rate FIT) | nontaxable (paid, not wages). Deductions: the deduction type.
  • calc_method
    stringrequired
  • rate
    string | nullrequired
  • is_active
    booleanrequired
  • include_in_regular_rate
    booleanrequired
    Earnings: 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 token
  • 403No 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

Generated from the contractcurl
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/codes

Create a code

Needs payroll_run; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • code
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: earning, deduction, benefit, employer_tax.
  • code
    stringrequired
  • name
    stringrequired
  • tax_treatment
    string | nullrequired
    Earnings: regular | supplemental (flat-rate FIT) | nontaxable (paid, not wages). Deductions: the deduction type.
  • calc_method
    stringrequired
  • rate
    string | nullrequired
  • is_active
    booleanrequired
  • include_in_regular_rate
    booleanrequired
    Earnings: 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 token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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/employees

List employees

PII masked (***-**-1234, ****6789). Filters: filters[status], filters[pay_group_id], search. Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
    Page (1-based)
  • per_page
    integerquery
    Page size (max 1000)
  • search
    stringquery
    Name or number

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • first_name
    stringrequired
  • last_name
    stringrequired
  • middle_initial
    string | null
  • user_id
    integer | null
  • workforce_person_id
    integer | null
  • status
    string
  • hire_date
    string | null
  • term_date
    string | null
  • pay_group_id
    integerrequired
  • pay_group_code
    string | null
  • pay_type
    stringrequired
    One of: hourly, salary.
  • hourly_rate
    string | null
  • salary_per_period
    string | null
    Decimal string
  • salary_allocation
    array | null
  • union_local_id
    integer | null
  • home_local_code
    string | null
  • classification
    string | null
  • worker_type
    string
    One of: J, RA.
  • apprentice_level
    string | null
  • plan_credit_per_hour
    string | null
  • wc_class_code
    string | null
  • resident_state
    string
  • work_state
    string
  • w4
    object | null
  • state_w4
    object | null
  • birth_year
    integer | null
  • address
    string | null
  • city
    string | null
  • state
    string | null
  • zip
    string | null
  • payment_method
    string
  • ssn_masked
    string | nullrequired
    Masked; full SSN only via ?reveal=true
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | null
  • has_bank_routing
    boolean
  • deductions
    object[]
  • deductions[].id
    integerrequired
  • deductions[].kind
    stringrequired
    One of: deduction, garnishment, match.
  • deductions[].code
    stringrequired
  • deductions[].type
    stringrequired
  • deductions[].amount
    string | nullrequired
    Decimal string
  • deductions[].pct_of_gross
    string | nullrequired
  • deductions[].params
    object | nullrequired
  • deductions[].is_active
    booleanrequired
  • revealed
    object
    Only with ?reveal=true and view_payroll_pii; audited
  • revealed.ssn
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • resident_locality
    string | null
  • reciprocity_states
    string[]
  • pending_rate_change_id
    integer | null
    PATCH only: pay-rate fields become this pending rate change
  • pending_bank_change_id
    integer | null
    PATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
  • flsa_exempt
    booleanrequired
    Salaried 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 token
  • 403No 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

Generated from the contractcurl
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/employees

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • employee
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • first_name
    stringrequired
  • last_name
    stringrequired
  • middle_initial
    string | null
  • user_id
    integer | null
  • workforce_person_id
    integer | null
  • status
    string
  • hire_date
    string | null
  • term_date
    string | null
  • pay_group_id
    integerrequired
  • pay_group_code
    string | null
  • pay_type
    stringrequired
    One of: hourly, salary.
  • hourly_rate
    string | null
  • salary_per_period
    string | null
    Decimal string
  • salary_allocation
    array | null
  • union_local_id
    integer | null
  • home_local_code
    string | null
  • classification
    string | null
  • worker_type
    string
    One of: J, RA.
  • apprentice_level
    string | null
  • plan_credit_per_hour
    string | null
  • wc_class_code
    string | null
  • resident_state
    string
  • work_state
    string
  • w4
    object | null
  • state_w4
    object | null
  • birth_year
    integer | null
  • address
    string | null
  • city
    string | null
  • state
    string | null
  • zip
    string | null
  • payment_method
    string
  • ssn_masked
    string | nullrequired
    Masked; full SSN only via ?reveal=true
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | null
  • has_bank_routing
    boolean
  • deductions
    object[]
  • deductions[].id
    integerrequired
  • deductions[].kind
    stringrequired
    One of: deduction, garnishment, match.
  • deductions[].code
    stringrequired
  • deductions[].type
    stringrequired
  • deductions[].amount
    string | nullrequired
    Decimal string
  • deductions[].pct_of_gross
    string | nullrequired
  • deductions[].params
    object | nullrequired
  • deductions[].is_active
    booleanrequired
  • revealed
    object
    Only with ?reveal=true and view_payroll_pii; audited
  • revealed.ssn
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • resident_locality
    string | null
  • reciprocity_states
    string[]
  • pending_rate_change_id
    integer | null
    PATCH only: pay-rate fields become this pending rate change
  • pending_bank_change_id
    integer | null
    PATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
  • flsa_exempt
    booleanrequired
    Salaried 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 token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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).

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • reveal
    booleanquery
    Decrypt PII (view_payroll_pii; audited)

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • first_name
    stringrequired
  • last_name
    stringrequired
  • middle_initial
    string | null
  • user_id
    integer | null
  • workforce_person_id
    integer | null
  • status
    string
  • hire_date
    string | null
  • term_date
    string | null
  • pay_group_id
    integerrequired
  • pay_group_code
    string | null
  • pay_type
    stringrequired
    One of: hourly, salary.
  • hourly_rate
    string | null
  • salary_per_period
    string | null
    Decimal string
  • salary_allocation
    array | null
  • union_local_id
    integer | null
  • home_local_code
    string | null
  • classification
    string | null
  • worker_type
    string
    One of: J, RA.
  • apprentice_level
    string | null
  • plan_credit_per_hour
    string | null
  • wc_class_code
    string | null
  • resident_state
    string
  • work_state
    string
  • w4
    object | null
  • state_w4
    object | null
  • birth_year
    integer | null
  • address
    string | null
  • city
    string | null
  • state
    string | null
  • zip
    string | null
  • payment_method
    string
  • ssn_masked
    string | nullrequired
    Masked; full SSN only via ?reveal=true
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | null
  • has_bank_routing
    boolean
  • deductions
    object[]
  • deductions[].id
    integerrequired
  • deductions[].kind
    stringrequired
    One of: deduction, garnishment, match.
  • deductions[].code
    stringrequired
  • deductions[].type
    stringrequired
  • deductions[].amount
    string | nullrequired
    Decimal string
  • deductions[].pct_of_gross
    string | nullrequired
  • deductions[].params
    object | nullrequired
  • deductions[].is_active
    booleanrequired
  • revealed
    object
    Only with ?reveal=true and view_payroll_pii; audited
  • revealed.ssn
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • resident_locality
    string | null
  • reciprocity_states
    string[]
  • pending_rate_change_id
    integer | null
    PATCH only: pay-rate fields become this pending rate change
  • pending_bank_change_id
    integer | null
    PATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
  • flsa_exempt
    booleanrequired
    Salaried 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 token
  • 403No 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
  • 404Not found
  • 429Too many reveals or PII files; retry after the Retry-After seconds.

Example request

Generated from the contractcurl
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).

v1.0Implemented

Parameters

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

Request body

  • employee
    objectrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • first_name
    stringrequired
  • last_name
    stringrequired
  • middle_initial
    string | null
  • user_id
    integer | null
  • workforce_person_id
    integer | null
  • status
    string
  • hire_date
    string | null
  • term_date
    string | null
  • pay_group_id
    integerrequired
  • pay_group_code
    string | null
  • pay_type
    stringrequired
    One of: hourly, salary.
  • hourly_rate
    string | null
  • salary_per_period
    string | null
    Decimal string
  • salary_allocation
    array | null
  • union_local_id
    integer | null
  • home_local_code
    string | null
  • classification
    string | null
  • worker_type
    string
    One of: J, RA.
  • apprentice_level
    string | null
  • plan_credit_per_hour
    string | null
  • wc_class_code
    string | null
  • resident_state
    string
  • work_state
    string
  • w4
    object | null
  • state_w4
    object | null
  • birth_year
    integer | null
  • address
    string | null
  • city
    string | null
  • state
    string | null
  • zip
    string | null
  • payment_method
    string
  • ssn_masked
    string | nullrequired
    Masked; full SSN only via ?reveal=true
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | null
  • has_bank_routing
    boolean
  • deductions
    object[]
  • deductions[].id
    integerrequired
  • deductions[].kind
    stringrequired
    One of: deduction, garnishment, match.
  • deductions[].code
    stringrequired
  • deductions[].type
    stringrequired
  • deductions[].amount
    string | nullrequired
    Decimal string
  • deductions[].pct_of_gross
    string | nullrequired
  • deductions[].params
    object | nullrequired
  • deductions[].is_active
    booleanrequired
  • revealed
    object
    Only with ?reveal=true and view_payroll_pii; audited
  • revealed.ssn
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • resident_locality
    string | null
  • reciprocity_states
    string[]
  • pending_rate_change_id
    integer | null
    PATCH only: pay-rate fields become this pending rate change
  • pending_bank_change_id
    integer | null
    PATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
  • flsa_exempt
    booleanrequired
    Salaried 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 token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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}/deductions

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • deduction
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • kind
    stringrequired
    One of: deduction, garnishment, match.
  • code
    stringrequired
  • type
    stringrequired
  • amount
    string | nullrequired
    Decimal string
  • pct_of_gross
    string | nullrequired
  • params
    object | nullrequired
  • is_active
    booleanrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 409The 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

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Response · 204

No response body.

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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}/reveal

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

v1.0Implemented

Parameters

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

Request body

  • reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • first_name
    stringrequired
  • last_name
    stringrequired
  • middle_initial
    string | null
  • user_id
    integer | null
  • workforce_person_id
    integer | null
  • status
    string
  • hire_date
    string | null
  • term_date
    string | null
  • pay_group_id
    integerrequired
  • pay_group_code
    string | null
  • pay_type
    stringrequired
    One of: hourly, salary.
  • hourly_rate
    string | null
  • salary_per_period
    string | null
    Decimal string
  • salary_allocation
    array | null
  • union_local_id
    integer | null
  • home_local_code
    string | null
  • classification
    string | null
  • worker_type
    string
    One of: J, RA.
  • apprentice_level
    string | null
  • plan_credit_per_hour
    string | null
  • wc_class_code
    string | null
  • resident_state
    string
  • work_state
    string
  • w4
    object | null
  • state_w4
    object | null
  • birth_year
    integer | null
  • address
    string | null
  • city
    string | null
  • state
    string | null
  • zip
    string | null
  • payment_method
    string
  • ssn_masked
    string | nullrequired
    Masked; full SSN only via ?reveal=true
  • bank_account_masked
    string | nullrequired
  • bank_account_type
    string | null
  • has_bank_routing
    boolean
  • deductions
    object[]
  • deductions[].id
    integerrequired
  • deductions[].kind
    stringrequired
    One of: deduction, garnishment, match.
  • deductions[].code
    stringrequired
  • deductions[].type
    stringrequired
  • deductions[].amount
    string | nullrequired
    Decimal string
  • deductions[].pct_of_gross
    string | nullrequired
  • deductions[].params
    object | nullrequired
  • deductions[].is_active
    booleanrequired
  • revealed
    object
    Only with ?reveal=true and view_payroll_pii; audited
  • revealed.ssn
    string | nullrequired
  • revealed.bank_routing_number
    string | nullrequired
  • revealed.bank_account_number
    string | nullrequired
  • resident_locality
    string | null
  • reciprocity_states
    string[]
  • pending_rate_change_id
    integer | null
    PATCH only: pay-rate fields become this pending rate change
  • pending_bank_change_id
    integer | null
    PATCH only: bank_routing_number, bank_account_number and bank_account_type become this pending bank change
  • flsa_exempt
    booleanrequired
    Salaried 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 token
  • 403No 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
  • 404Not found
  • 422Validation error (reason: 3 to 500 characters)
  • 429Too many reveals or PII files; retry after the Retry-After seconds.

Example request

Generated from the contractcurl
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/employers

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • entity_id
    integerrequired
  • state_account_ids
    objectrequired
  • ach_odfi_routing
    string | nullrequired
  • ach_bank_name
    string | nullrequired
  • ach_account_masked
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Request body

  • employer
    objectrequired
  • employer.state_account_ids
    object | null
  • employer.ach_odfi_routing
    string | null
  • employer.ach_bank_name
    string | null
  • employer.ach_account_number
    string | null

Response · 200 · object

  • entity_id
    integerrequired
  • state_account_ids
    objectrequired
  • ach_odfi_routing
    string | nullrequired
  • ach_bank_name
    string | nullrequired
  • ach_account_masked
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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/filings

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • period
    stringrequired
  • filed
    boolean

Response · 200 · object

  • filed_periods
    string[]required

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace
  • 422Validation error or payroll setup missing

Example request

Generated from the contractcurl
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_override

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

v1.0Implemented

Parameters

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

Request body

  • action
    stringrequired
    One of: request, approve.
  • year
    integerrequired
  • reason
    string
    Required for request (3-500 chars)

Response · 200 · object

  • year
    integer
  • rates
    object
  • reason
    string
  • requested_by_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null
  • status
    string
    One of: pending, approved.

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_checks

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • manual_check
    objectrequired
  • manual_check.pay_group_id
    integerrequired
  • manual_check.employee_id
    integerrequired
  • manual_check.pay_date
    string (date)required
  • manual_check.period_start
    string (date)
  • manual_check.period_end
    string (date)
  • manual_check.check_number
    string
  • manual_check.project_id
    integer | null
  • manual_check.cost_code_id
    integer | null
  • manual_check.memo
    string | null
  • manual_check.gross
    stringrequired
  • manual_check.net
    string
  • manual_check.taxes
    object[]
  • manual_check.taxes[].code
    stringrequired
    FIT, SS, MED, ADDL_MED, FUTA, SUTA, SIT, LOCAL, SDI …
  • manual_check.taxes[].payer
    stringrequired
    One of: employee, employer.
  • manual_check.taxes[].jurisdiction
    string
  • manual_check.taxes[].amount
    stringrequired
  • manual_check.taxes[].wages
    string
  • manual_check.deductions
    object[]
  • manual_check.deductions[].code
    stringrequired
  • manual_check.deductions[].type
    stringrequired
    One of: pretax_401k, roth_401k, section125, hsa, post_tax, union_dues.
  • manual_check.deductions[].amount
    stringrequired
  • manual_check.request_key
    string
    Retry 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_id
    integer
    Required with check_number: the checking account the check was written on.

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • pay_group_id
    integerrequired
  • pay_group_code
    string | nullrequired
  • period_start
    stringrequired
  • period_end
    stringrequired
  • pay_date
    stringrequired
  • status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • revision
    integerrequired
  • gross_total
    stringrequired
    Decimal string
  • employee_taxes
    stringrequired
    Decimal string
  • deductions_total
    stringrequired
    Decimal string
  • net_total
    stringrequired
    Decimal string
  • employer_cost
    stringrequired
    Decimal string
  • check_count
    integer | nullrequired
  • exceptions
    object[]required
  • exceptions[].key
    stringrequired
  • exceptions[].code
    stringrequired
  • exceptions[].severity
    stringrequired
    One of: error, warning, info.
  • exceptions[].message
    stringrequired
  • exceptions[].employee_id
    integer | nullrequired
  • exceptions[].acknowledged
    booleanrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | nullrequired
  • posted_at
    string | nullrequired
  • journal_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii), wrong company, or read-only workspace
  • 404Not found
  • 409The 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

Generated from the contractcurl
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_groups

List pay groups

Pay groups with frequency and overtime rule set (FLSA, CA, AK, NV, CO). Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • frequency
    stringrequired
    One of: weekly, biweekly, semimonthly, monthly.
  • ot_rule_set
    stringrequired
  • is_active
    booleanrequired
  • employee_count
    integer | nullrequired
  • ot_method
    stringrequired
    rate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
  • workweek_anchor
    string | null (date)required
    Any first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
  • entity_id
    integer | nullrequired
    Posting entity for the group's runs (default entity when null)
  • dimension_value_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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_groups

Create a pay group

Needs payroll_run; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • pay_group
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • frequency
    stringrequired
    One of: weekly, biweekly, semimonthly, monthly.
  • ot_rule_set
    stringrequired
  • is_active
    booleanrequired
  • employee_count
    integer | nullrequired
  • ot_method
    stringrequired
    rate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
  • workweek_anchor
    string | null (date)required
    Any first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
  • entity_id
    integer | nullrequired
    Posting entity for the group's runs (default entity when null)
  • dimension_value_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Request body

  • pay_group
    object

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • frequency
    stringrequired
    One of: weekly, biweekly, semimonthly, monthly.
  • ot_rule_set
    stringrequired
  • is_active
    booleanrequired
  • employee_count
    integer | nullrequired
  • ot_method
    stringrequired
    rate_in_effect needs a §7(g)(2) agreement (29 CFR 778.419) One of: weighted_average, rate_in_effect.
  • workweek_anchor
    string | null (date)required
    Any first day of the fixed FLSA workweek (29 CFR 778.105); required for semimonthly/monthly groups with hourly staff
  • entity_id
    integer | nullrequired
    Posting entity for the group's runs (default entity when null)
  • dimension_value_ids
    array | nullrequired
    User-defined dimension values (AcctDimensionValue ids).

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_rotation

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

v1.0Implemented

Parameters

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

Response · 200 · object

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

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing 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
  • 409An approved run holds a hash of the current ciphertext

Example request

Generated from the contractcurl
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_changes

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • employee_id
    integerquery
  • status
    stringquery
    One of: pending, approved, rejected.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • employee_id
    integerrequired
  • kind
    stringrequired
    bank: 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.
  • changes
    objectrequired
  • status
    stringrequired
    One of: pending, approved, rejected.
  • requested_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • decided_at
    string | nullrequired
  • reason
    string | nullrequired
  • created_at
    stringrequired
  • effective_date
    string | null
    Rate in effect from this date (time on earlier dates pays the previous rate)

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Request body

  • approve
    boolean
  • reason
    string | null

Response · 200 · object

  • id
    integerrequired
  • employee_id
    integerrequired
  • kind
    stringrequired
    bank: 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.
  • changes
    objectrequired
  • status
    stringrequired
    One of: pending, approved, rejected.
  • requested_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • decided_at
    string | nullrequired
  • reason
    string | nullrequired
  • created_at
    stringrequired
  • effective_date
    string | null
    Rate in effect from this date (time on earlier dates pays the previous rate)

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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/remittances

List payroll liability remittances

Newest first. Paginated (page/per_page; Total and Link headers). Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • request_key
    stringrequired
  • account_key
    stringrequired
    Engine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
  • account_id
    integerrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: bank, ap_bill.
  • bank_account_id
    integer | null
  • ap_bill_id
    integer | nullrequired
  • journal_entry_id
    integer | nullrequired
  • amount
    stringrequired
    Decimal string
  • through_date
    stringrequired
  • paid_date
    stringrequired
  • memo
    string | null
  • created_at
    string
  • status
    stringrequired
    pending_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_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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/remittances

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • remittance
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • request_key
    stringrequired
  • account_key
    stringrequired
    Engine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
  • account_id
    integerrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: bank, ap_bill.
  • bank_account_id
    integer | null
  • ap_bill_id
    integer | nullrequired
  • journal_entry_id
    integer | nullrequired
  • amount
    stringrequired
    Decimal string
  • through_date
    stringrequired
  • paid_date
    stringrequired
  • memo
    string | null
  • created_at
    string
  • status
    stringrequired
    pending_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_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace
  • 404Not found
  • 409Request key reused for a different remittance
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • decision
    stringpathrequired
    One of: approve, reject.

Response · 200 · object

  • id
    integerrequired
  • request_key
    stringrequired
  • account_key
    stringrequired
    Engine liability key (2110 FIT, 2111 FICA, 2112 SIT, 2113 FUTA, 2114 SUTA …)
  • account_id
    integerrequired
  • entity_id
    integerrequired
  • method
    stringrequired
    One of: bank, ap_bill.
  • bank_account_id
    integer | null
  • ap_bill_id
    integer | nullrequired
  • journal_entry_id
    integer | nullrequired
  • amount
    stringrequired
    Decimal string
  • through_date
    stringrequired
  • paid_date
    stringrequired
  • memo
    string | null
  • created_at
    string
  • status
    stringrequired
    pending_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_id
    integer
  • approved_by_id
    integer | null
  • approved_at
    string | null

Errors

  • 401Missing or invalid bearer token
  • 403No accounting access, missing payroll permission (payroll_view / payroll_run / view_payroll_pii / release_payments), wrong company, or read-only workspace
  • 404Not found
  • 409Not waiting for release, or decided concurrently
  • 422Validation or workflow error (closed period)

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • report
    stringpathrequired
    One of: form_941, form_940, w2, union_remittance, union_local_remittance, state_ui, deposit_calendar, w3.
  • year
    integerquery
    Tax year
  • quarter
    integerquery
    1-4
  • month
    stringquery
    YYYY-MM
  • format
    stringquery
    w2: json | efw2 | pdf; state_ui: json | csv; union_local_remittance: json | csv
  • local
    stringquery
    union_local_remittance: one remit-to local code
  • bso_user_id
    stringquery
    Required for efw2: attesting BSO user ID
  • contact_name
    stringquery
    Required for efw2
  • contact_phone
    stringquery
    Required for efw2: ten-digit domestic telephone (formatting allowed)
  • contact_email
    string (email)query
    Required for efw2: printable ASCII email
  • state
    stringquery
    state_ui: two-letter state
  • employer_entity_id
    integerquery
    form_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 token
  • 403No 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
  • 404Not found
  • 422Unsupported year/provisional option, invalid identity/contact, missing qualified-overtime detail, unsupported populated W-2 data, HSA contributions or unclassified retirement-plan source
  • 429Too many reveals or PII files; retry after the Retry-After seconds.

Example request

Generated from the contractcurl
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/runs

List pay runs

Newest pay date first. Filters: filters[status], filters[pay_group_id]. Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • page
    integerquery
    Page (1-based)
  • per_page
    integerquery
    Page size (max 1000)

Response · 200 · object[]

  • id
    integerrequired
  • number
    stringrequired
  • pay_group_id
    integerrequired
  • pay_group_code
    string | nullrequired
  • period_start
    stringrequired
  • period_end
    stringrequired
  • pay_date
    stringrequired
  • status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • revision
    integerrequired
  • gross_total
    stringrequired
    Decimal string
  • employee_taxes
    stringrequired
    Decimal string
  • deductions_total
    stringrequired
    Decimal string
  • net_total
    stringrequired
    Decimal string
  • employer_cost
    stringrequired
    Decimal string
  • check_count
    integer | nullrequired
  • exceptions
    object[]required
  • exceptions[].key
    stringrequired
  • exceptions[].code
    stringrequired
  • exceptions[].severity
    stringrequired
    One of: error, warning, info.
  • exceptions[].message
    stringrequired
  • exceptions[].employee_id
    integer | nullrequired
  • exceptions[].acknowledged
    booleanrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | nullrequired
  • posted_at
    string | nullrequired
  • journal_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No 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

Generated from the contractcurl
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/runs

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

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • pay_run
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • number
    stringrequired
  • pay_group_id
    integerrequired
  • pay_group_code
    string | nullrequired
  • period_start
    stringrequired
  • period_end
    stringrequired
  • pay_date
    stringrequired
  • status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • revision
    integerrequired
  • gross_total
    stringrequired
    Decimal string
  • employee_taxes
    stringrequired
    Decimal string
  • deductions_total
    stringrequired
    Decimal string
  • net_total
    stringrequired
    Decimal string
  • employer_cost
    stringrequired
    Decimal string
  • check_count
    integer | nullrequired
  • exceptions
    object[]required
  • exceptions[].key
    stringrequired
  • exceptions[].code
    stringrequired
  • exceptions[].severity
    stringrequired
    One of: error, warning, info.
  • exceptions[].message
    stringrequired
  • exceptions[].employee_id
    integer | nullrequired
  • exceptions[].acknowledged
    booleanrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | nullrequired
  • posted_at
    string | nullrequired
  • journal_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • explain
    booleanquery
    Include calculation traces

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • pay_group_id
    integerrequired
  • pay_group_code
    string | nullrequired
  • period_start
    stringrequired
  • period_end
    stringrequired
  • pay_date
    stringrequired
  • status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • revision
    integerrequired
  • gross_total
    stringrequired
    Decimal string
  • employee_taxes
    stringrequired
    Decimal string
  • deductions_total
    stringrequired
    Decimal string
  • net_total
    stringrequired
    Decimal string
  • employer_cost
    stringrequired
    Decimal string
  • check_count
    integer | nullrequired
  • exceptions
    object[]required
  • exceptions[].key
    stringrequired
  • exceptions[].code
    stringrequired
  • exceptions[].severity
    stringrequired
    One of: error, warning, info.
  • exceptions[].message
    stringrequired
  • exceptions[].employee_id
    integer | nullrequired
  • exceptions[].acknowledged
    booleanrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | nullrequired
  • posted_at
    string | nullrequired
  • journal_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • checks
    object[]required
  • checks[].id
    integerrequired
  • checks[].employee_id
    integerrequired
  • checks[].employee_number
    string | null
  • checks[].employee_name
    string | null
  • checks[].ssn_masked
    string | null
  • checks[].bank_account_masked
    string | null
  • checks[].payment_method
    string
  • checks[].pay_date
    string
  • checks[].hours
    string
  • checks[].regular_hours
    string
  • checks[].ot_hours
    string
  • checks[].dt_hours
    string
  • checks[].gross
    stringrequired
    Decimal string
  • checks[].employee_taxes
    string
    Decimal string
  • checks[].deductions
    string
    Decimal string
  • checks[].net
    stringrequired
    Decimal string
  • checks[].employer_cost
    string
    Decimal string
  • checks[].taxes
    object[]required
  • checks[].deduction_lines
    object[]required
  • checks[].exceptions
    any[]
  • checks[].explain
    object[]
  • checks[].check_number
    string | null
    Paper check number from the shared check register
  • checks[].suta_state
    string | null
  • checks[].employer_entity_id
    integer | nullrequired
    Employer of record: the entity with its own EIN, null = the company employer in payroll setup.
  • checks[].voided_at
    string | nullrequired
  • checks[].void_reason
    string | nullrequired
  • checks[].void_entry_id
    integer | nullrequired
  • time
    object[]required
  • time[].id
    integerrequired
  • time[].employee_id
    integerrequired
  • time[].date
    stringrequired
  • time[].hours
    stringrequired
  • time[].project_id
    integer | nullrequired
  • time[].cost_code_id
    integer | nullrequired
  • time[].classification
    string | nullrequired
  • time[].work_state
    string | nullrequired
  • time[].rate
    string | nullrequired
  • time[].timecard_entry_id
    integer | nullrequired
  • time[].locality
    string | nullrequired
  • time[].per_diem
    string | nullrequired
  • time[].per_diem_high_cost
    booleanrequired
  • time[].per_diem_away
    booleanrequired
  • time[].wc_class_code
    string | null
    Workers' comp class override for this line
  • last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No 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
  • 404Not found

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • action
    stringpathrequired
    GET: 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.
  • format
    stringquery
    register: csv

Response · 200 · object | object[]

  • posting_date
    stringrequired
  • journal
    stringrequired
  • memo
    string | nullrequired
  • source_type
    stringrequired
  • source_id
    integer | nullrequired
  • source_revision
    integerrequired
  • lines
    object[]required
  • lines[].account_id
    integerrequired
  • lines[].account_number
    string | nullrequired
  • lines[].account_name
    string | nullrequired
  • lines[].job_cost_type
    string | nullrequired
  • lines[].debit
    stringrequired
    Decimal string
  • lines[].credit
    stringrequired
    Decimal string
  • lines[].memo
    string | nullrequired
  • lines[].project_id
    integer | nullrequired
  • lines[].cost_code_id
    integer | nullrequired
  • lines[].hours
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 409The direct deposit file was already generated (re-send with nacha_resend)
  • 422Not calculated / not approved / setup incomplete

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • id
    integerpathrequired
  • action
    stringpathrequired
    GET: 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

  • resend
    objectrequired
  • resend.reason
    stringrequired
  • resend.previous_file_id_modifier
    stringrequired
    Last file reviewed by the caller, from last_ach_file_id_modifier on run detail.

Response · 200 · object

  • id
    integerrequired
  • number
    stringrequired
  • pay_group_id
    integerrequired
  • pay_group_code
    string | nullrequired
  • period_start
    stringrequired
  • period_end
    stringrequired
  • pay_date
    stringrequired
  • status
    stringrequired
    One of: draft, calculated, approved, posted, voided.
  • revision
    integerrequired
  • gross_total
    stringrequired
    Decimal string
  • employee_taxes
    stringrequired
    Decimal string
  • deductions_total
    stringrequired
    Decimal string
  • net_total
    stringrequired
    Decimal string
  • employer_cost
    stringrequired
    Decimal string
  • check_count
    integer | nullrequired
  • exceptions
    object[]required
  • exceptions[].key
    stringrequired
  • exceptions[].code
    stringrequired
  • exceptions[].severity
    stringrequired
    One of: error, warning, info.
  • exceptions[].message
    stringrequired
  • exceptions[].employee_id
    integer | nullrequired
  • exceptions[].acknowledged
    booleanrequired
  • prepared_by_id
    integerrequired
  • approved_by_id
    integer | nullrequired
  • approved_at
    string | nullrequired
  • posted_at
    string | nullrequired
  • journal_entry_id
    integer | nullrequired
  • void_reason
    string | nullrequired
  • run_type
    stringrequired
    Only regular runs are refused on an overlapping period One of: regular, off_cycle, correction, final.
  • last_ach_file_id_modifier
    string | null
    Latest 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 token
  • 403No 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
  • 404Not found
  • 409Approve: YTD changed since calculation (recalculate), approval inputs busy, or a conflicting state
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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/setup

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

v1.0Implemented

Parameters

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

Response · 200 · object

  • tax_provider
    stringrequired
  • tax_providers
    string[]required
  • burden_method
    stringrequired
  • default_ot_rule_set
    stringrequired
  • suta_state
    string | nullrequired
  • suta_rate
    string | nullrequired
  • suta_wage_base
    string | nullrequired
    Decimal string
  • state_flat_rates
    objectrequired
  • state_account_ids
    objectrequired
    State employer account numbers for EFW2 RS records, keyed by state
  • account_map
    object[]required
  • account_map[].key
    stringrequired
  • account_map[].label
    stringrequired
  • account_map[].account_number
    stringrequired
  • employer_ein_masked
    string | nullrequired
  • employer_name
    string | nullrequired
  • employer_address
    string | nullrequired
  • employer_city
    string | nullrequired
  • employer_state
    string | nullrequired
  • employer_zip
    string | nullrequired
  • ach_odfi_routing
    string | nullrequired
  • ach_bank_name
    string | nullrequired
  • ach_account_masked
    string | nullrequired
  • local_flat_rates
    objectrequired
    Stub rates for localities without built-in data, keyed ST:City
  • sdi_rates
    objectrequired
    Company-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_rate
    string | nullrequired
  • burden_true_up_to
    stringrequired
    One of: jobs, overhead.
  • per_diem_accountable
    booleanrequired
  • per_diem_federal_rate
    string | nullrequired
  • suta_rates
    object
    SUTA rate and wage base per state; a check uses its localization state
  • filed_periods
    string[]
    Filed payroll return periods: 2026-Q1 (941 / state UI) and 2026 (W-2 / 940)

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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/setup

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

v1.0Implemented

Parameters

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

Request body

  • payroll_setup
    objectrequired

Response · 200 · object

  • tax_provider
    stringrequired
  • tax_providers
    string[]required
  • burden_method
    stringrequired
  • default_ot_rule_set
    stringrequired
  • suta_state
    string | nullrequired
  • suta_rate
    string | nullrequired
  • suta_wage_base
    string | nullrequired
    Decimal string
  • state_flat_rates
    objectrequired
  • state_account_ids
    objectrequired
    State employer account numbers for EFW2 RS records, keyed by state
  • account_map
    object[]required
  • account_map[].key
    stringrequired
  • account_map[].label
    stringrequired
  • account_map[].account_number
    stringrequired
  • employer_ein_masked
    string | nullrequired
  • employer_name
    string | nullrequired
  • employer_address
    string | nullrequired
  • employer_city
    string | nullrequired
  • employer_state
    string | nullrequired
  • employer_zip
    string | nullrequired
  • ach_odfi_routing
    string | nullrequired
  • ach_bank_name
    string | nullrequired
  • ach_account_masked
    string | nullrequired
  • local_flat_rates
    objectrequired
    Stub rates for localities without built-in data, keyed ST:City
  • sdi_rates
    objectrequired
    Company-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_rate
    string | nullrequired
  • burden_true_up_to
    stringrequired
    One of: jobs, overhead.
  • per_diem_accountable
    booleanrequired
  • per_diem_federal_rate
    string | nullrequired
  • suta_rates
    object
    SUTA rate and wage base per state; a check uses its localization state
  • filed_periods
    string[]
    Filed payroll return periods: 2026-Q1 (941 / state UI) and 2026 (W-2 / 940)

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_locals

List union locals

Locals with their effective-dated CBA rates and benefit rules. Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • remit_to
    string | nullrequired
  • cba_rules
    object | nullrequired
    CBA day rules: weekday 0 = Sunday ... 6 = Saturday
  • cba_rules.day_multipliers
    object
  • cba_rules.holidays
    string (date)[]
  • cba_rules.holiday_multiplier
    string
    One of: 1.5, 2.
  • rates
    object[]required
  • rates[].id
    integerrequired
  • rates[].local_id
    integerrequired
  • rates[].classification
    stringrequired
  • rates[].zone
    string | nullrequired
  • rates[].effective_from
    stringrequired
  • rates[].effective_to
    string | nullrequired
  • rates[].wage
    stringrequired
  • rates[].benefits
    object[]required
  • rates[].apprentice_ratio
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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_locals

Create a union local

Needs payroll_run; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • union_local
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • remit_to
    string | nullrequired
  • cba_rules
    object | nullrequired
    CBA day rules: weekday 0 = Sunday ... 6 = Saturday
  • cba_rules.day_multipliers
    object
  • cba_rules.holidays
    string (date)[]
  • cba_rules.holiday_multiplier
    string
    One of: 1.5, 2.
  • rates
    object[]required
  • rates[].id
    integerrequired
  • rates[].local_id
    integerrequired
  • rates[].classification
    stringrequired
  • rates[].zone
    string | nullrequired
  • rates[].effective_from
    stringrequired
  • rates[].effective_to
    string | nullrequired
  • rates[].wage
    stringrequired
  • rates[].benefits
    object[]required
  • rates[].apprentice_ratio
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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.

v1.0Implemented

Parameters

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

Request body

  • union_local
    objectrequired

Response · 200 · object

  • id
    integerrequired
  • code
    stringrequired
  • name
    stringrequired
  • remit_to
    string | nullrequired
  • cba_rules
    object | nullrequired
    CBA day rules: weekday 0 = Sunday ... 6 = Saturday
  • cba_rules.day_multipliers
    object
  • cba_rules.holidays
    string (date)[]
  • cba_rules.holiday_multiplier
    string
    One of: 1.5, 2.
  • rates
    object[]required
  • rates[].id
    integerrequired
  • rates[].local_id
    integerrequired
  • rates[].classification
    stringrequired
  • rates[].zone
    string | nullrequired
  • rates[].effective_from
    stringrequired
  • rates[].effective_to
    string | nullrequired
  • rates[].wage
    stringrequired
  • rates[].benefits
    object[]required
  • rates[].apprentice_ratio
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 404Not found
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_rates

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

v1.0Implemented

Parameters

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

Request body

  • union_rate
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • local_id
    integerrequired
  • classification
    stringrequired
  • zone
    string | nullrequired
  • effective_from
    stringrequired
  • effective_to
    string | nullrequired
  • wage
    stringrequired
  • benefits
    object[]required
  • benefits[].code
    string
  • benefits[].fund
    string
  • benefits[].local
    string
  • benefits[].basis
    string
    One of: per_hour, pct_gross, per_day.
  • benefits[].amount
    string | number
  • benefits[].kind
    string
    One of: employer_fringe, employee_deduction.
  • benefits[].reciprocal
    boolean
  • benefits[].plan
    string
    One of: retirement, health, other.
  • apprentice_ratio
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_determinations

List wage determinations

Prevailing wage BHR + fringe per project and classification, with the apprentice ratio. Needs payroll_view. Requires the accounting:read scope.

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
  • wd_number
    stringrequired
  • county
    string | nullrequired
  • classification
    stringrequired
  • bhr
    stringrequired
  • fringe
    stringrequired
  • effective_from
    stringrequired
  • effective_to
    string | nullrequired
  • apprentice_ratio
    string | nullrequired
  • dir_project_id
    string | nullrequired
  • awarding_body
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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_determinations

Create a wage determination

Needs payroll_run; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • wage_determination
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • wd_number
    stringrequired
  • county
    string | nullrequired
  • classification
    stringrequired
  • bhr
    stringrequired
  • fringe
    stringrequired
  • effective_from
    stringrequired
  • effective_to
    string | nullrequired
  • apprentice_ratio
    string | nullrequired
  • dir_project_id
    string | nullrequired
  • awarding_body
    string | nullrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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_classes

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

v1.0Implemented

Parameters

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

Response · 200 · object[]

  • id
    integerrequired
  • state
    stringrequired
  • code
    stringrequired
  • name
    stringrequired
  • rate_per_100
    string | nullrequired
  • rate_per_hour
    string | nullrequired
  • exclude_ot_premium
    booleanrequired
  • effective_from
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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

Generated from the contractcurl
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_classes

Create a wc class

Needs payroll_run; audited. Requires the accounting:write scope.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
    Company id; must be the token's company
  • Idempotency-Key
    stringheader
    Client retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.

Request body

  • wc_class
    objectrequired

Response · 201 · object

  • id
    integerrequired
  • state
    stringrequired
  • code
    stringrequired
  • name
    stringrequired
  • rate_per_100
    string | nullrequired
  • rate_per_hour
    string | nullrequired
  • exclude_ot_premium
    booleanrequired
  • effective_from
    stringrequired

Errors

  • 401Missing or invalid bearer token
  • 403No 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
  • 422Validation or workflow error

Example request

Generated from the contractcurl
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": {}
}'

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file