Accounts Payable
Code bills, resolve holds and release approved payment runs. 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 Accounts Payable guide for the workflow.
- GET
/rest/v1.0/companies/{company_id}/accounting/ap/agingAP aging as of a date - GET
/rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsGet AP automation settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsUpdate AP automation settings - GET
/rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesList CP2100 B notices - POST
/rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesRecord a CP2100 B notice - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}Mark a B notice letter sent or record the cure - GET
/rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}/letterB notice letter - GET
/rest/v1.0/companies/{company_id}/accounting/ap/billsList bills and vendor credits - POST
/rest/v1.0/companies/{company_id}/accounting/ap/billsCreate a draft bill or vendor credit - GET
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Show a bill - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Edit a draft or pending bill - DELETE
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Delete a draft bill - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/apply_creditApply a vendor credit to a bill - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/approveApprove a bill - GET
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsList attachments on a bill - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsAttach a file to a bill - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/override_holdOverride a hold - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rejectReject a bill (return to the preparer) - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/release_retainageRelease retainage payable - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rematchRe-run the three-way match - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/submitSubmit a bill for approval - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/unapply_creditUndo a vendor credit application - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/voidVoid a posted bill - POST
/rest/v1.0/companies/{company_id}/accounting/ap/bills/from_sourceDraft a bill from a requisition or direct cost - GET
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsList the capture inbox - POST
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsUpload a bill document to the capture inbox - GET
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Get a captured document - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Key, assign or progress a captured document - POST
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/draft_billDraft a bill from a captured document - GET
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/fileDownload a captured file - POST
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/rejectReject a captured document - GET
/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/suggestionsCoding suggestions for a captured document - POST
/rest/v1.0/companies/{company_id}/accounting/ap/checks/{id}/reprintReprint a check under a new number - GET
/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsList compliance requirements - POST
/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsRequire a compliance document - DELETE
/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirements/{id}Drop a compliance requirement - GET
/rest/v1.0/companies/{company_id}/accounting/ap/form_10991099 review - GET
/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/copy_b1099 recipient Copy B - POST
/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/irisExport 1099s as IRIS Taxpayer Portal CSV files - POST
/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/pub1220Export 1099s as an IRS Pub 1220 file - GET
/rest/v1.0/companies/{company_id}/accounting/ap/form_945Form 945 data - POST
/rest/v1.0/companies/{company_id}/accounting/ap/form_945/eftpsEFTPS 945 deposits - GET
/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptionsList three-way match exceptions - GET
/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}Show a match exception - POST
/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}/overrideOverride a match exception - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runsList payment runs - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runsCreate a draft payment run - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Show a payment run - DELETE
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Delete a draft run - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/checksCheck print data - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaACH (NACHA) file - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaRe-send the ACH (NACHA) file - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/positive_payPositive pay file (CSV) - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/rejectReject a payment run release - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/releaseRelease (approve) and post a payment run - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payment_selectionPayment selection - GET
/rest/v1.0/companies/{company_id}/accounting/ap/paymentsList payments - POST
/rest/v1.0/companies/{company_id}/accounting/ap/paymentsCreate one manual payment - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}Show a payment - GET
/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittanceGet a payment's remittance advice - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittance/sendEmail a payment's remittance advice - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/virtual_card/issueRetry a virtual card issue - POST
/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/voidVoid a payment - GET
/rest/v1.0/companies/{company_id}/accounting/ap/receiptsList PO receipts - POST
/rest/v1.0/companies/{company_id}/accounting/ap/receiptsReceive against a purchase order - POST
/rest/v1.0/companies/{company_id}/accounting/ap/receipts/{id}/voidVoid a PO receipt - POST
/rest/v1.0/companies/{company_id}/accounting/ap/retainage_releases/{id}/voidVoid a retainage release - GET
/rest/v1.0/companies/{company_id}/accounting/ap/settingsAP settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/settingsUpdate AP settings - GET
/rest/v1.0/companies/{company_id}/accounting/ap/tie_outAP subledger tie-out - POST
/rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/exportExport an IRS bulk TIN Matching request file - POST
/rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/importImport IRS bulk TIN Matching results - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requestsList portal bank change requests - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/forwardForward a bank change request for approval - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/rejectReject a bank change request - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grantsList vendor portal users - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grants/{id}/revokeRevoke a vendor portal user's access - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsList vendor portal invitations - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsInvite a user to a vendor's portal - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitations/{id}/revokeRevoke a pending invitation - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissionsList portal compliance submissions - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/acceptAccept a portal compliance submission - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/rejectReject a portal compliance submission - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendorsList AP vendors - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}Show an AP vendor - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsList attachments on a vendor - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsAttach a file to a vendor - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationGet a vendor's remittance and capture settings - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationUpdate a vendor's remittance and capture settings - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/complianceRecord a compliance document - PATCH
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}Lift or reinstate a compliance record - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}/attachmentsList attachments on a vendor compliance record (COI, W-9, license) - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}/attachmentsAttach a file to a vendor compliance record (COI, W-9, license) - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waiversRecord a lien waiver received - GET
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsList attachments on a lien waiver - POST
/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsAttach a file to a lien waiver - GET
/rest/v1.0/companies/{company_id}/accounting/ap/virtual_cardsList virtual card payments - POST
/rest/v1.0/companies/{company_id}/accounting/ap/virtual_cards/sync_settlementsSync virtual card settlements
Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/agingAP aging as of a date
Rebuilt from documents and dated applications, so a past aging re-performs exactly. Retainage is aged separately. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- basisstringqueryOne of: due, document.
Response · 200 · object
- as_ofstring (date)required
- basisstringrequired
- bucket_labelsstring[]required
- rowsobject[]required
- rows[].vendor_idintegerrequired
- rows[].vendor_namestring | nullrequired
- rows[].bucketsstring[]required
- rows[].retainagestringrequiredMoney, 2 dp
- rows[].totalstringrequiredMoney, 2 dp
- totalsobjectrequired
- totals.bucketsstring[]required
- totals.retainagestringrequiredMoney, 2 dp
- totals.totalstringrequiredMoney, 2 dp
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/aging" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsGet AP automation settings
Capture address and allow list, vendor portal, remittance and virtual card settings. A project-scoped grant gets 403. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- capture_enabledbooleanrequired
- capture_addressstring | nullap+<token>@ACCT_AP_CAPTURE_DOMAIN; null when capture by email is not deployed.
- capture_allowed_sendersstring[]
- portal_enabledbooleanrequired
- remittance_enabledbooleanrequired
- virtual_card_enabledbooleanrequired
- virtual_card_providerstring
- virtual_card_clearing_account_idinteger | null
- virtual_card_funding_bank_account_idinteger | null
- updated_atstring | null (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/automation/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/automation/settingsUpdate AP automation settings
Needs manage_coa. Virtual card fields also need release_payments and step-up; enabling virtual cards needs a non-control liability clearing account and an active bank (not card) funding account. rotate_capture_address issues a new capture address at once. Audited with the values before and after. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- automation_settingsobjectrequired
- automation_settings.capture_enabledboolean
- automation_settings.capture_allowed_sendersstring[]
- automation_settings.rotate_capture_addressboolean
- automation_settings.portal_enabledboolean
- automation_settings.remittance_enabledboolean
- automation_settings.virtual_card_enabledboolean
- automation_settings.virtual_card_clearing_account_idinteger | null
- automation_settings.virtual_card_funding_bank_account_idinteger | null
Response · 200 · object
- capture_enabledbooleanrequired
- capture_addressstring | nullap+<token>@ACCT_AP_CAPTURE_DOMAIN; null when capture by email is not deployed.
- capture_allowed_sendersstring[]
- portal_enabledbooleanrequired
- remittance_enabledbooleanrequired
- virtual_card_enabledbooleanrequired
- virtual_card_providerstring
- virtual_card_clearing_account_idinteger | null
- virtual_card_funding_bank_account_idinteger | null
- updated_atstring | null (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/automation/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"automation_settings": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesList CP2100 B notices
B notice records, newest first. Filter with vendor_id. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- vendor_idintegerquery
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- notice_numberintegerrequiredOne of: 1, 2.
- notice_datestring (date)required
- tax_yearinteger | nullrequired
- letter_due_bystring (date)requirednotice_date + 15 IRS business days (Pub 1281).
- withhold_fromstring (date)requirednotice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
- letter_sent_atstring | null (date)required
- cured_atstring | null (date)required
- cure_kindstring | nullrequiredOne of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/backup_notices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/backup_noticesRecord a CP2100 B notice
Records a vendor listed on an IRS CP2100/CP2100A notice. notice_date is the CP2100 date or the date received, whichever is later. The letter is due within 15 business days, and 24% backup withholding applies to AP payments dated on or after notice_date + 30 IRS business days until the notice is cured (Pub 1281). notice_number defaults to 2 when the vendor already had a notice in the same or the two preceding calendar years. Needs ap_enter; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- backup_noticeobjectrequired
- backup_notice.vendor_idintegerrequired
- backup_notice.notice_datestring (date)required
- backup_notice.tax_yearinteger | null
- backup_notice.notice_numberinteger | nullOne of: 1, 2, null.
Response · 201 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- notice_numberintegerrequiredOne of: 1, 2.
- notice_datestring (date)required
- tax_yearinteger | nullrequired
- letter_due_bystring (date)requirednotice_date + 15 IRS business days (Pub 1281).
- withhold_fromstring (date)requirednotice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
- letter_sent_atstring | null (date)required
- cured_atstring | null (date)required
- cure_kindstring | nullrequiredOne of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/backup_notices" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"backup_notice": {
"vendor_id": 1,
"notice_date": "2026-11-01"
}
}'Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}Mark a B notice letter sent or record the cure
letter_sent_at records the mailing date (ap_enter). cured_at with cure_kind stops backup withholding from that date and needs manage_vendor_banking: a first notice is cured only by a signed W-9 (w9); a second notice only by SSA or IRS validation (ssa_card, letter_147c, letter_685c, letter_096c), otherwise 422 cure_not_allowed. A cure is final (409 already_cured). Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- backup_noticeobjectrequired
- backup_notice.letter_sent_atstring | null (date)
- backup_notice.cured_atstring | null (date)
- backup_notice.cure_kindstring | nullOne of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- notice_numberintegerrequiredOne of: 1, 2.
- notice_datestring (date)required
- tax_yearinteger | nullrequired
- letter_due_bystring (date)requirednotice_date + 15 IRS business days (Pub 1281).
- withhold_fromstring (date)requirednotice_date + 30 IRS business days: 24% backup withholding applies to AP payments from this date until cured.
- letter_sent_atstring | null (date)required
- cured_atstring | null (date)required
- cure_kindstring | nullrequiredOne of: w9, ssa_card, letter_147c, letter_685c, letter_096c, null.
- created_by_idintegerrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/backup_notices/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"backup_notice": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/backup_notices/{id}/letterB notice letter
The first or second B notice letter header for the vendor (reply-by date, account number, name, masked TIN, 24% rate) and the opening paragraph of the IRS text (Pub 1281 Rev. 12-2023, Part 4). Enclose the rest of the IRS notice text (and Form W-9 for a first notice); mail it in an envelope marked IMPORTANT TAX INFORMATION ENCLOSED. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- filenamestringrequired
- textstringrequired
- envelopestringrequired
- letter_due_bystring (date)required
- notice_numberintegerrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/backup_notices/1/letter" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/billsList bills and vendor credits
Filters: filters[status], filters[kind], vendor_id, project_id, due_by, search. Paginated (Total, Per-Page headers). Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- filters[status]stringquery
- filters[kind]stringquery
- vendor_idintegerquery
- project_idintegerquery
- due_bystring (date)query
- searchstringquery
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/billsCreate a draft bill or vendor credit
Needs ap_enter. Retainage defaults from the commitment, then the vendor profile; due and discount dates from terms. A suspected duplicate (same vendor, normalized invoice number) returns 409 duplicate_suspected unless an ap_approve user sends duplicate_override_reason (audited). A vendor inactive in the directory returns 409 vendor_inactive unless an ap_approve user sends inactive_vendor_override_reason (audited). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- billobjectrequired
- bill.kindstring
- bill.vendor_idintegerrequired
- bill.entity_idinteger | null
- bill.invoice_numberstring | null
- bill.invoice_datestring (date)required
- bill.posting_datestring (date)
- bill.due_datestring (date)
- bill.term_idinteger | null
- bill.memostring | null
- bill.retainage_percentstring | null
- bill.tax_code_idinteger | null
- bill.commitment_typestring | null
- bill.commitment_idinteger | null
- bill.pay_when_paid_pay_app_idinteger | null
- bill.pay_when_paid_modestring | null
- bill.off_rent_datestring | null (date)
- bill.billed_throughstring | null (date)
- bill.duplicate_override_reasonstring | null
- bill.inactive_vendor_override_reasonstring | nullBill a vendor that is inactive in the directory (otherwise 409 vendor_inactive). ap_approve only (403); audited as inactive_vendor_overridden. Credits are not refused.
- bill.linesobject[]required
- bill.lines[].account_idintegerrequired
- bill.lines[].amountstringrequired
- bill.lines[].descriptionstring | null
- bill.lines[].retainage_percentstring | null
- bill.lines[].retainage_amountstring | nullExplicit retainage (at most the line amount); overrides retainage_percent.
- bill.lines[].project_idinteger | null
- bill.lines[].cost_code_idinteger | null
- bill.lines[].cost_type_idinteger | null
- bill.lines[].equipment_idinteger | null
- bill.lines[].commitment_line_item_idinteger | null
- bill.lines[].quantitystring | null
- bill.lines[].unit_pricestring | null
- bill.lines[].use_taxbooleanOmitted on an untaxed material line of a job whose tax profile accrues use tax (consumer states such as CA): defaults to true, and the bill tax code defaults to the job use tax code.
- bill.lines[].reportable_1099boolean
- bill.lines[].tax_categorystring | nullOne of: material, fixture, labor, equipment, null.
- bill.lines[].dimension_value_idsarray | nullUser-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"bill": {
"vendor_id": 1,
"invoice_date": "2026-11-01",
"lines": [
{
"account_id": 1,
"amount": "0.00"
}
]
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Show a bill
Lines, approvals for the current revision, applications, retainage releases, current payment holds and the approval route preview. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Edit a draft or pending bill
Every PATCH, including a partial header-only edit, requires bill.expected_revision from the last read. Missing or invalid tokens return 422; a stale token returns 409 stale_revision without changing the bill. Reload and review before retrying. Any edit bumps the revision and returns the bill to draft; approvals of earlier revisions no longer count. Replacing lines or changing tax_code_id recalculates use_tax_amount; tax_code_id null while a line has use_tax returns 422. Needs ap_enter. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- billobjectrequired
- bill.expected_revisionintegerrequiredRevision returned by the last bill read; required for every edit.
- bill.kindstring
- bill.vendor_idinteger
- bill.entity_idinteger | null
- bill.invoice_numberstring | null
- bill.invoice_datestring (date)
- bill.posting_datestring (date)
- bill.due_datestring (date)
- bill.term_idinteger | null
- bill.memostring | null
- bill.retainage_percentstring | null
- bill.tax_code_idinteger | null
- bill.commitment_typestring | null
- bill.commitment_idinteger | null
- bill.pay_when_paid_pay_app_idinteger | null
- bill.pay_when_paid_modestring | null
- bill.off_rent_datestring | null (date)
- bill.billed_throughstring | null (date)
- bill.duplicate_override_reasonstring | null
- bill.inactive_vendor_override_reasonstring | nullBill a vendor that is inactive in the directory (otherwise 409 vendor_inactive). ap_approve only (403); audited as inactive_vendor_overridden. Credits are not refused.
- bill.linesobject[]
- bill.lines[].account_idintegerrequired
- bill.lines[].amountstringrequired
- bill.lines[].descriptionstring | null
- bill.lines[].retainage_percentstring | null
- bill.lines[].retainage_amountstring | nullExplicit retainage (at most the line amount); overrides retainage_percent.
- bill.lines[].project_idinteger | null
- bill.lines[].cost_code_idinteger | null
- bill.lines[].cost_type_idinteger | null
- bill.lines[].equipment_idinteger | null
- bill.lines[].commitment_line_item_idinteger | null
- bill.lines[].quantitystring | null
- bill.lines[].unit_pricestring | null
- bill.lines[].use_taxbooleanOmitted on an untaxed material line of a job whose tax profile accrues use tax (consumer states such as CA): defaults to true, and the bill tax code defaults to the job use tax code.
- bill.lines[].reportable_1099boolean
- bill.lines[].tax_categorystring | nullOne of: material, fixture, labor, equipment, null.
- bill.lines[].dimension_value_idsarray | nullUser-defined dimension values (AcctDimensionValue ids), at most one per dimension; see oas-dimensions.json.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (stale_revision or duplicate_suspected)422Validation failed or the ledger refused the change
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"bill": {
"expected_revision": 1
}
}'Accounting / Accounts Payable
DELETE/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}Delete a draft bill
Needs ap_enter. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/apply_creditApply a vendor credit to a bill
The path id is the credit. Same vendor, both posted; no GL effect. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- applicationobjectrequired
- application.bill_idintegerrequired
- application.amountstringrequired
- application.datestring (date)required
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/apply_credit" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"application": {
"bill_id": 1,
"amount": "0.00",
"date": "2026-11-01"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/approveApprove a bill
Needs ap_approve. Segregation of duties: the preparer or last editor cannot approve (403 sod_maker_checker); one vote per user per revision (409 already_approved). The route comes from the lowest-priority active ap_bill approval rule matching the bill (amount, entity, project, vendor risk); with none, amount bands set the number of approvals and the final approver role. The route is snapshotted at submit. A caller not on the current step gets 403 approver_role_required unless an active delegation lets them act for someone who is. The final approval posts the bill (Dr cost / Cr AP / Cr retainage payable, use tax accrual) in the same transaction; a match exception returns 409 match_exception. In small-team SoD mode (settings sod_mode) a maker may approve their own document by sending approve.reason; the event is audited as self_approved and listed by approvals/self_approved. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- approveobject
- approve.reasonstringRequired only to approve your own document in small-team SoD mode (422 self_approval_reason_required); the approval is flagged self_approved.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/approve" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"approve": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsList attachments on a bill
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/attachmentsAttach a file to a bill
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs ap_enter and the parent's entity scope. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/override_holdOverride a hold
Needs ap_approve (and release_payments for payment holds). Audited with the reason. The preparer cannot override; the bank-change cool-off cannot be overridden. Requires the accounting:write scope. expires_at (optional date) limits the override to pay dates on or before it, so a later lapse holds again. Code match_exception also overrides every open three-way match exception on the bill (each audited with the reason).
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- overrideobjectrequired
- override.codestringrequired
- override.reasonstringrequired
- override.expires_atstring | null (date)
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/override_hold" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"override": {
"code": "string",
"reason": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rejectReject a bill (return to the preparer)
Needs ap_approve and the bill's entity. A pending_approval bill returns to draft with a new revision, so votes on the rejected revision are spent and resubmission routes afresh. The reason is required and audited (action rejected); the preparer sees it in their approvals inbox. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rejectobjectrequired
- reject.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, or wrong company404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reject": {
"reason": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/release_retainageRelease retainage payable
Needs ap_approve. Posts Dr retainage payable / Cr AP. A final release needs the vendor's conditional final, prior unconditional progress and every lower tier's unconditional final waiver (422 missing_closeout_docs); pay-when-paid bills need owner_released. Send an Idempotency-Key: a retried partial release otherwise releases twice. Void a release with POST ap/retainage_releases/{id}/void. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- releaseobjectrequired
- release.datestring (date)required
- release.amountstring
- release.finalboolean
- release.owner_releasedboolean
- release.lower_tier_partiesstring[]
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/release_retainage" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"release": {
"date": "2026-11-01"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/rematchRe-run the three-way match
Re-evaluates a bill pending approval on live figures (receipts, other posted bills, approved change orders, the current match policy): exceptions no longer found are resolved (re_evaluated), new ones open and hold the bill. Receipts, bill posts and voids on the same commitment do this automatically. Needs ap_enter. 422 not_pending for any other status. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/rematch" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/submitSubmit a bill for approval
Runs the commitment / three-way match and stores the result; over-commitment with action block returns 409. Resolves and snapshots the approval route (409 approver_unresolved when no project-team member for a project-role step can approve, or a named user approver prepared the bill or lacks the approve grant). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/submit" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/unapply_creditUndo a vendor credit application
The path id is the credit. Reopens the credit and the bill as of date (on or after the application date), so either can be voided; as-of aging before that date still shows the application. No GL effect. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- applicationobjectrequired
- application.application_idintegerrequired
- application.datestring (date)required
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/unapply_credit" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"application": {
"application_id": 1,
"date": "2026-11-01"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/{id}/voidVoid a posted bill
Needs ap_approve. Posts a reversing entry on the given date (must be in an open period). Bills with payments, credit applications or retainage releases return 409. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/bills/from_sourceDraft a bill from a requisition or direct cost
Approved subcontract requisition → draft bill for the period delta (never the cumulative claim), coded to the subcontract job cost account; approved direct cost → draft bill by line type. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- sourceobjectrequired
- source.requisition_idinteger | null
- source.direct_cost_idinteger | null
- source.invoice_datestring (date)
Response · 201 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/bills/from_source" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"source": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsList the capture inbox
Captured bill documents, oldest first. Filters: status (comma-separated new, in_progress, drafted, rejected), source (upload, email, portal), vendor_id (keyed or suggested), assigned_to_id, unassigned=true, search (number, invoice number, sender, file name). Paginated (Total, Per-Page, Link). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- statusstringquery
- sourcestringquery
- searchstringquery
- vendor_idintegerquery
- assigned_to_idintegerquery
- unassignedbooleanquery
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- sourcestringrequiredOne of: upload, email, portal.
- statusstringrequiredOne of: new, in_progress, drafted, rejected.
- kindstringOne of: invoice, pay_app.
- sender_emailstring | null
- sender_namestring | null
- subjectstring | null
- received_atstring (date-time)required
- fileobjectrequired
- file.namestringrequired
- file.content_typestringrequired
- file.size_bytesintegerrequired
- file.sha256stringrequired
- file.scan_statusstringrequiredOne of: clean, internal_upload, unscanned_local, infected.
- file.download_urlstring | null
- vendorobject | null
- vendor.idinteger
- vendor.namestring | null
- suggested_vendorobject | null
- suggested_vendor.idinteger
- suggested_vendor.namestring | null
- invoice_numberstring | null
- invoice_datestring | null (date)
- amountstring | null
- notesstring | null
- duplicatesobject[]required
- duplicates[].kindstringrequiredOne of: file_hash, vendor_invoice.
- duplicates[].captured_document_idinteger
- duplicates[].bill_idinteger
- duplicates[].numberstringrequired
- assigned_toobject | null
- assigned_to.idinteger
- assigned_to.namestring | null
- portal_grant_idinteger | null
- billobject | null
- bill.idinteger
- bill.numberstring | null
- bill.statusstring | null
- reject_reasonstring | null
- drafted_atstring | null (date-time)
- rejected_atstring | null (date-time)
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/capture/documentsUpload a bill document to the capture inbox
One file (multipart field file; optional kind invoice | pay_app and notes) under the accounting attachment size and type rules. Needs ap_enter. The document is checked for duplicates by file hash at once (and by vendor + invoice number once keyed). Nothing is read out of the file: there is no OCR or AI extraction. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
- kindstringOne of: invoice, pay_app.
- notesstring
Response · 201 · object
- idintegerrequired
- numberstringrequired
- sourcestringrequiredOne of: upload, email, portal.
- statusstringrequiredOne of: new, in_progress, drafted, rejected.
- kindstringOne of: invoice, pay_app.
- sender_emailstring | null
- sender_namestring | null
- subjectstring | null
- received_atstring (date-time)required
- fileobjectrequired
- file.namestringrequired
- file.content_typestringrequired
- file.size_bytesintegerrequired
- file.sha256stringrequired
- file.scan_statusstringrequiredOne of: clean, internal_upload, unscanned_local, infected.
- file.download_urlstring | null
- vendorobject | null
- vendor.idinteger
- vendor.namestring | null
- suggested_vendorobject | null
- suggested_vendor.idinteger
- suggested_vendor.namestring | null
- invoice_numberstring | null
- invoice_datestring | null (date)
- amountstring | null
- notesstring | null
- duplicatesobject[]required
- duplicates[].kindstringrequiredOne of: file_hash, vendor_invoice.
- duplicates[].captured_document_idinteger
- duplicates[].bill_idinteger
- duplicates[].numberstringrequired
- assigned_toobject | null
- assigned_to.idinteger
- assigned_to.namestring | null
- portal_grant_idinteger | null
- billobject | null
- bill.idinteger
- bill.numberstring | null
- bill.statusstring | null
- reject_reasonstring | null
- drafted_atstring | null (date-time)
- rejected_atstring | null (date-time)
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
400Malformed body or Idempotency-Key401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace409Conflict (state guard)413File too large422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Get a captured document
With its duplicate findings, keyed header, assignment and the bill drafted from it. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- sourcestringrequiredOne of: upload, email, portal.
- statusstringrequiredOne of: new, in_progress, drafted, rejected.
- kindstringOne of: invoice, pay_app.
- sender_emailstring | null
- sender_namestring | null
- subjectstring | null
- received_atstring (date-time)required
- fileobjectrequired
- file.namestringrequired
- file.content_typestringrequired
- file.size_bytesintegerrequired
- file.sha256stringrequired
- file.scan_statusstringrequiredOne of: clean, internal_upload, unscanned_local, infected.
- file.download_urlstring | null
- vendorobject | null
- vendor.idinteger
- vendor.namestring | null
- suggested_vendorobject | null
- suggested_vendor.idinteger
- suggested_vendor.namestring | null
- invoice_numberstring | null
- invoice_datestring | null (date)
- amountstring | null
- notesstring | null
- duplicatesobject[]required
- duplicates[].kindstringrequiredOne of: file_hash, vendor_invoice.
- duplicates[].captured_document_idinteger
- duplicates[].bill_idinteger
- duplicates[].numberstringrequired
- assigned_toobject | null
- assigned_to.idinteger
- assigned_to.namestring | null
- portal_grant_idinteger | null
- billobject | null
- bill.idinteger
- bill.numberstring | null
- bill.statusstring | null
- reject_reasonstring | null
- drafted_atstring | null (date-time)
- rejected_atstring | null (date-time)
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}Key, assign or progress a captured document
Needs ap_enter. Keying vendor, invoice number, date or amount moves a new document to in_progress and re-runs the duplicate check. The assignee must be an active user who can enter AP bills. A drafted or rejected document is final (409 capture_closed). Audited with the values before and after. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- captured_documentobjectrequired
- captured_document.vendor_idinteger | null
- captured_document.kindstringOne of: invoice, pay_app.
- captured_document.invoice_numberstring | null
- captured_document.invoice_datestring | null (date)
- captured_document.amountstring | null
- captured_document.notesstring | null
- captured_document.assigned_to_idinteger | null
- captured_document.statusstringOne of: new, in_progress.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- sourcestringrequiredOne of: upload, email, portal.
- statusstringrequiredOne of: new, in_progress, drafted, rejected.
- kindstringOne of: invoice, pay_app.
- sender_emailstring | null
- sender_namestring | null
- subjectstring | null
- received_atstring (date-time)required
- fileobjectrequired
- file.namestringrequired
- file.content_typestringrequired
- file.size_bytesintegerrequired
- file.sha256stringrequired
- file.scan_statusstringrequiredOne of: clean, internal_upload, unscanned_local, infected.
- file.download_urlstring | null
- vendorobject | null
- vendor.idinteger
- vendor.namestring | null
- suggested_vendorobject | null
- suggested_vendor.idinteger
- suggested_vendor.namestring | null
- invoice_numberstring | null
- invoice_datestring | null (date)
- amountstring | null
- notesstring | null
- duplicatesobject[]required
- duplicates[].kindstringrequiredOne of: file_hash, vendor_invoice.
- duplicates[].captured_document_idinteger
- duplicates[].bill_idinteger
- duplicates[].numberstringrequired
- assigned_toobject | null
- assigned_to.idinteger
- assigned_to.namestring | null
- portal_grant_idinteger | null
- billobject | null
- bill.idinteger
- bill.numberstring | null
- bill.statusstring | null
- reject_reasonstring | null
- drafted_atstring | null (date-time)
- rejected_atstring | null (date-time)
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"captured_document": {}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/draft_billDraft a bill from a captured document
Needs ap_enter. The AP bill body with the clerk's manual coding; vendor_id and invoice_date default to the keyed header, invoice_number too. The bill must name the keyed vendor (422 vendor_mismatch) and, when an amount was keyed, its lines must total it (422 amount_mismatch). The usual vendor + invoice number duplicate check applies (409 duplicate_suspected unless an AP approver overrides). Creates an unapproved draft bill with a copy of the file, closes the document as drafted, and audits both; the drafter is a maker of the bill and cannot approve it. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- billobjectrequired
- bill.kindstring
- bill.vendor_idinteger
- bill.entity_idinteger | null
- bill.invoice_numberstring | null
- bill.invoice_datestring (date)
- bill.posting_datestring (date)
- bill.due_datestring (date)
- bill.term_idinteger | null
- bill.memostring | null
- bill.retainage_percentstring | null
- bill.tax_code_idinteger | null
- bill.commitment_typestring | null
- bill.commitment_idinteger | null
- bill.pay_when_paid_pay_app_idinteger | null
- bill.pay_when_paid_modestring | null
- bill.off_rent_datestring | null (date)
- bill.billed_throughstring | null (date)
- bill.duplicate_override_reasonstring | null
- bill.linesobject[]required
- bill.lines[].account_idintegerrequired
- bill.lines[].amountstringrequired
- bill.lines[].descriptionstring | null
- bill.lines[].retainage_percentstring | null
- bill.lines[].retainage_amountstring | nullExplicit retainage (at most the line amount); overrides retainage_percent.
- bill.lines[].project_idinteger | null
- bill.lines[].cost_code_idinteger | null
- bill.lines[].cost_type_idinteger | null
- bill.lines[].equipment_idinteger | null
- bill.lines[].commitment_line_item_idinteger | null
- bill.lines[].quantitystring | null
- bill.lines[].unit_pricestring | null
- bill.lines[].use_taxbooleanOmitted on an untaxed material line of a job whose tax profile accrues use tax (consumer states such as CA): defaults to true, and the bill tax code defaults to the job use tax code.
- bill.lines[].reportable_1099boolean
- bill.lines[].tax_categorystring | nullOne of: material, fixture, labor, equipment, null.
Response · 201 · object
- captured_documentobjectrequired
- captured_document.idintegerrequired
- captured_document.numberstringrequired
- captured_document.sourcestringrequiredOne of: upload, email, portal.
- captured_document.statusstringrequiredOne of: new, in_progress, drafted, rejected.
- captured_document.kindstringOne of: invoice, pay_app.
- captured_document.sender_emailstring | null
- captured_document.sender_namestring | null
- captured_document.subjectstring | null
- captured_document.received_atstring (date-time)required
- captured_document.fileobjectrequired
- captured_document.vendorobject | null
- captured_document.suggested_vendorobject | null
- captured_document.invoice_numberstring | null
- captured_document.invoice_datestring | null (date)
- captured_document.amountstring | null
- captured_document.notesstring | null
- captured_document.duplicatesobject[]required
- captured_document.assigned_toobject | null
- captured_document.portal_grant_idinteger | null
- captured_document.billobject | null
- captured_document.reject_reasonstring | null
- captured_document.drafted_atstring | null (date-time)
- captured_document.rejected_atstring | null (date-time)
- captured_document.created_atstring (date-time)
- captured_document.updated_atstring (date-time)
- billobjectrequired
- bill.idinteger
- bill.numberstring
- bill.statusstring
- bill.totalstring
- bill.linksobject
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1/draft_bill" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"bill": {
"lines": [
{
"account_id": 1,
"amount": "0.00"
}
]
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/fileDownload a captured file
Always sent as an attachment (application/octet-stream), never rendered inline. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1/file" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/rejectReject a captured document
Needs ap_enter and a reason (3-500 characters). Final; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rejectobjectrequired
- reject.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- sourcestringrequiredOne of: upload, email, portal.
- statusstringrequiredOne of: new, in_progress, drafted, rejected.
- kindstringOne of: invoice, pay_app.
- sender_emailstring | null
- sender_namestring | null
- subjectstring | null
- received_atstring (date-time)required
- fileobjectrequired
- file.namestringrequired
- file.content_typestringrequired
- file.size_bytesintegerrequired
- file.sha256stringrequired
- file.scan_statusstringrequiredOne of: clean, internal_upload, unscanned_local, infected.
- file.download_urlstring | null
- vendorobject | null
- vendor.idinteger
- vendor.namestring | null
- suggested_vendorobject | null
- suggested_vendor.idinteger
- suggested_vendor.namestring | null
- invoice_numberstring | null
- invoice_datestring | null (date)
- amountstring | null
- notesstring | null
- duplicatesobject[]required
- duplicates[].kindstringrequiredOne of: file_hash, vendor_invoice.
- duplicates[].captured_document_idinteger
- duplicates[].bill_idinteger
- duplicates[].numberstringrequired
- assigned_toobject | null
- assigned_to.idinteger
- assigned_to.namestring | null
- portal_grant_idinteger | null
- billobject | null
- bill.idinteger
- bill.numberstring | null
- bill.statusstring | null
- reject_reasonstring | null
- drafted_atstring | null (date-time)
- rejected_atstring | null (date-time)
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reject": {
"reason": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/capture/documents/{id}/suggestionsCoding suggestions for a captured document
Fixed rules only (no model): the vendor (keyed, the portal grant's vendor, or the sender rule), the coding of its last 50 posted bills in the caller's entities ranked by bills that used it then recency, its default expense account, and its open purchase order and subcontract lines (amount less posted billing). vendor_id overrides the vendor. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- vendor_idintegerquery
Response · 200 · object
- vendor_idinteger | null
- vendor_rulestring | nullOne of: keyed, portal_grant, sender, null.
- codingobject[]required
- coding[].account_idintegerrequired
- coding[].cost_code_idinteger | null
- coding[].cost_type_idinteger | null
- coding[].project_idinteger | null
- coding[].usesintegerrequired
- coding[].last_usedstring
- coding[].rulestringrequiredOne of: vendor_history, vendor_default_account.
- open_commitment_linesobject[]required
- open_commitment_lines[].commitment_typestring
- open_commitment_lines[].commitment_idinteger
- open_commitment_lines[].commitment_numberstring
- open_commitment_lines[].project_idinteger
- open_commitment_lines[].commitment_line_item_idinteger
- open_commitment_lines[].cost_code_idinteger
- open_commitment_lines[].descriptionstring | null
- open_commitment_lines[].amountstring
- open_commitment_lines[].billedstring
- open_commitment_lines[].remainingstring
- open_commitment_lines[].unit_coststring | null
- profileobject | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/capture/documents/1/suggestions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/checks/{id}/reprintReprint a check under a new number
Needs release_payments. Voids the AP check's register row (positive pay sends the void when the issue was sent) and registers the same check under the bank account's next check number; the payment and its journal entry are unchanged. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reprintobjectrequired
- reprint.reasonstringrequired
Response · 201 · object
- idintegerrequired
- check_numberstringrequired
- ap_payment_idintegerrequired
- amountstringrequired
- statusstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/checks/1/reprint" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reprint": {
"reason": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsList compliance requirements
Requirements that apply to every vendor, one vendor or one commitment. vendor_id narrows to that vendor's and the company-wide ones. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- vendor_idintegerquery
Response · 200 · object[]
- idintegerrequired
- kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- vendor_idinteger | nullrequired
- commitment_typestring | nullrequiredOne of: WorkOrderContract, PurchaseOrderContract, null.
- commitment_idinteger | nullrequired
- notesstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/compliance_requirements" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirementsRequire a compliance document
Needs ap_approve. A vendor (or every vendor when vendor_id is null, or the vendor on a commitment) must keep a current, active record of this kind; otherwise its bills carry the compliance_missing payment hold. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- compliance_requirementobjectrequired
- compliance_requirement.kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- compliance_requirement.vendor_idinteger | null
- compliance_requirement.commitment_typestring | nullOne of: WorkOrderContract, PurchaseOrderContract, null.
- compliance_requirement.commitment_idinteger | null
- compliance_requirement.notesstring | null
Response · 201 · object
- idintegerrequired
- kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- vendor_idinteger | nullrequired
- commitment_typestring | nullrequiredOne of: WorkOrderContract, PurchaseOrderContract, null.
- commitment_idinteger | nullrequired
- notesstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/compliance_requirements" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"compliance_requirement": {
"kind": "coi"
}
}'Accounting / Accounts Payable
DELETE/rest/v1.0/companies/{company_id}/accounting/ap/compliance_requirements/{id}Drop a compliance requirement
Needs ap_approve. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/compliance_requirements/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/form_10991099 review
Payments to 1099 vendors by payment date: AP payments plus posted banking checks and withdrawals to 1099 vendors (expense-coded lines with reportable_1099; card charges are 1099-K and excluded), line-level reportable overrides, the 2026 $2,000 NEC threshold, backup withholding in box 4. Forms are grouped per payer entity and vendor. Requires the accounting:read scope. Corporations and exempt payees (W-9 tax_classification) get no NEC/MISC; owner-direct payments are excluded. explain names each source document.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- yearintegerquery
- entity_idintegerqueryOnly this payer entity. Each entity is its own payer: forms are per (entity, vendor) with the threshold per payer.
Response · 200 · object
- yearintegerrequired
- formsobject[]required
- forms[].entity_idintegerrequired
- forms[].entity_codestring | nullrequired
- forms[].vendor_idintegerrequired
- forms[].vendor_namestring | nullrequired
- forms[].formstringrequiredOne of: NEC, MISC.
- forms[].boxesobjectrequired
- forms[].requiredbooleanrequired
- forms[].reasonsstring[]required
- forms[].filing_statusstringAgainst the latest IRIS or Pub 1220 export: changed means the live amounts differ from what was filed. One of: not_filed, filed, changed.
- forms[].filedobject | null
- explainobjectrequired
- explain.stepsobject[]required
- summary_1096object[]requiredForm 1096-style totals per payer entity and form: required forms and the total reported.
- summary_1096[].entity_idintegerrequired
- summary_1096[].entity_codestring | nullrequired
- summary_1096[].formstringrequiredOne of: NEC, MISC.
- summary_1096[].formsintegerrequired
- summary_1096[].totalstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_1099" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/copy_b1099 recipient Copy B
PDF statement for one vendor from one payer entity: the payer's full EIN and the recipient's truncated TIN, marked CORRECTED when the live amounts differ from what was filed. manage_vendor_banking; audited. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- yearintegerqueryrequired
- entity_idintegerqueryrequired
- vendor_idintegerqueryrequired
Response · 200 · string (binary)
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access or missing manage_vendor_banking404No required 1099 for this vendor and payer422year, entity_id and vendor_id are required, or the payer entity lacks its tax identity
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_1099/copy_b" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/irisExport 1099s as IRIS Taxpayer Portal CSV files
Builds the IRIS Taxpayer Portal CSV upload (IRS Pub 5717 Rev. 9-2026) for one form type from the year's 1099 data (W-9 tax classification applied; owner-direct payments excluded). Pass the header row of the CSV template downloaded from the portal for that tax year and form; it is written back byte for byte and each column is filled by name. Returns are split into files of at most 250 (Pub 5717 §3.5.1). A missing payee TIN (tin_missing), an unknown required template column, or corrected: true (portal corrections go through Make a Correction, iris_correction_portal_only) is refused with 422. Payee TINs are decrypted, so it needs manage_vendor_banking; every export is audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- irisobjectrequired
- iris.yearintegerrequired
- iris.formstringrequiredOne of: NEC, MISC.
- iris.templatestringrequiredThe CSV template downloaded from the IRIS Taxpayer Portal for this tax year and form (only its first line, the header row, is used)
- iris.correctedbooleanRefused: the portal CSV has no corrected-return column
- iris.issuerobjectOverrides the entity tax identity (EIN, legal name, address, phone) for a one-entity export. Omitted, the issuer comes from the entity.
- iris.issuer.tinstringrequired
- iris.issuer.tin_typestringOne of: EIN, SSN.
- iris.issuer.namestringrequired
- iris.issuer.name2string
- iris.issuer.addressstringrequired
- iris.issuer.address2string
- iris.issuer.citystringrequired
- iris.issuer.statestringrequired
- iris.issuer.zipstringrequired
- iris.issuer.phonestring
- iris.entity_idinteger | nullThe payer entity; required when forms span several entities.
Response · 200 · object
- yearintegerrequired
- formstringrequiredOne of: NEC, MISC.
- filesobject[]required
- files[].filenamestringrequired
- files[].recordsintegerrequiredReturns in this file (header row excluded), at most 250
- files[].csvstringrequiredCSV text: the template header row, then one row per return, CRLF line endings
- warningsstring[]required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_1099/iris" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"iris": {
"year": 1,
"form": "NEC",
"template": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/form_1099/pub1220Export 1099s as an IRS Pub 1220 file
Builds the FIRE file for one form type from the year's 1099 data (W-9 tax classification applied; owner-direct payments excluded). Payee TINs are decrypted, so it needs manage_vendor_banking; every export is audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- pub1220objectrequired
- pub1220.yearintegerrequired
- pub1220.formstringrequiredOne of: NEC, MISC.
- pub1220.testboolean
- pub1220.transmitterobjectrequired
- pub1220.transmitter.tinstringrequired
- pub1220.transmitter.tccstringrequired
- pub1220.transmitter.namestringrequired
- pub1220.transmitter.company_namestringrequired
- pub1220.transmitter.addressstringrequired
- pub1220.transmitter.citystringrequired
- pub1220.transmitter.statestringrequired
- pub1220.transmitter.zipstringrequired
- pub1220.transmitter.contact_namestringrequired
- pub1220.transmitter.contact_phonestringrequired
- pub1220.transmitter.contact_emailstring (email)required
- pub1220.issuerobjectOverrides the entity tax identity (EIN, legal name, address, phone) for a one-entity export. Omitted, the issuer comes from the entity.
- pub1220.issuer.tinstringrequired
- pub1220.issuer.namestringrequired
- pub1220.issuer.addressstringrequired
- pub1220.issuer.citystringrequired
- pub1220.issuer.statestringrequired
- pub1220.issuer.zipstringrequired
- pub1220.issuer.phonestringrequired
- pub1220.entity_idinteger | nullOnly this payer entity; omitted, one issuer (A) record per entity with forms.
- pub1220.correctedbooleanOnly the forms whose amounts changed since they were filed, flagged G (one-step correction); refused when nothing changed.
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed, no vendor needs this form, or the file failed Pub 1220 checks (FIRE is closed for payment years 2026 and later)
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_1099/pub1220" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"pub1220": {
"year": 1,
"form": "NEC",
"transmitter": {
"tin": "string",
"tcc": "string",
"name": "string",
"company_name": "string",
"address": "string",
"city": "string",
"state": "string",
"zip": "string",
"contact_name": "string",
"contact_phone": "string",
"contact_email": "string"
}
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/form_945Form 945 data
Form 945 for one entity (each EIN files its own; entity_id is required). Line 2 is the backup withholding on posted AP payments dated in the year (the liability date is the payment date); line 4 is the debits to the backup withholding account outside reversals (deposits). The deposit schedule comes from line 3 of the second preceding year (computed from the same data, or pass lookback_liability): monthly if 50,000.00 or less, otherwise semiweekly, with the 100,000.00 next-day rule (26 CFR 31.6302-4). Under 2,500.00 for the year no deposits are listed (pay with the return). ledger_withheld is the account's withholding credits less reversals; a difference from line 2 is reported in warnings as withholding_account_mismatch. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- yearintegerquery
- entity_idintegerqueryrequired
- lookback_liabilitystringquery
Response · 200 · object
- yearintegerrequired
- entity_idintegerrequired
- linesobjectrequiredForm 945 line 1 (nonpayroll income tax withholding; 0.00 from AP), line 2 backup withholding, 3 = 1 + 2, 4 deposits, 5 balance due, 6 overpayment.
- lines.1string
- lines.2string
- lines.3string
- lines.4string
- lines.5string
- lines.6string
- line_7object | nullrequiredMonthly summary, only for a monthly depositor for the whole year with line 3 of 2,500.00 or more.
- line_7.monthsstring[]
- line_7.totalstring
- form_945a_requiredbooleanrequired
- schedulestringrequiredOne of: monthly, semiweekly.
- lookback_liabilitystringrequired
- may_pay_with_returnbooleanrequired
- liability_by_dateobject[]required
- liability_by_date[].datestring (date)
- liability_by_date[].amountstring
- depositsobject[]required
- deposits[].due_datestring (date)
- deposits[].amountstring
- deposits[].rulestringOne of: monthly, semiweekly, next_day.
- deposits[].liability_datesstring (date)[]
- ledger_withheldstringrequired
- warningsstring[]required
- explainobjectrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_945" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/form_945/eftpsEFTPS 945 deposits
EFTPS ACH-credit deposit records for the computed Form 945 deposits: tax type 09455, tax period end December 31, TXP addenda with the total. 422 entity_ein_missing when the entity has no EIN; 422 no_945_deposits when nothing is due (under 2,500.00: pay with the return). The entity EIN is decrypted, so it needs manage_vendor_banking; every export is audited (eftps_945_exported). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- form_945objectrequired
- form_945.yearintegerrequired
- form_945.entity_idintegerrequired
- form_945.lookback_liabilitystring | null
Response · 200 · object
- yearintegerrequired
- entity_idintegerrequired
- depositsobject[]required
- deposits[].tax_formstring
- deposits[].tax_type_codestring
- deposits[].tax_period_endstring (date)
- deposits[].settlement_datestring (date)
- deposits[].amountstring
- deposits[].txpstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/form_945/eftps" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"form_945": {
"year": 1,
"entity_id": 1
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptionsList three-way match exceptions
The exception workbench: bill lines (and whole bills) failing the PO, receipt and bill match, oldest first. status and type take comma-separated values (status defaults to open). min_age and max_age are whole days since detection, inclusive. Limited to the caller's entities; a project-scoped grant gets 403. Paginated (Total, Per-Page, Link headers). Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- statusstringqueryopen, resolved, overridden (comma-separated)
- typestringqueryqty_over, price_over, no_receipt, no_po, over_commitment (comma-separated)
- vendor_idintegerquery
- project_idintegerquery
- entity_idintegerquery
- bill_idintegerquery
- min_ageintegerqueryDays since detection, at least
- max_ageintegerqueryDays since detection, at most
Response · 200 · object[]
- idintegerrequired
- bill_idintegerrequired
- bill_numberstring | nullrequired
- invoice_numberstring | nullrequired
- bill_statusstring | nullrequired
- bill_revisionintegerrequired
- line_nointeger | nullrequiredBill line; null for the whole bill (over_commitment).
- typestringrequiredOne of: qty_over, price_over, no_receipt, no_po, over_commitment.
- statusstringrequiredOne of: open, resolved, overridden.
- entity_idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- project_idinteger | nullrequired
- project_namestring | nullrequired
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- commitment_line_item_idinteger | nullrequired
- cost_type_idinteger | nullrequired
- amountstringrequiredMoney at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
- messagestringrequired
- detailsobjectrequiredFigures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
- detected_atstring (date-time)required
- last_evaluated_atstring (date-time)required
- age_daysinteger | nullrequired
- age_bucketstring | nullrequiredOne of: 0_7, 8_14, 15_30, 31_plus, null.
- resolutionstring | nullrequiredreceipt, re_evaluated, bill_corrected, bill_returned or override.
- resolved_atstring | null (date-time)required
- resolved_by_idinteger | nullrequired
- override_reasonstring | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/match_exceptions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}Show a match exception
The exception with its PO line, the receipts on that line, other bills on it and the bill line, side by side. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- bill_idintegerrequired
- bill_numberstring | nullrequired
- invoice_numberstring | nullrequired
- bill_statusstring | nullrequired
- bill_revisionintegerrequired
- line_nointeger | nullrequiredBill line; null for the whole bill (over_commitment).
- typestringrequiredOne of: qty_over, price_over, no_receipt, no_po, over_commitment.
- statusstringrequiredOne of: open, resolved, overridden.
- entity_idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- project_idinteger | nullrequired
- project_namestring | nullrequired
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- commitment_line_item_idinteger | nullrequired
- cost_type_idinteger | nullrequired
- amountstringrequiredMoney at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
- messagestringrequired
- detailsobjectrequiredFigures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
- detected_atstring (date-time)required
- last_evaluated_atstring (date-time)required
- age_daysinteger | nullrequired
- age_bucketstring | nullrequiredOne of: 0_7, 8_14, 15_30, 31_plus, null.
- resolutionstring | nullrequiredreceipt, re_evaluated, bill_corrected, bill_returned or override.
- resolved_atstring | null (date-time)required
- resolved_by_idinteger | nullrequired
- override_reasonstring | nullrequired
- can_overridebooleanrequiredThe exception is open and the caller is not a maker of the bill (ap_approve is still checked on override).
- poobject | nullrequired
- po.commitment_typestring | nullrequired
- po.idintegerrequired
- po.numberstringrequired
- po.titlestring | nullrequired
- po.lineobject | nullrequired
- receiptsobject[]required
- receipts[].receipt_idintegerrequired
- receipts[].numberstringrequired
- receipts[].receipt_datestring (date)required
- receipts[].quantitystringrequired
- receipts[].amountstringrequiredMoney, 2 dp
- receipts[].voidedbooleanrequired
- other_billsobject[]requiredOther posted or pending bill lines on the same PO line.
- other_bills[].bill_idintegerrequired
- other_bills[].numberstringrequired
- other_bills[].statusstringrequired
- other_bills[].kindstringrequired
- other_bills[].line_nointegerrequired
- other_bills[].quantitystring | nullrequired
- other_bills[].amountstringrequiredMoney, 2 dp
- billobjectrequired
- bill.idintegerrequired
- bill.numberstringrequired
- bill.invoice_numberstring | nullrequired
- bill.statusstringrequired
- bill.revisionintegerrequired
- bill.totalstringrequiredMoney, 2 dp
- bill.lineobject | nullrequired
- other_exceptionsobject[]required
- other_exceptions[].idintegerrequired
- other_exceptions[].line_nointeger | nullrequired
- other_exceptions[].typestringrequiredOne of: qty_over, price_over, no_receipt, no_po, over_commitment.
- other_exceptions[].statusstringrequiredOne of: open, resolved, overridden.
- other_exceptions[].amountstringrequiredMoney, 2 dp
- other_exceptions[].messagestringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/match_exceptions/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/match_exceptions/{id}/overrideOverride a match exception
Accepts an open exception with a reason (3-500 characters); all_on_bill overrides every open exception on the same bill. Needs ap_approve in the bill's entity; a maker of the bill (preparer, editor or contributor) gets 403 sod_maker_checker. Each overridden exception and the bill get an audit row with the reason. When no open exception is left the bill's match hold is released. 409 not_open when the exception is already resolved or overridden. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- overrideobjectrequired
- override.reasonstringrequired
- override.all_on_billboolean
Response · 200 · object
- idintegerrequired
- bill_idintegerrequired
- bill_numberstring | nullrequired
- invoice_numberstring | nullrequired
- bill_statusstring | nullrequired
- bill_revisionintegerrequired
- line_nointeger | nullrequiredBill line; null for the whole bill (over_commitment).
- typestringrequiredOne of: qty_over, price_over, no_receipt, no_po, over_commitment.
- statusstringrequiredOne of: open, resolved, overridden.
- entity_idintegerrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- project_idinteger | nullrequired
- project_namestring | nullrequired
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- commitment_line_item_idinteger | nullrequired
- cost_type_idinteger | nullrequired
- amountstringrequiredMoney at stake: |price variance|, the excess quantity at the bill price, the unreceived or unordered line amount, or the over-commitment.
- messagestringrequired
- detailsobjectrequiredFigures behind the exception as of the last evaluation (quantities, prices, tolerance applied).
- detected_atstring (date-time)required
- last_evaluated_atstring (date-time)required
- age_daysinteger | nullrequired
- age_bucketstring | nullrequiredOne of: 0_7, 8_14, 15_30, 31_plus, null.
- resolutionstring | nullrequiredreceipt, re_evaluated, bill_corrected, bill_returned or override.
- resolved_atstring | null (date-time)required
- resolved_by_idinteger | nullrequired
- override_reasonstring | nullrequired
- can_overridebooleanrequiredThe exception is open and the caller is not a maker of the bill (ap_approve is still checked on override).
- poobject | nullrequired
- po.commitment_typestring | nullrequired
- po.idintegerrequired
- po.numberstringrequired
- po.titlestring | nullrequired
- po.lineobject | nullrequired
- receiptsobject[]required
- receipts[].receipt_idintegerrequired
- receipts[].numberstringrequired
- receipts[].receipt_datestring (date)required
- receipts[].quantitystringrequired
- receipts[].amountstringrequiredMoney, 2 dp
- receipts[].voidedbooleanrequired
- other_billsobject[]requiredOther posted or pending bill lines on the same PO line.
- other_bills[].bill_idintegerrequired
- other_bills[].numberstringrequired
- other_bills[].statusstringrequired
- other_bills[].kindstringrequired
- other_bills[].line_nointegerrequired
- other_bills[].quantitystring | nullrequired
- other_bills[].amountstringrequiredMoney, 2 dp
- billobjectrequired
- bill.idintegerrequired
- bill.numberstringrequired
- bill.invoice_numberstring | nullrequired
- bill.statusstringrequired
- bill.revisionintegerrequired
- bill.totalstringrequiredMoney, 2 dp
- bill.lineobject | nullrequired
- other_exceptionsobject[]required
- other_exceptions[].idintegerrequired
- other_exceptions[].line_nointeger | nullrequired
- other_exceptions[].typestringrequiredOne of: qty_over, price_over, no_receipt, no_po, over_commitment.
- other_exceptions[].statusstringrequiredOne of: open, resolved, overridden.
- other_exceptions[].amountstringrequiredMoney, 2 dp
- other_exceptions[].messagestringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/match_exceptions/1/override" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"override": {
"reason": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_runsList payment runs
Paginated. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- ach_generated_atstring | null (date-time)requiredWhen the NACHA file was last generated (null: never).
- ach_file_id_modifierstring | nullrequiredFile id modifier of the last NACHA file: A, then B, C… on each audited re-send.
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- ach_resend_requested_by_idinteger | nullPending requester; null when there is no pending resend.
- ach_resend_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payment_runsCreate a draft payment run
Needs ap_enter. Explicit payments (method, joint payees, owner-direct) or every unheld bill due by due_by. Held bills are listed and never paid; backup withholding (24%) applies to 1099 vendors with no TIN. Requires the accounting:write scope. The owner_direct method is refused (422 owner_direct_unavailable) until it posts through AR.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- payment_runobjectrequired
- payment_run.pay_datestring (date)required
- payment_run.cash_account_idinteger | null
- payment_run.due_bystring (date)
- payment_run.vendor_idsinteger[]
- payment_run.memostring | null
- payment_run.paymentsobject[]
- payment_run.payments[].vendor_idintegerrequired
- payment_run.payments[].methodstring
- payment_run.payments[].customer_idinteger | null
- payment_run.payments[].joint_payeesobject[]
- payment_run.payments[].joint_payees[].namestringrequired
- payment_run.payments[].joint_payees[].amountstringrequired
- payment_run.payments[].billsobject[]required
- payment_run.payments[].bills[].bill_idintegerrequired
- payment_run.payments[].bills[].amountstring
Response · 201 · object
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- heldobject[]required
- held[].bill_idintegerrequired
- held[].numberstringrequired
- held[].vendor_idintegerrequired
- held[].holdsobject[]required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"payment_run": {
"pay_date": "2026-11-01"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Show a payment run
Payments with their bill applications. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- ach_generated_atstring | null (date-time)requiredWhen the NACHA file was last generated (null: never).
- ach_file_id_modifierstring | nullrequiredFile id modifier of the last NACHA file: A, then B, C… on each audited re-send.
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- ach_resend_requested_by_idinteger | nullPending requester; null when there is no pending resend.
- ach_resend_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
DELETE/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}Delete a draft run
Needs ap_enter. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 204
No response body.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/checksCheck print data
Needs release_payments. Generated on demand, never stored; a joint check prints both payees. Check numbers come from the shared check register; voided checks are left out. Contains the MICR line (routing and account number), so it requires the accounting:write scope. A released check missing from the register returns 409 check_not_registered. Audited.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- formatstringquerypdf returns printable checks (one Letter page per check: check on top, two stubs, the MICR line in font-mapped form for a MICR toner printer or overlay) One of: json, pdf.
Response · 200 · object[]
- payment_idintegerrequired
- check_numberstringrequired
- datestring (date)required
- amountstringrequired
- amount_wordsstringrequired
- payee_linestringrequired
- memostring | nullrequired
- micrstringrequired
- stubobject[]required
- stub[].referencestringrequired
- stub[].grossstringrequired
- stub[].discountstringrequired
- stub[].netstringrequired
- stub[].datestring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409A released check is not in the check register (check_not_registered)422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/checks" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaACH (NACHA) file
Needs release_payments. Vendor credits for the run's ACH payments, batched by SEC code from the vendor's bank_account_ownership (CCD+ to business accounts, PPD to consumer accounts), originating from the pay-from bank account's routing. Generated once (file id modifier A); the generation time, modifier and each payment's trace number are recorded and audited. A second generation is refused with 409 ach_already_generated: use POST to re-send. ACH payments pay the vendor bank details snapshotted at release; if the vendor profile changed since, 409 bank_changed_since_release (void the payment and pay it in a new run). An account blocked by an ACH return is refused (409 ach_account_blocked); an account whose prenote has not settled three banking days before the pay date is refused (409 ach_prenote_pending); with ach_prenote_required on, an account never prenoted is refused (409 ach_prenote_required). Requires the accounting:write scope. A file generated after the pay date carries the next Fed banking day as its effective entry date (X-Ach-Effective-Date, X-Ach-Warning). The pay-from bank is revalidated under lock at generation and resend: inactive or credit-card accounts return 422 not_a_bank_account; a bank assigned to a different payment entity returns 422 bank_entity_mismatch. Refusal leaves generation, trace and resend state unchanged.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Already generated (ach_already_generated)422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/nacha" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/nachaRe-send the ACH (NACHA) file
The resend object requires reason, action (request or confirm), and previous_file_id_modifier. Read the current modifier and pending requester from the payment run. Request returns 202; an independent releaser confirms to receive the file. Missing fields return 422; stale or conflicting actions return 409. Payload example and two-person approval rules →
Explicit two-person re-send: resend.action=request records the request (202, no file); resend.action=confirm by an independent releaser returns the new file. Both require resend.previous_file_id_modifier equal to the current payment-run ach_file_id_modifier. Missing fields are 422; a stale modifier, request when one is already pending, or confirmation without a pending request is 409. Refresh GET payment_runs/{id} to inspect ach_resend_requested_by_id and ach_resend_reason before confirming. Reason-only legacy requests are no longer accepted. Needs release_payments and two people. The first call records the re-send request and its reason (202, no file). A second call by a different release_payments user, who is neither the requester nor the run preparer (403 sod_resend otherwise), regenerates the run's NACHA file with the next file id modifier (B, C…) so the bank sees a distinct file, records the new trace numbers and writes an ach_resent audit row with both reasons. At most 2 re-sends per run (409 ach_resend_limit). Refused (422) before the first generation. ACH payments pay the vendor bank details snapshotted at release; if the vendor profile changed since, 409 bank_changed_since_release (void the payment and pay it in a new run). Requires the accounting:write scope. A file generated after the pay date carries the next Fed banking day as its effective entry date (X-Ach-Effective-Date, X-Ach-Warning). The pay-from bank is revalidated under lock at generation and resend: inactive or credit-card accounts return 422 not_a_bank_account; a bank assigned to a different payment entity returns 422 bank_entity_mismatch. Refusal leaves generation, trace and resend state unchanged.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- resendobjectrequired
- resend.reasonstringrequired
- resend.actionstringrequiredExplicit workflow intent; requesting cannot confirm an existing request. One of: request, confirm.
- resend.previous_file_id_modifierstringrequiredCurrent ach_file_id_modifier from the payment run. Both requester and confirmer must acknowledge the file being replaced.
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Another generation ran at the same time422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/nacha" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"resend": {
"reason": "string",
"action": "request",
"previous_file_id_modifier": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/positive_payPositive pay file (CSV)
Needs release_payments. The run's checks from the shared check register (the same register banking positive pay reads): issued checks, plus a void record for a check voided after its issue record was sent; a void never sent is left out. Account number from the pay-from bank account. Marks the checks sent; audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · string
No documented fields.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/positive_pay" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/rejectReject a payment run release
Needs release_payments and every payment's entity. Spends the release votes recorded so far on a draft run (the run stays a draft for its preparer to fix or delete). The reason is required and audited (action rejected). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- rejectobjectrequired
- reject.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- ach_generated_atstring | null (date-time)requiredWhen the NACHA file was last generated (null: never).
- ach_file_id_modifierstring | nullrequiredFile id modifier of the last NACHA file: A, then B, C… on each audited re-send.
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- ach_resend_requested_by_idinteger | nullPending requester; null when there is no pending resend.
- ach_resend_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, or wrong company404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"reject": {
"reason": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payment_runs/{id}/releaseRelease (approve) and post a payment run
Needs release_payments. The releaser must not be the run's preparer nor have entered any bill in it (403 sod_release). Release is the payment_batch approval: with no matching approval rule one release posts the run; when a rule routes the batch (for example 2 of 3 named releasers), each call fills one slot of the current step (403 approver_role_required when the caller is not on it, 409 already_approved on a second vote) and the run stays draft until the route completes. The call that completes the route re-checks holds and open amounts, numbers checks and posts each payment (Dr AP / Cr cash, discounts, backup withholding). In small-team SoD mode (settings sod_mode) a maker may approve their own document by sending approve.reason; the event is audited as self_approved and listed by approvals/self_approved. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- approveobject
- approve.reasonstringRequired only to approve your own document in small-team SoD mode (422 self_approval_reason_required); the approval is flagged self_approved.
Response · 200 · object
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- ach_generated_atstring | null (date-time)requiredWhen the NACHA file was last generated (null: never).
- ach_file_id_modifierstring | nullrequiredFile id modifier of the last NACHA file: A, then B, C… on each audited re-send.
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- ach_resend_requested_by_idinteger | nullPending requester; null when there is no pending resend.
- ach_resend_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_runs/1/release" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"approve": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payment_selectionPayment selection
Open posted bills due by due_by with their holds, the amount payable now (pay-when-paid aware) and any early-pay discount on pay_date. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pay_datestring (date)query
- due_bystring (date)query
Response · 200 · object[]
- bill_idintegerrequired
- numberstringrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- invoice_numberstring | nullrequired
- due_datestring (date)required
- open_amountstringrequiredMoney, 2 dp
- payable_amountstringrequiredMoney, 2 dp
- discountstringrequiredMoney, 2 dp
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- payablebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payment_selection" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/paymentsList payments
Filters: vendor_id, filters[status]. Paginated. Delta sync: updated_since and/or cursor return changes in ascending (updated_at, id) order with Next-Cursor. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- vendor_idintegerquery
- filters[status]stringquery
- updated_sincestring (date-time)queryDelta sync: only rows created or changed at or after this time (ISO 8601 with offset). Switches the list to ascending (updated_at, id) order; page is ignored and Next-Cursor continues it. Re-read with a small overlap (a few seconds) and dedupe by id.
- cursorstringqueryOpaque keyset cursor from a previous response's Next-Cursor header; each page costs the same however deep it is.
Response · 200 · object[]
- idintegerrequired
- run_idinteger | nullrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- check_numberstring | nullrequired
- payment_datestring (date)required
- cash_account_idintegerrequired
- amountstringrequiredMoney, 2 dp
- discount_amountstringrequiredMoney, 2 dp
- withholding_amountstringrequiredMoney, 2 dp
- joint_payeesobject[]required
- joint_payees[].namestringrequired
- joint_payees[].amountstringrequired
- customer_idinteger | nullrequired
- statusstringrequiredOne of: draft, posted, void.
- memostring | nullrequired
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- applications[].bill_numberstringrequired
- applications[].invoice_numberstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/paymentsCreate one manual payment
Needs ap_enter. One vendor payment against explicit bills, created as a single-payment draft run (the response is the run). A different user releases it with POST .../payment_runs/{id}/release, which numbers checks and posts. Holds, discounts and backup withholding apply as for runs. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- paymentobjectrequired
- payment.pay_datestring (date)required
- payment.cash_account_idinteger | null
- payment.memostring | null
- payment.vendor_idintegerrequired
- payment.methodstring
- payment.customer_idinteger | null
- payment.joint_payeesobject[]
- payment.joint_payees[].namestringrequired
- payment.joint_payees[].amountstringrequired
- payment.billsobject[]required
- payment.bills[].bill_idintegerrequired
- payment.bills[].amountstring
Response · 201 · object
- idintegerrequired
- numberstringrequired
- statusstringrequiredOne of: draft, posted.
- pay_datestring (date)required
- cash_account_idintegerrequired
- memostring | nullrequired
- prepared_by_idintegerrequired
- released_by_idinteger | nullrequired
- released_atstring | null (date-time)required
- ach_generated_atstring | null (date-time)requiredWhen the NACHA file was last generated (null: never).
- ach_file_id_modifierstring | nullrequiredFile id modifier of the last NACHA file: A, then B, C… on each audited re-send.
- totalstringrequiredMoney, 2 dp
- payment_countintegerrequired
- paymentsobject[]required
- payments[].idintegerrequired
- payments[].run_idinteger | nullrequired
- payments[].vendor_idintegerrequired
- payments[].vendor_namestring | nullrequired
- payments[].entity_idintegerrequired
- payments[].methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- payments[].check_numberstring | nullrequired
- payments[].payment_datestring (date)required
- payments[].cash_account_idintegerrequired
- payments[].amountstringrequiredMoney, 2 dp
- payments[].discount_amountstringrequiredMoney, 2 dp
- payments[].withholding_amountstringrequiredMoney, 2 dp
- payments[].joint_payeesobject[]required
- payments[].customer_idinteger | nullrequired
- payments[].statusstringrequiredOne of: draft, posted, void.
- payments[].memostring | nullrequired
- payments[].entry_idinteger | nullrequired
- payments[].voided_atstring | null (date-time)required
- payments[].void_entry_idinteger | nullrequired
- payments[].void_reasonstring | nullrequired
- payments[].ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- payments[].applicationsobject[]required
- payments[].created_atstring (date-time)required
- created_atstring (date-time)required
- ach_resend_requested_by_idinteger | nullPending requester; null when there is no pending resend.
- ach_resend_reasonstring | null
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"payment": {
"pay_date": "2026-11-01",
"vendor_id": 1,
"bills": [
{
"bill_id": 1
}
]
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}Show a payment
Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- run_idinteger | nullrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- check_numberstring | nullrequired
- payment_datestring (date)required
- cash_account_idintegerrequired
- amountstringrequiredMoney, 2 dp
- discount_amountstringrequiredMoney, 2 dp
- withholding_amountstringrequiredMoney, 2 dp
- joint_payeesobject[]required
- joint_payees[].namestringrequired
- joint_payees[].amountstringrequired
- customer_idinteger | nullrequired
- statusstringrequiredOne of: draft, posted, void.
- memostring | nullrequired
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- applications[].bill_numberstringrequired
- applications[].invoice_numberstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittanceGet a payment's remittance advice
The itemized advice (bills paid with invoice numbers, amounts applied, discounts, backup withholding and retainage still held; net equals the payment) and every send of it. Limited to the caller's entities. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- payment_idintegerrequired
- subjectstringrequired
- textstringrequired
- content_sha256string
- totalsobjectrequired
- totals.appliedstringrequired
- totals.discountstringrequired
- totals.withholdingstringrequired
- totals.netstringrequired
- totals.retainage_heldstringrequired
- sendsobject[]required
- sends[].idinteger
- sends[].recipientstring | null
- sends[].statusstringOne of: sent, failed, no_recipient.
- sends[].resendboolean
- sends[].email_message_idinteger | null
- sends[].content_sha256string
- sends[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments/1/remittance" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/remittance/sendEmail a payment's remittance advice
Needs ap_enter. Sends through the email transport (the outbox by default) to to, or to the vendor's remittance email and active portal users. Posted payments only. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- remittanceobjectrequired
- remittance.tostring (email)
Response · 200 · object
- payment_idintegerrequired
- subjectstringrequired
- textstringrequired
- content_sha256string
- totalsobjectrequired
- totals.appliedstringrequired
- totals.discountstringrequired
- totals.withholdingstringrequired
- totals.netstringrequired
- totals.retainage_heldstringrequired
- sendsobject[]required
- sends[].idinteger
- sends[].recipientstring | null
- sends[].statusstringOne of: sent, failed, no_recipient.
- sends[].resendboolean
- sends[].email_message_idinteger | null
- sends[].content_sha256string
- sends[].created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments/1/remittance/send" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"remittance": {}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/virtual_card/issueRetry a virtual card issue
Needs release_payments and step-up. Issues (again) the payment's card locked to the payment amount; the provider returns the same card for the same payment, so a retry never makes a second card. A card whose limit differs from the payment is canceled (issue_failed). 409 when already issued, settled or canceled. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- payment_idintegerrequired
- entity_idinteger
- vendorobject
- vendor.idinteger
- vendor.namestring | null
- providerstring
- statusstringrequiredOne of: pending_issue, issued, issue_failed, settled, settlement_mismatch, canceled.
- last4string | null
- exp_monthinteger | null
- exp_yearinteger | null
- amountstringrequired
- currencystringrequired
- issued_atstring | null (date-time)
- settlement_idstring | null
- settled_amountstring | null
- settled_onstring | null (date)
- bank_transaction_idinteger | null
- errorstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)503No usable card provider
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments/1/virtual_card/issue" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/payments/{id}/voidVoid a payment
Needs release_payments. Reversal dated in an open period; its bills reopen. A reconciled payment returns 409 reconciled. An ACH payment already sent in a NACHA file (trace number set) returns 422 ach_recall_unconfirmed unless confirm_ach_recalled is true; its bills then carry an ach_return_pending hold until an override records the bank return. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
- void.confirm_ach_recalledbooleanRequired true to void an ACH payment that was already transmitted (the bank recalled or returned it).
Response · 200 · object
- idintegerrequired
- run_idinteger | nullrequired
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- methodstringrequiredOne of: check, ach, wire, virtual_card, owner_direct.
- check_numberstring | nullrequired
- payment_datestring (date)required
- cash_account_idintegerrequired
- amountstringrequiredMoney, 2 dp
- discount_amountstringrequiredMoney, 2 dp
- withholding_amountstringrequiredMoney, 2 dp
- joint_payeesobject[]required
- joint_payees[].namestringrequired
- joint_payees[].amountstringrequired
- customer_idinteger | nullrequired
- statusstringrequiredOne of: draft, posted, void.
- memostring | nullrequired
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- ach_trace_numberstring | nullrequiredACH: trace number in the last generated NACHA file.
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- applications[].bill_numberstringrequired
- applications[].invoice_numberstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/payments/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/receiptsList PO receipts
Filter by commitment_id. Limited to the caller's entities. Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- commitment_idintegerquery
Response · 200 · object[]
- idintegerrequired
- numberstringrequired
- commitment_idintegerrequired
- project_idintegerrequired
- vendor_idintegerrequired
- entity_idinteger | nullrequired
- receipt_datestring (date)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- linesobject[]required
- lines[].idintegerrequired
- lines[].commitment_line_item_idintegerrequired
- lines[].quantitystringrequired
- lines[].amountstringrequiredMoney, 2 dp
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/receipts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/receiptsReceive against a purchase order
Quantities at PO unit cost, posted in the PO project's entity. With receipt accrual posts Dr cost / Cr received-not-invoiced. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- receiptobjectrequired
- receipt.commitment_idintegerrequired
- receipt.entity_idinteger | nullMust match the project's assigned entity when it has one; defaults to it, else to the default entity.
- receipt.receipt_datestring (date)required
- receipt.linesobject[]required
- receipt.lines[].commitment_line_item_idintegerrequired
- receipt.lines[].quantitystringrequiredGreater than zero; with earlier receipts that are not void, at most the PO line quantity (422 over_received).
- receipt.lines[].account_idinteger | nullCost account the accrual debits (postable, not a control account). Defaults to the first material job cost account.
Response · 201 · object
- idintegerrequired
- numberstringrequired
- commitment_idintegerrequired
- project_idintegerrequired
- vendor_idintegerrequired
- entity_idinteger | nullrequired
- receipt_datestring (date)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- linesobject[]required
- lines[].idintegerrequired
- lines[].commitment_line_item_idintegerrequired
- lines[].quantitystringrequired
- lines[].amountstringrequiredMoney, 2 dp
- created_atstring (date-time)required
Errors
400Malformed JSON body or Idempotency-Key header401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed (over_received, zero quantity, entity mismatch) or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/receipts" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"receipt": {
"commitment_id": 1,
"receipt_date": "2026-11-01",
"lines": [
{
"commitment_line_item_id": 1,
"quantity": "0.00"
}
]
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/receipts/{id}/voidVoid a PO receipt
Reverses its accrual on the given date (an open period); its quantities no longer count as received. Refused while posted bills have invoiced those quantities. Requires ap_approve and the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- commitment_idintegerrequired
- project_idintegerrequired
- vendor_idintegerrequired
- entity_idinteger | nullrequired
- receipt_datestring (date)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- linesobject[]required
- lines[].idintegerrequired
- lines[].commitment_line_item_idintegerrequired
- lines[].quantitystringrequired
- lines[].amountstringrequiredMoney, 2 dp
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (receipt_invoiced: posted bills invoiced the quantities it received)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/receipts/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/retainage_releases/{id}/voidVoid a retainage release
Needs ap_approve. The path id is the retainage release. Reverses its entry on the given date (open AP period, on or after the release date), sets voided_at and puts the amount back in retainage held, so the bill can be voided. 409 release_paid once the released amount has been paid, 409 bill_in_draft_run while the bill is in a draft payment run. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- voidobjectrequired
- void.datestring (date)required
- void.reasonstringrequired
Response · 200 · object
- idintegerrequired
- numberstringrequired
- kindstringrequiredOne of: bill, credit.
- statusstringrequiredOne of: draft, pending_approval, posted, void.
- vendor_idintegerrequired
- vendor_namestring | nullrequired
- entity_idintegerrequired
- invoice_numberstring | nullrequired
- invoice_datestring (date)required
- posting_datestring (date)required
- due_datestring (date)required
- term_idinteger | nullrequired
- discount_percentstring | nullrequiredRate/quantity, 6 dp
- discount_datestring | null (date)required
- memostring | nullrequired
- totalstringrequiredMoney, 2 dp
- retainage_amountstringrequiredMoney, 2 dp
- use_tax_amountstringrequiredMoney, 2 dp
- tax_code_idinteger | nullrequired
- open_amountstringrequiredMoney, 2 dp
- retainage_openstringrequiredMoney, 2 dp
- paid_amountstringrequiredMoney, 2 dp
- retainage_releasedstringrequiredMoney, 2 dp
- commitment_typestring | nullrequired
- commitment_idinteger | nullrequired
- requisition_idinteger | nullrequired
- direct_cost_idinteger | nullrequired
- pay_when_paid_pay_app_idinteger | nullrequired
- pay_when_paid_modestring | nullrequired
- off_rent_datestring | null (date)required
- billed_throughstring | null (date)required
- matchobject | nullrequired
- hold_overridesobject[]required
- revisionintegerrequired
- prepared_by_idintegerrequired
- last_edited_by_idintegerrequired
- contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- submitted_atstring | null (date-time)required
- approved_atstring | null (date-time)required
- entry_idinteger | nullrequired
- voided_atstring | null (date-time)required
- void_entry_idinteger | nullrequired
- void_reasonstring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- linesobject[]required
- lines[].idintegerrequired
- lines[].line_nointegerrequired
- lines[].account_idintegerrequired
- lines[].descriptionstring | nullrequired
- lines[].amountstringrequiredMoney, 2 dp
- lines[].retainage_percentstring | nullrequiredRate/quantity, 6 dp
- lines[].retainage_amountstringrequiredMoney, 2 dp
- lines[].project_idinteger | nullrequired
- lines[].cost_code_idinteger | nullrequired
- lines[].cost_type_idinteger | nullrequired
- lines[].equipment_idinteger | nullrequired
- lines[].commitment_line_item_idinteger | nullrequired
- lines[].quantitystring | nullrequiredRate/quantity, 6 dp
- lines[].unit_pricestring | nullrequiredRate/quantity, 6 dp
- lines[].use_taxbooleanrequired
- lines[].reportable_1099booleanrequired
- lines[].tax_categorystring | nullrequiredContractor tax category: CA fixtures are retail sales while materials are consumed; untaxed material on a consumer-model job defaults to use tax (AP). One of: material, fixture, labor, equipment, null.
- lines[].dimension_value_idsarray | nullrequiredUser-defined dimension values (AcctDimensionValue ids).
- holdsobject[]required
- holds[].codestringrequiredHold code; ach_returned: the bank returned an ACH payment on this bill (ACH notice import), overridable with release_payments.
- holds[].messagestringrequired
- holds[].overriddenbooleanrequired
- approvals_requiredintegerrequired
- route_previewstringrequired
- approvalsobject[]required
- approvals[].user_idintegerrequired
- approvals[].stepintegerrequired
- approvals[].approved_atstring (date-time)required
- applicationsobject[]required
- applications[].idintegerrequired
- applications[].bill_idintegerrequired
- applications[].payment_idinteger | nullrequired
- applications[].credit_idinteger | nullrequired
- applications[].datestring (date)required
- applications[].amountstringrequiredMoney, 2 dp
- applications[].discountstringrequiredMoney, 2 dp
- applications[].withholdingstringrequiredMoney, 2 dp
- applications[].voidedbooleanrequired
- retainage_releasesobject[]required
- retainage_releases[].idintegerrequired
- retainage_releases[].datestring (date)required
- retainage_releases[].amountstringrequiredMoney, 2 dp
- retainage_releases[].entry_idintegerrequired
- retainage_releases[].voided_atstring | null (date)Effective void date; as-of aging counts the release before it.
- retainage_releases[].void_entry_idinteger | null
- retainage_releases[].void_reasonstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company409Conflict (duplicate_suspected, match_exception, a payment hold, already approved)422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/retainage_releases/1/void" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"void": {
"date": "2026-11-01",
"reason": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/settingsAP settings
Matching tolerances, over-commitment action, discount posting, approval bands, hold settings and the default pay-from cash account. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- over_commitment_actionstringrequired
- match_tolerance_pctstringrequired
- match_tolerance_amountstringrequiredMoney, 2 dp
- receipt_accrualbooleanrequired
- discount_posting_modestringrequired
- bank_change_hold_daysintegerrequired
- lien_waiver_modestringrequired
- approval_bandsobject[]required
- approval_bands[].minstringrequired
- approval_bands[].approvalsintegerrequired
- approval_bands[].final_rolestring | null
- rni_account_idinteger | nullrequired
- backup_withholding_account_idinteger | nullrequired
- cash_account_idinteger | nullrequiredDefault pay-from: the GL account of an active, non-card bank account (banking). Routing, account number and check numbering come from that bank account.
- ach_company_idstring | nullrequired
- ach_company_namestring | nullrequired
- ach_destination_routingstring | nullrequired
- ach_destination_namestring | nullrequired
- prompt_pay_daysinteger | nullrequired
- updated_atstring (date-time)required
- backup_withholding_policystringrequiredhold: payments subject to backup withholding (no TIN, or past a B notice's withholding date) are also put on a backup_withholding hold; overriding the hold pays with 24% withheld. One of: withhold, hold.
- match_qty_tolerance_pctstringrequiredThree-way match quantity tolerance: percent of received-not-invoiced. Both this and match_qty_tolerance must hold (whichever is less). Default 0.
- match_qty_tolerancestringrequiredThree-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
- match_cost_type_tolerancesobject[]requiredPer cost type overrides of the price (match_tolerance_pct/amount) and quantity tolerances; a null or omitted field uses the company value.
- match_cost_type_tolerances[].cost_type_idintegerrequired
- match_cost_type_tolerances[].price_pctstring | null
- match_cost_type_tolerances[].price_amountstring | null
- match_cost_type_tolerances[].qty_pctstring | null
- match_cost_type_tolerances[].qtystring | null
- match_receipt_policystringrequiredWhen bill quantities are checked against receipts: receipt_accrual (default; only with receipt accrual and an RNI account), required (every unit-priced PO line) or off. One of: receipt_accrual, required, off.
- match_require_pobooleanrequiredJob-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
- ach_prenote_requiredbooleanrequiredPayment control (manage_grants to change): live ACH to a vendor or employee account needs a prenote settled at least three banking days (Nacha Rules 2.6); otherwise 409 ach_prenote_required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/settingsUpdate AP settings
Needs manage_coa. Changing a payment control (approval_bands, bank_change_hold_days, ach_company_id, ach_destination_routing) also needs manage_grants (an accounting owner); otherwise 403 control_setting. Resending a control's current value is not a change. Control changes are audited with before and after values. bank_change_hold_days is at least 3. cash_account_id must be the GL account of an active, non-card bank account; routing, account number and check numbers live on that bank account. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- ap_settingsobjectrequired
- ap_settings.approval_bandsobject[]
- ap_settings.approval_bands[].minstringrequired
- ap_settings.approval_bands[].approvalsintegerrequired
- ap_settings.approval_bands[].final_rolestring | null
- ap_settings.bank_change_hold_daysintegerVendor bank-change cool-off in days; never below 3. Changing it needs manage_grants.
- ap_settings.backup_withholding_policystringOne of: withhold, hold.
- ap_settings.match_qty_tolerance_pctstringThree-way match quantity tolerance: percent of received-not-invoiced. Both this and match_qty_tolerance must hold (whichever is less). Default 0.
- ap_settings.match_qty_tolerancestringThree-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
- ap_settings.match_cost_type_tolerancesobject[]Per cost type overrides of the price (match_tolerance_pct/amount) and quantity tolerances; a null or omitted field uses the company value.
- ap_settings.match_cost_type_tolerances[].cost_type_idintegerrequired
- ap_settings.match_cost_type_tolerances[].price_pctstring | null
- ap_settings.match_cost_type_tolerances[].price_amountstring | null
- ap_settings.match_cost_type_tolerances[].qty_pctstring | null
- ap_settings.match_cost_type_tolerances[].qtystring | null
- ap_settings.match_receipt_policystringWhen bill quantities are checked against receipts: receipt_accrual (default; only with receipt accrual and an RNI account), required (every unit-priced PO line) or off. One of: receipt_accrual, required, off.
- ap_settings.match_require_pobooleanJob-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
- ap_settings.ach_prenote_requiredboolean
Response · 200 · object
- over_commitment_actionstringrequired
- match_tolerance_pctstringrequired
- match_tolerance_amountstringrequiredMoney, 2 dp
- receipt_accrualbooleanrequired
- discount_posting_modestringrequired
- bank_change_hold_daysintegerrequired
- lien_waiver_modestringrequired
- approval_bandsobject[]required
- approval_bands[].minstringrequired
- approval_bands[].approvalsintegerrequired
- approval_bands[].final_rolestring | null
- rni_account_idinteger | nullrequired
- backup_withholding_account_idinteger | nullrequired
- cash_account_idinteger | nullrequiredDefault pay-from: the GL account of an active, non-card bank account (banking). Routing, account number and check numbering come from that bank account.
- ach_company_idstring | nullrequired
- ach_company_namestring | nullrequired
- ach_destination_routingstring | nullrequired
- ach_destination_namestring | nullrequired
- prompt_pay_daysinteger | nullrequired
- updated_atstring (date-time)required
- backup_withholding_policystringrequiredhold: payments subject to backup withholding (no TIN, or past a B notice's withholding date) are also put on a backup_withholding hold; overriding the hold pays with 24% withheld. One of: withhold, hold.
- match_qty_tolerance_pctstringrequiredThree-way match quantity tolerance: percent of received-not-invoiced. Both this and match_qty_tolerance must hold (whichever is less). Default 0.
- match_qty_tolerancestringrequiredThree-way match quantity tolerance as an absolute quantity. Default 0 (no quantity tolerance).
- match_cost_type_tolerancesobject[]requiredPer cost type overrides of the price (match_tolerance_pct/amount) and quantity tolerances; a null or omitted field uses the company value.
- match_cost_type_tolerances[].cost_type_idintegerrequired
- match_cost_type_tolerances[].price_pctstring | null
- match_cost_type_tolerances[].price_amountstring | null
- match_cost_type_tolerances[].qty_pctstring | null
- match_cost_type_tolerances[].qtystring | null
- match_receipt_policystringrequiredWhen bill quantities are checked against receipts: receipt_accrual (default; only with receipt accrual and an RNI account), required (every unit-priced PO line) or off. One of: receipt_accrual, required, off.
- match_require_pobooleanrequiredJob-coded bill lines with no purchase order or subcontract are no_po exceptions. Default false.
- ach_prenote_requiredbooleanrequiredPayment control (manage_grants to change): live ACH to a vendor or employee account needs a prenote settled at least three banking days (Nacha Rules 2.6); otherwise 409 ach_prenote_required.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"ap_settings": {}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/tie_outAP subledger tie-out
AP open items and retainage held vs every accounts payable and retainage payable account (the same controls the ap_aging report and period close use), for one entity_id inside the grant (404 outside it) or every entity the grant allows. Reports differences; never repairs. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- as_ofstring (date)query
- entity_idintegerqueryOne entity inside the caller's grant; default every entity the grant allows.
Response · 200 · object
- as_ofstring (date)required
- apobjectrequired
- ap.subledgerstringrequiredMoney, 2 dp
- ap.controlstringrequiredMoney, 2 dp
- ap.differencestringrequiredMoney, 2 dp
- retainageobjectrequired
- retainage.subledgerstringrequiredMoney, 2 dp
- retainage.controlstringrequiredMoney, 2 dp
- retainage.differencestringrequiredMoney, 2 dp
- in_balancebooleanrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/tie_out" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/exportExport an IRS bulk TIN Matching request file
Builds the IRS e-Services bulk TIN Matching .txt file (Pub 2108 Section 11: TIN TYPE;TIN;NAME;ACCOUNT NUMBER, TIN type 1 = EIN, 2 = SSN, 3 = unknown, at most 100,000 pairs) for every 1099 vendor with a TIN. The account number field is the vendor id so the result file maps back. Vendors without a TIN are listed in skipped. TINs are decrypted, so it needs manage_vendor_banking; exports are rate-limited and audited (tin_match_exported). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Response · 200 · object
- filenamestringrequired
- recordsintegerrequired
- textstringrequired
- skippedobject[]required
- skipped[].vendor_idinteger
- skipped[].reasonstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/tin_matching/export" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/tin_matching/importImport IRS bulk TIN Matching results
Reads the IRS result file (each request record with its indicator 0-8 appended) and stores the indicator on the vendor (tin_match_code). Codes 1 (missing or not 9 digits), 2 (not issued) and 3 (name/TIN mismatch) put the vendor's bills on a tin_mismatch payment hold; 0, 6, 7 and 8 are matches; 4 and 5 mean resubmit. A record whose TIN no longer ends like the vendor's TIN on file is skipped as stale_tin; an unknown account is skipped as unknown_vendor. Any unreadable line rejects the whole file with 422 invalid_tin_match_file. Needs manage_vendor_banking; each result is audited (tin_match_result). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- tin_matchingobjectrequired
- tin_matching.textstringrequired
- tin_matching.matched_atstring (date)required
Response · 200 · object
- appliedobject[]required
- applied[].vendor_idinteger
- applied[].codeinteger
- applied[].statusstringOne of: matched, mismatch, resubmit.
- applied[].holdboolean
- skippedobject[]required
- skipped[].lineinteger
- skipped[].accountstring
- skipped[].reasonstringOne of: unknown_vendor, stale_tin.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace422Validation failed, no vendor needs this form, a payee TIN, name or address is missing, the template is missing, for another form or has an unknown required column, or a corrected return was requested
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/tin_matching/import" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"tin_matching": {
"text": "string",
"matched_at": "2026-11-01"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requestsList portal bank change requests
Needs manage_vendor_banking. Last four digits only. Filter status (pending_review, forwarded, rejected). Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- statusstringqueryOne of: pending_review, forwarded, rejected.
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- statusstringrequiredOne of: pending_review, forwarded, rejected.
- routing_last4stringrequired
- account_last4stringrequired
- account_typestringrequiredOne of: checking, savings.
- notestring | null
- forwarded_by_idinteger | null
- forwarded_atstring | null (date-time)
- change_hashstring | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
- party_profile_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/bank_change_requests" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/forwardForward a bank change request for approval
Needs manage_vendor_banking and step-up. Puts the vendor's numbers into the party profile's pending sensitive change with the caller as requester (the existing two-person bank change approval): a different manage_vendor_banking user must approve it with step-up (POST party_profiles/{id}/sensitive_change), the forwarder cannot. The vendor needs an accounting profile (409 no_profile). The request's sealed numbers are cleared. 409 not_pending. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestring | null
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- statusstringrequiredOne of: pending_review, forwarded, rejected.
- routing_last4stringrequired
- account_last4stringrequired
- account_typestringrequiredOne of: checking, savings.
- notestring | null
- forwarded_by_idinteger | null
- forwarded_atstring | null (date-time)
- change_hashstring | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
- party_profile_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/bank_change_requests/1/forward" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"review": {}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/bank_change_requests/{id}/rejectReject a bank change request
Needs manage_vendor_banking and a note. The sealed numbers are discarded. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- statusstringrequiredOne of: pending_review, forwarded, rejected.
- routing_last4stringrequired
- account_last4stringrequired
- account_typestringrequiredOne of: checking, savings.
- notestring | null
- forwarded_by_idinteger | null
- forwarded_atstring | null (date-time)
- change_hashstring | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
- party_profile_idinteger
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/bank_change_requests/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"review": {
"note": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grantsList vendor portal users
Active and revoked grants. Filter vendor_id. Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- vendor_idintegerquery
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- rolestringrequiredOne of: member, admin.
- emailstringrequired
- namestring
- activebooleanrequired
- granted_atstring (date-time)
- revoked_atstring | null (date-time)
- revocation_notestring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/grants" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/grants/{id}/revokeRevoke a vendor portal user's access
Needs ap_approve and a note. Every later portal request of that grant is refused. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- revokeobjectrequired
- revoke.notestringrequired
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- rolestringrequiredOne of: member, admin.
- emailstringrequired
- namestring
- activebooleanrequired
- granted_atstring (date-time)
- revoked_atstring | null (date-time)
- revocation_notestring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/grants/1/revoke" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"revoke": {
"note": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsList vendor portal invitations
Filter vendor_id. Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- vendor_idintegerquery
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- emailstringrequired
- namestring
- rolestringrequiredOne of: member, admin.
- expires_atstring (date-time)
- accepted_atstring | null (date-time)
- revoked_atstring | null (date-time)
- revocation_notestring | null
- created_by_idinteger
- created_atstring (date-time)
- statusstringrequiredOne of: pending, accepted, revoked, expired.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/invitations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitationsInvite a user to a vendor's portal
Needs ap_approve; an admin role (may request bank changes) also needs manage_vendor_banking and step-up. The portal must be enabled (409 portal_disabled). The response carries the one-time secret (43 characters, single use, 7 days); it is stored only as a hash and never shown again. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- invitationobjectrequired
- invitation.vendor_idintegerrequired
- invitation.emailstring (email)required
- invitation.namestringrequired
- invitation.rolestringOne of: member, admin.
Response · 201 · object
- idintegerrequired
- vendor_idintegerrequired
- emailstringrequired
- namestring
- rolestringrequiredOne of: member, admin.
- expires_atstring (date-time)
- accepted_atstring | null (date-time)
- revoked_atstring | null (date-time)
- revocation_notestring | null
- created_by_idinteger
- created_atstring (date-time)
- statusstringrequiredOne of: pending, accepted, revoked, expired.
- secretstringrequiredThe one-time activation secret. Shown only in this response; deliver it to the invitee out of band.
- activation_urlstring
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/invitations" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"invitation": {
"vendor_id": 1,
"email": "string",
"name": "string"
}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/invitations/{id}/revokeRevoke a pending invitation
Needs ap_approve and a note. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- revokeobjectrequired
- revoke.notestringrequired
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- emailstringrequired
- namestring
- rolestringrequiredOne of: member, admin.
- expires_atstring (date-time)
- accepted_atstring | null (date-time)
- revoked_atstring | null (date-time)
- revocation_notestring | null
- created_by_idinteger
- created_atstring (date-time)
- statusstringrequiredOne of: pending, accepted, revoked, expired.
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/invitations/1/revoke" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"revoke": {
"note": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissionsList portal compliance submissions
COIs and lien waivers uploaded through the portal. Filter status (pending, accepted, rejected). Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- statusstringqueryOne of: pending, accepted, rejected.
Response · 200 · object[]
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- kindstringrequiredOne of: coi, lien_waiver.
- statusstringrequiredOne of: pending, accepted, rejected.
- detailsobject
- fileobjectrequired
- file.namestring
- file.content_typestring
- file.size_bytesinteger
- file.sha256string
- file.scan_statusstring
- file.download_urlstring | null
- compliance_idinteger | null
- lien_waiver_idinteger | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/submissions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/acceptAccept a portal compliance submission
Needs ap_enter. Creates the COI compliance record or the lien waiver from the vendor's statement (a waiver's project, payment and received date may be corrected), copies the file onto it and closes the submission. Until then it counts toward nothing. 409 not_pending. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestring
- review.project_idinteger | null
- review.payment_idinteger | null
- review.received_atstring (date)
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- kindstringrequiredOne of: coi, lien_waiver.
- statusstringrequiredOne of: pending, accepted, rejected.
- detailsobject
- fileobjectrequired
- file.namestring
- file.content_typestring
- file.size_bytesinteger
- file.sha256string
- file.scan_statusstring
- file.download_urlstring | null
- compliance_idinteger | null
- lien_waiver_idinteger | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/submissions/1/accept" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"review": {}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendor_portal/submissions/{id}/rejectReject a portal compliance submission
Needs ap_enter and a note the vendor sees. 409 not_pending. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- reviewobjectrequired
- review.notestringrequired
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- portal_grant_idinteger
- kindstringrequiredOne of: coi, lien_waiver.
- statusstringrequiredOne of: pending, accepted, rejected.
- detailsobject
- fileobjectrequired
- file.namestring
- file.content_typestring
- file.size_bytesinteger
- file.sha256string
- file.scan_statusstring
- file.download_urlstring | null
- compliance_idinteger | null
- lien_waiver_idinteger | null
- reviewed_by_idinteger | null
- reviewed_atstring | null (date-time)
- review_notestring | null
- created_atstring (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company409Conflict (state guard)422Validation failed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendor_portal/submissions/1/reject" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"review": {
"note": "string"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendorsList AP vendors
Vendors with an accounting profile: compliance status, open balance and retainage held. Requires the accounting:read scope. Entity-wide: a project-scoped (project_manager_view) grant gets 403.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- searchstringquery
Response · 200 · object[]
- vendor_idintegerrequired
- namestring | nullrequired
- is_1099booleanrequired
- w9_statusstringrequired
- payment_methodstringrequired
- compliance_holdbooleanrequired
- coi_expires_atstring | null (date)required
- coi_expiredbooleanrequired
- stop_paybooleanrequired
- open_balancestringrequiredMoney, 2 dp
- retainage_heldstringrequiredMoney, 2 dp
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}Show an AP vendor
The path id is the core vendor id. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- vendor_idintegerrequired
- namestringrequired
- profile_idinteger | nullrequired
- is_1099booleanrequired
- w9_statusstring | nullrequired
- compliance_holdbooleanrequired
- complianceobject[]required
- compliance[].idintegerrequired
- compliance[].vendor_idintegerrequired
- compliance[].kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- compliance[].referencestring | nullrequired
- compliance[].effective_atstring | null (date)required
- compliance[].expires_atstring | null (date)required
- compliance[].activebooleanrequired
- compliance[].notesstring | nullrequired
- compliance[].created_atstring (date-time)required
- lien_waiversobject[]required
- lien_waivers[].idintegerrequired
- lien_waivers[].vendor_idintegerrequired
- lien_waivers[].project_idinteger | nullrequired
- lien_waivers[].partystringrequired
- lien_waivers[].kindstringrequired
- lien_waivers[].scopestringrequired
- lien_waivers[].payment_nointegerrequired
- lien_waivers[].through_datestring | null (date)required
- lien_waivers[].amountstring | nullrequired
- lien_waivers[].received_atstring (date)required
- lien_waivers[].created_atstring (date-time)required
- lien_waivers[].payment_idinteger | nullrequired
- billsobject[]required
- bills[].idintegerrequired
- bills[].numberstringrequired
- bills[].kindstringrequiredOne of: bill, credit.
- bills[].statusstringrequiredOne of: draft, pending_approval, posted, void.
- bills[].vendor_idintegerrequired
- bills[].vendor_namestring | nullrequired
- bills[].entity_idintegerrequired
- bills[].invoice_numberstring | nullrequired
- bills[].invoice_datestring (date)required
- bills[].posting_datestring (date)required
- bills[].due_datestring (date)required
- bills[].term_idinteger | nullrequired
- bills[].discount_percentstring | nullrequiredRate/quantity, 6 dp
- bills[].discount_datestring | null (date)required
- bills[].memostring | nullrequired
- bills[].totalstringrequiredMoney, 2 dp
- bills[].retainage_amountstringrequiredMoney, 2 dp
- bills[].use_tax_amountstringrequiredMoney, 2 dp
- bills[].tax_code_idinteger | nullrequired
- bills[].open_amountstringrequiredMoney, 2 dp
- bills[].retainage_openstringrequiredMoney, 2 dp
- bills[].paid_amountstringrequiredMoney, 2 dp
- bills[].retainage_releasedstringrequiredMoney, 2 dp
- bills[].commitment_typestring | nullrequired
- bills[].commitment_idinteger | nullrequired
- bills[].requisition_idinteger | nullrequired
- bills[].direct_cost_idinteger | nullrequired
- bills[].pay_when_paid_pay_app_idinteger | nullrequired
- bills[].pay_when_paid_modestring | nullrequired
- bills[].off_rent_datestring | null (date)required
- bills[].billed_throughstring | null (date)required
- bills[].matchobject | nullrequired
- bills[].hold_overridesobject[]required
- bills[].revisionintegerrequired
- bills[].prepared_by_idintegerrequired
- bills[].last_edited_by_idintegerrequired
- bills[].contributor_idsinteger[]requiredEvery user who created or edited the bill. None of them may approve it, override its holds or release its payment.
- bills[].submitted_atstring | null (date-time)required
- bills[].approved_atstring | null (date-time)required
- bills[].entry_idinteger | nullrequired
- bills[].voided_atstring | null (date-time)required
- bills[].void_entry_idinteger | nullrequired
- bills[].void_reasonstring | nullrequired
- bills[].created_atstring (date-time)required
- bills[].updated_atstring (date-time)required
- bills[].linesobject[]
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsList attachments on a vendor
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/attachmentsAttach a file to a vendor
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs ap_enter and the parent's entity scope. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationGet a vendor's remittance and capture settings
The remittance advice email and the sender addresses that identify the vendor in the capture inbox. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Response · 200 · object
- vendor_idintegerrequired
- remittance_emailstring | null
- sender_addressesstring[]required
- updated_atstring | null (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/automation" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/automationUpdate a vendor's remittance and capture settings
Needs ap_enter. Audited. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
Request body
- vendor_automationobjectrequired
- vendor_automation.remittance_emailstring | null (email)
- vendor_automation.sender_addressesstring[]
Response · 200 · object
- vendor_idintegerrequired
- remittance_emailstring | null
- sender_addressesstring[]required
- updated_atstring | null (date-time)
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/automation" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"vendor_automation": {}
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/complianceRecord a compliance document
COI, W-9, license, prequalification or stop-pay (stop-pay needs ap_approve). A newer COI clears an expired-COI hold. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- complianceobjectrequired
- compliance.kindstringrequired
- compliance.referencestring | null
- compliance.effective_atstring | null (date)
- compliance.expires_atstring | null (date)
- compliance.notesstring | null
Response · 201 · object
- idintegerrequired
- vendor_idintegerrequired
- kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- referencestring | nullrequired
- effective_atstring | null (date)required
- expires_atstring | null (date)required
- activebooleanrequired
- notesstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/compliance" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"compliance": {
"kind": "string"
}
}'Accounting / Accounts Payable
PATCH/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}Lift or reinstate a compliance record
Needs ap_approve. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- compliance_idintegerpathrequired
Request body
- complianceobjectrequired
- compliance.activebooleanrequired
Response · 200 · object
- idintegerrequired
- vendor_idintegerrequired
- kindstringrequiredOne of: coi, w9, license, prequalification, stop_pay.
- referencestring | nullrequired
- effective_atstring | null (date)required
- expires_atstring | null (date)required
- activebooleanrequired
- notesstring | nullrequired
- created_atstring (date-time)required
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/compliance/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"compliance": {
"active": true
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}/attachmentsList attachments on a vendor compliance record (COI, W-9, license)
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- compliance_idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/compliance/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/compliance/{compliance_id}/attachmentsAttach a file to a vendor compliance record (COI, W-9, license)
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs ap_enter and the parent's entity scope. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- compliance_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/compliance/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waiversRecord a lien waiver received
party is 'vendor' or a lower-tier party name; payment_no is the vendor's payment sequence on the project. Give payment_id (a posted AP payment to this vendor) for an unconditional waiver: the waiver then covers that payment only (a voided payment never shifts it), payment_no is derived when omitted, and a waiver whose amount is below the payment's net amount on the project is recorded but does not clear the lien-waiver hold. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- lien_waiverobjectrequired
- lien_waiver.project_idinteger | null
- lien_waiver.partystring
- lien_waiver.kindstringrequired
- lien_waiver.scopestringrequired
- lien_waiver.payment_nointegerRequired unless payment_id is given
- lien_waiver.through_datestring | null (date)
- lien_waiver.amountstring | null
- lien_waiver.received_atstring (date)required
- lien_waiver.payment_idinteger | nullPosted AP payment the waiver covers
Response · 201 · object
- idintegerrequired
- vendor_idintegerrequired
- project_idinteger | nullrequired
- partystringrequired
- kindstringrequired
- scopestringrequired
- payment_nointegerrequired
- through_datestring | null (date)required
- amountstring | nullrequired
- received_atstring (date)required
- created_atstring (date-time)required
- payment_idinteger | nullrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, segregation of duties, wrong company, or read-only workspace404Not found in this company422Validation failed or the ledger refused the change
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/lien_waivers" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"lien_waiver": {
"kind": "string",
"scope": "string",
"received_at": "2026-11-01"
}
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsList attachments on a lien waiver
Oldest first. Needs view_ledger and the parent's entity scope. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- waiver_idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/lien_waivers/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/vendors/{id}/lien_waivers/{waiver_id}/attachmentsAttach a file to a lien waiver
Multipart upload (one file part, allow-listed type, up to MAX_UPLOAD_BYTES). Allowed after posting: attachments are not ledger data. Writes an attachment_added audit event on the parent in the same transaction. Needs ap_enter and the parent's entity scope. Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- idintegerpathrequired
- waiver_idintegerpathrequired
- Idempotency-KeystringheaderClient retry key (a UUID is recommended); see the idempotency guide. The first successful response is stored and replayed (same status and body, header Idempotent-Replayed: true) for a repeat with the same key, body and caller; the same key with a different body or caller, or while the first request is still running, is 409. The key is marked committed in the same database transaction as the change, so a retry after a crash or timeout between commit and response replays instead of answering 409. A failed request frees the key. Keys are kept 30 days. On routes that take a body request_key (AR invoices, receipts, cash applications, reversals and deposits; payroll remittances) the header stands in for a missing request_key (a non-UUID key is mapped to a stable UUID) and a request_key that differs from it is 422. Strongly recommended: without it a retried POST can create a second document.
Request body
- filestring (binary)required
Response · 201 · object
- idintegerrequired
- doc_typestringrequiredOne of: journal_entry, ap_bill, vendor, ap_compliance, ap_lien_waiver, ar_invoice, ar_receipt, bank_transaction, fixed_asset, wip_snapshot, account_rec, policy_signoff.
- doc_idintegerrequired
- namestringrequired
- content_typestringrequired
- size_bytesintegerrequired
- sha256stringrequired
- uploaded_byobjectrequired
- uploaded_by.idintegerrequired
- uploaded_by.namestring | nullrequired
- created_atstring (date-time)required
- download_urlstringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, outside the parent record's entity scope, wrong company, or read-only workspace404Not found in this company409Idempotency-Key reused for a different request or still in progress413Request body too large422Missing file, empty file, too large, or a type that is not allowed
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/vendors/1/lien_waivers/1/attachments" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"file": "string"
}'Accounting / Accounts Payable
GET/rest/v1.0/companies/{company_id}/accounting/ap/virtual_cardsList virtual card payments
One single-use card per virtual card payment (last four digits only; card numbers are never stored), with issue and settlement state. Limited to the caller's entities. Filter status (comma-separated). Paginated. Requires the accounting:read scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
- pageintegerquery
- per_pageintegerquery
- statusstringquery
Response · 200 · object[]
- idintegerrequired
- payment_idintegerrequired
- entity_idinteger
- vendorobject
- vendor.idinteger
- vendor.namestring | null
- providerstring
- statusstringrequiredOne of: pending_issue, issued, issue_failed, settled, settlement_mismatch, canceled.
- last4string | null
- exp_monthinteger | null
- exp_yearinteger | null
- amountstringrequired
- currencystringrequired
- issued_atstring | null (date-time)
- settlement_idstring | null
- settled_amountstring | null
- settled_onstring | null (date)
- bank_transaction_idinteger | null
- errorstring | null
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace422Validation failed
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/virtual_cards" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"Accounting / Accounts Payable
POST/rest/v1.0/companies/{company_id}/accounting/ap/virtual_cards/sync_settlementsSync virtual card settlements
Needs bank_reconcile. Pulls the provider's settlements and posts each once (the settlement id is unique): a withdrawal on the funding bank account, Dr clearing / Cr bank, matched to the one unmatched imported statement line of that amount within 5 days when there is one. A settlement of a different amount, or of a canceled card, is recorded as settlement_mismatch and not posted. Only a fake provider exists (no network call; refused in production). Requires the accounting:write scope.
Parameters
- company_idintegerpathrequiredCompany id; must be the token's company
Request body
- syncobject
Response · 200 · object
- settledintegerrequired
- matchedintegerrequired
- mismatchedintegerrequired
- skippedintegerrequired
- blockedintegerSettlements the ledger refused (for example dated in a closed period). Nothing was recorded for them; the next sync retries them, and the other settlements still post.
- errorsobject[]
- errors[].settlement_idstringrequired
- errors[].messagestringrequired
Errors
401Missing or invalid bearer token403No accounting access, missing permission, step-up or MFA required, wrong company, or read-only workspace404Not found in this company422Validation failed503No usable card provider
Example request
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/accounting/ap/virtual_cards/sync_settlements" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"sync": {}
}'